Twilio WhatsApp Integration Guide

Twilio WhatsApp + UptimeObserver Benefits

Integrating UptimeObserver with Twilio's WhatsApp Business API enables real-time WhatsApp notifications when your monitors go down or come back up. This integration uses webhooks to send alerts directly to WhatsApp using Twilio's messaging service, providing a familiar and widely-used communication channel for critical alerts.

Note

This integration is available on all UptimeObserver plans.

Cost Notice

WhatsApp Business API usage through Twilio incurs costs for both Twilio and Meta (WhatsApp). Charges apply per conversation initiated. Please review Twilio's WhatsApp pricing before implementing this integration to understand the costs involved.

Support

If you need help with this integration please reach out to us using the "Need Help?" button on the bottom right corner or send us an email at support@uptimeobserver.com.

Prerequisites

Before setting up this integration, you'll need:

A Twilio account with WhatsApp Business API access (sign up at twilio.com)
Your Twilio Account SID
Your Twilio Auth Token
A WhatsApp-enabled Twilio phone number (in E.164 format, e.g., +14155551234)
The recipient WhatsApp phone number(s) to receive alerts (in E.164 format)
At least one approved WhatsApp message template

Getting Your Twilio Credentials

Log in to your Twilio Console
Your Account SID and Auth Token are displayed on the console dashboard
Keep these credentials secure - you'll use them for authentication

WhatsApp Business Setup

To use WhatsApp with Twilio in production, you need to complete the following steps:

Apply for WhatsApp Business API access through your Twilio Console
Complete Meta (Facebook) approval process - typically takes 1-3 business days
Set up your WhatsApp Business Profile with business information
Obtain a WhatsApp-enabled phone number from Twilio or enable WhatsApp on an existing Twilio number

For detailed setup instructions, see Twilio's WhatsApp Quickstart Guide.

Twilio Sandbox for WhatsApp

Twilio provides a WhatsApp Sandbox for testing purposes. While this documentation focuses on production setup, you can use the Sandbox for initial testing without full Business API approval. Note that Sandbox has limitations including required opt-in messages and Twilio branding.

E.164 Phone Number Format with WhatsApp Prefix

Phone numbers must be in E.164 format with the whatsapp: prefix: whatsapp:+[country code][number]

Examples: - US: whatsapp:+14155551234 - UK: whatsapp:+447911123456 - India: whatsapp:+919876543210

Basic Authentication Setup

For this integration, you'll use Basic Authentication with Twilio's API:

Username: Your Twilio Account SID
Password: Your Twilio Auth Token

Creating WhatsApp Message Templates

WhatsApp requires pre-approved message templates for business-initiated conversations. This is a requirement by Meta (WhatsApp's parent company) to prevent spam and ensure quality messaging.

Why Templates Are Required

Unlike SMS, you cannot send arbitrary text messages via WhatsApp Business API without using approved templates. All messages sent outside of active 24-hour conversation windows must use a template that Meta has reviewed and approved.

Template Creation Process

Log in to your Twilio Console
Navigate to Messaging → Content Templates → WhatsApp Templates
Click "Create new Template"
Fill in the template details:
1. Template Name: Use a descriptive name (e.g., monitor_down_alert)
2. Language: Select your preferred language
3. Message Content: Write your template using placeholders for variables

Template Approval Process

After submission, Meta reviews templates (typically within 24-48 hours)
Templates must comply with WhatsApp Business Policy
Approved templates receive a Template SID or Content SID for reference
You can check approval status in the Twilio Console

Ready-to-Use Template Examples

Below are three complete template examples you can submit for approval and use immediately with UptimeObserver:

Template 1: Basic Monitor Down Alert

Template Name: monitor_down_basic
Content:

🚨 ALERT: {{1}} is DOWN!

Reason: {{2}}

Check details: {{3}}

Variable Mapping for UptimeObserver: - {{1}} = __MONITOR_FRIENDLY_NAME__ - {{2}} = __INCIDENT_ROOT_CAUSE__ - {{3}} = __INCIDENT_URL__

Template 2: Detailed Monitor Down Alert

Template Name: monitor_down_detailed
Content:

⚠️ MONITOR DOWN ALERT

Monitor: {{1}}
URL: {{2}}
Cause: {{3}}
Status: {{4}}

Incident Details: {{5}}

Variable Mapping for UptimeObserver: - {{1}} = __MONITOR_FRIENDLY_NAME__ - {{2}} = __MONITOR_URL__ - {{3}} = __INCIDENT_ROOT_CAUSE__ - {{4}} = __INCIDENT_STATUS__ - {{5}} = __INCIDENT_URL__

Template 3: Monitor Up Resolution Alert

Template Name: monitor_up_resolution
Content:

✅ RESOLVED: {{1}} is back UP!

Your monitor has recovered and is functioning normally.

Incident resolved: {{2}}

Variable Mapping for UptimeObserver: - {{1}} = __MONITOR_FRIENDLY_NAME__ - {{2}} = __INCIDENT_URL__

Using Templates in Webhooks

Once your templates are approved, you'll use them in the webhook configuration. Instead of sending a plain Body parameter, you'll reference the template and provide values for the placeholders.

Integration Walkthrough

Go to UptimeObserver and log in to your account.
Navigate to the Integrations section from your dashboard.
Select Webhooks from the list of available integration options.
You'll need to create two webhooks:
1. One for declaring an incident (Monitor Down alert)
2. Another for resolving an incident (Monitor Up alert)

1. Incident Webhook Setup

This webhook sends a WhatsApp message when a monitor goes down.

Friendly name: Twilio WhatsApp - Monitor Down
URL: https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json
Replace {AccountSid} with your actual Twilio Account SID
Example: https://api.twilio.com/2010-04-01/Accounts/AC1234567890abcdef1234567890abcdef/Messages.json
HTTP Method: POST
Authentication: Basic Auth
Enter your Twilio Account SID as the username
Enter your Twilio Auth Token as the password
HTTP Body Encoding: application/x-www-form-urlencoded

HTTP Body (using Template 1 - Basic Alert):

From=whatsapp:+14155551234&To=whatsapp:+19165551234&Body=🚨 ALERT: __MONITOR_FRIENDLY_NAME__ is DOWN! Reason: __INCIDENT_ROOT_CAUSE__. Check details: __INCIDENT_URL__

OR using an approved template with ContentSid (recommended for production):

From=whatsapp:+14155551234&To=whatsapp:+19165551234&ContentSid=HXa1b2c3d4e5f6g7h8i9j0&ContentVariables={"1":"__MONITOR_FRIENDLY_NAME__","2":"__INCIDENT_ROOT_CAUSE__","3":"__INCIDENT_URL__"}

Important Configuration Notes

Replace +14155551234 with your WhatsApp-enabled Twilio phone number (From)
Replace +19165551234 with the recipient's WhatsApp phone number (To)
Both numbers must include the whatsapp: prefix
Replace HXa1b2c3d4e5f6g7h8i9j0 with your actual approved template's ContentSid
Ensure phone numbers are in E.164 format
ContentVariables maps template placeholders ({{1}}, {{2}}, etc.) to UptimeObserver variables

Click Save Webhook, then test it using the Test Button 🧪.

2. Resolution Webhook Setup

This webhook sends a WhatsApp message when a monitor comes back up.

Friendly name: Twilio WhatsApp - Monitor Up
URL: https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json
Replace {AccountSid} with your actual Twilio Account SID
Example: https://api.twilio.com/2010-04-01/Accounts/AC1234567890abcdef1234567890abcdef/Messages.json
HTTP Method: POST
Authentication: Basic Auth
Enter your Twilio Account SID as the username
Enter your Twilio Auth Token as the password
HTTP Body Encoding: application/x-www-form-urlencoded

HTTP Body (using Template 3 - Resolution Alert):

From=whatsapp:+14155551234&To=whatsapp:+19165551234&Body=✅ RESOLVED: __MONITOR_FRIENDLY_NAME__ is back UP! Your monitor has recovered and is functioning normally. Incident resolved: __INCIDENT_URL__

OR using an approved template with ContentSid (recommended for production):

From=whatsapp:+14155551234&To=whatsapp:+19165551234&ContentSid=HXz9y8x7w6v5u4t3s2r1q0&ContentVariables={"1":"__MONITOR_FRIENDLY_NAME__","2":"__INCIDENT_URL__"}

Available Variables

You can customize your WhatsApp messages using these UptimeObserver variables:

__MONITOR_FRIENDLY_NAME__ - The name of your monitor
__INCIDENT_URL__ - Direct link to the incident details
__INCIDENT_ROOT_CAUSE__ - The reason for the incident
__INCIDENT_STATUS__ - Current status of the incident
__MONITOR_URL__ - URL being monitored
__MONITOR_ID__ - Unique monitor identifier
__INCIDENT_ID__ - Unique incident identifier

Click Save Webhook, then test it using the Test Button 🧪.

Once completed, your Twilio WhatsApp integration is configured!

3. Add Alerts to Your Monitor

After configuring your webhooks, follow these steps to add alerts to your monitor:

Navigate to your monitor.
Scroll down to the Monitor Alerts section.
Click Add Alert.
Set the following parameters:
1. Alert Type: Webhook
2. Event: Monitor Down
3. Webhook: Select Twilio WhatsApp - Monitor Down
Click Save Changes.
Repeat the process to add another alert:
1. Alert Type: Webhook
2. Event: Monitor Up
3. Webhook: Select Twilio WhatsApp - Monitor Up

Everything is now set up—you'll receive WhatsApp alerts automatically when your monitors go down or come back up!

Testing Your Integration

After saving each webhook, click the Test Button 🧪 next to the webhook.
You should receive a WhatsApp message within a few seconds.
If you don't receive the test WhatsApp message:
Verify your Twilio credentials (Account SID and Auth Token)
Check that phone numbers are in E.164 format with whatsapp: prefix
Ensure your WhatsApp Business Account is approved
Verify the recipient's phone number has WhatsApp installed
If using templates, confirm the template is approved in Twilio Console
Check Twilio's messaging logs in the Twilio Console for delivery status

Troubleshooting

Template Not Approved

Issue: Message fails to send because template is pending or rejected

Solutions:

Check template approval status in Twilio Console → Messaging → Content Templates
Templates typically take 24-48 hours for approval
If rejected, review Meta's feedback and resubmit with modifications
Ensure template category is appropriate (use "UTILITY" for monitoring alerts)
Verify template content complies with WhatsApp Business Policy

Template Variables Mismatch

Issue: Webhook fails with "template variables don't match" error

Solutions:

Ensure the number of variables in ContentVariables matches your template placeholders
Verify variable mapping: {"1":"value1","2":"value2"} corresponds to {{1}} and {{2}}
Check for typos in UptimeObserver variable names (e.g., __MONITOR_FRIENDLY_NAME__)
Confirm you're using the correct ContentSid for the template
Test variable substitution in Twilio Console before deploying

WhatsApp Business Account Not Approved

Issue: Messages fail because WhatsApp Business Account is pending approval

Solutions:

Check approval status in Twilio Console → Messaging → WhatsApp Senders
Meta approval typically takes 1-3 business days but can take longer
Ensure your Business Profile is complete with accurate information
Contact Meta support if approval is delayed beyond 5 business days
Use Twilio Sandbox for WhatsApp for testing while waiting for approval

Phone Number Not WhatsApp-Enabled

Issue: Error indicates the sender phone number doesn't support WhatsApp

Solutions:

Verify your Twilio number is WhatsApp-enabled in Twilio Console → Phone Numbers
Not all Twilio numbers support WhatsApp - check number capabilities
Request WhatsApp enablement for your existing number, or purchase a new WhatsApp-enabled number
Ensure you've completed WhatsApp Business API approval before enabling numbers

Missing `whatsapp:` Prefix

Issue: Messages fail or get sent as SMS instead of WhatsApp

Solutions:

Both From and To fields must include the whatsapp: prefix
Correct format: whatsapp:+14155551234
Incorrect format: +14155551234 (will attempt SMS instead)
Double-check there are no spaces: whatsapp: +1415... is incorrect

Authentication Errors

Issue: Webhook fails with 401 Unauthorized error

Solutions:

Double-check that your Account SID is entered as the Basic Auth username
Verify your Auth Token is entered as the Basic Auth password (not the Account SID)
Ensure there are no extra spaces in the credentials
Regenerate your Auth Token in Twilio Console if it has been compromised
Confirm you're using the correct Account SID in the webhook URL

Message Delivery Failures

Issue: Webhook succeeds but WhatsApp message not received

Solutions:

Verify the recipient's phone number has WhatsApp installed and active
Check that the recipient's phone number is in E.164 format with correct country code
Ensure the recipient hasn't blocked your WhatsApp Business number
Review Twilio's messaging logs in the Console for detailed error messages
Confirm your Twilio account has sufficient credit/active billing
Check if the recipient's region has WhatsApp Business API restrictions

Sandbox vs Production Configuration Errors

Issue: Confusion between Sandbox and Production setup requirements

Solutions:

Sandbox: Requires recipients to send join code first; uses Twilio's shared number; for testing only
Production: Requires approved WhatsApp Business Account; uses your dedicated number; no join code needed
If testing in Sandbox, recipients must send the join code (e.g., "join [word]-[word]") to the Sandbox number first
For production alerts, complete full WhatsApp Business API approval and use your own WhatsApp-enabled number
Don't mix Sandbox and production configurations - they use different phone numbers

Message Not Delivered to Multiple Recipients

Issue: Need to send alerts to multiple WhatsApp recipients

Solutions:

The Twilio Messages API To field only accepts one phone number at a time
Solution: Create separate webhooks for each recipient:
Create additional webhooks with the same configuration but different To phone numbers
Example: Twilio WhatsApp - Monitor Down (John), Twilio WhatsApp - Monitor Down (Jane)
Add all webhooks as separate alerts to your monitor
This approach allows you to customize messages per recipient if needed

How to Uninstall

In UptimeObserver:

Go to UptimeObserver and log in to your account.
Navigate to your monitors and remove the Twilio WhatsApp webhook alerts from the Monitor Alerts section.
Navigate to the Integrations section from your dashboard.
Select Webhooks from the list of available integration options.
Delete the Twilio WhatsApp webhooks.

In Twilio:

No action needed in Twilio - the integration only uses standard API endpoints. However, you may want to:

Review your WhatsApp message templates and delete any that are no longer needed
Check your Twilio phone numbers and release WhatsApp-enabled numbers that aren't being used
Review your Twilio account usage to understand WhatsApp messaging costs incurred
Disable WhatsApp on phone numbers if you're no longer using the service

Twilio WhatsApp Integration Guide

Twilio WhatsApp + UptimeObserver Benefits

Support

Prerequisites

Getting Your Twilio Credentials

WhatsApp Business Setup

Basic Authentication Setup

Creating WhatsApp Message Templates

Why Templates Are Required

Template Creation Process

Template Approval Process

Ready-to-Use Template Examples

Template 1: Basic Monitor Down Alert

Template 2: Detailed Monitor Down Alert

Template 3: Monitor Up Resolution Alert

Using Templates in Webhooks

Integration Walkthrough

1. Incident Webhook Setup

2. Resolution Webhook Setup

3. Add Alerts to Your Monitor

Testing Your Integration

Troubleshooting

Template Not Approved

Template Variables Mismatch

WhatsApp Business Account Not Approved

Phone Number Not WhatsApp-Enabled

Missing whatsapp: Prefix

Authentication Errors

Message Delivery Failures

Sandbox vs Production Configuration Errors

Message Not Delivered to Multiple Recipients

How to Uninstall

In UptimeObserver:

In Twilio:

Missing `whatsapp:` Prefix