Skip to content

Twilio WhatsApp Integration Guide

Overview

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 uses Webhooks on all plans, subject to advertised webhook allowances. Twilio charges separately.

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.

Prerequisites

Before setting up this integration, you'll need:

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

Getting Your Twilio Credentials

  1. Log in to your Twilio Console
  2. Your Account SID and Auth Token are displayed on the console dashboard
  3. 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:

  1. Apply for WhatsApp Business API access through your Twilio Console
  2. Complete Meta (Facebook) approval process - typically takes 1-3 business days
  3. Set up your WhatsApp Business Profile with business information
  4. 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

  1. Log in to your Twilio Console
  2. Navigate to Messaging → Content Templates → WhatsApp Templates
  3. Click "Create new Template"
  4. 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 template examples to submit for approval. Use them only after Twilio shows the content template as approved for WhatsApp. The webhook examples use IDs and fixed text to avoid unsafe free-text substitution.

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 __MONITOR_ID__ - {{2}} = Monitor check failed (fixed text; open the incident for the actual 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 __MONITOR_ID__ - {{2}} = __MONITOR_URL__ - {{3}} = Monitor check failed (fixed text) - {{4}} = Down (fixed text for this template) - {{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 __MONITOR_ID__ - {{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.

Production alerts need approved templates

Use ContentSid and ContentVariables for unattended down/recovery alerts. Arbitrary Body messages are limited to an active 24-hour customer-service window after the recipient messages you; do not rely on that window for scheduled alerts. The Sandbox requires recipients to join and has separate testing restrictions; it is not a substitute for production template approval.

Enter raw form values

Paste each body as one line, with literal whatsapp:+ numbers and unencoded JSON. UptimeObserver URL-encodes form values after variable substitution, so pre-encoded values would be encoded twice. The JSON must already be valid after substitution, and no value may contain a literal &. The examples therefore avoid free-text monitor names and root causes. See body encoding and substitution.

Step-by-Step Setup

  1. Go to UptimeObserver and log in to your account.
  2. Navigate to the Integrations section from your dashboard.
  3. Select Webhooks from the list of available integration options.
  4. 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.

  1. Friendly name: Twilio WhatsApp - Monitor Down
  2. URL: https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json
  3. Replace {AccountSid} with your actual Twilio Account SID
  4. Example: https://api.twilio.com/2010-04-01/Accounts/AC1234567890abcdef1234567890abcdef/Messages.json
  5. HTTP Method: POST
  6. Authentication: Basic Auth
  7. Enter your Twilio Account SID as the username
  8. Enter your Twilio Auth Token as the password
  9. HTTP Body Encoding: application/x-www-form-urlencoded
  10. HTTP Body (using the approved Template 1): 
    From=whatsapp:+14155551234&To=whatsapp:+19165551234&ContentSid=HX00000000000000000000000000000000&ContentVariables={"1":"Monitor __MONITOR_ID__","2":"Monitor check failed","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 HX00000000000000000000000000000000 (a fake example) with the approved down template's Content SID
  • Ensure phone numbers are in E.164 format
  • ContentVariables maps template placeholders ({{1}}, {{2}}, etc.) to UptimeObserver variables
  1. 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.

  1. Friendly name: Twilio WhatsApp - Monitor Up
  2. URL: https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json
  3. Replace {AccountSid} with your actual Twilio Account SID
  4. Example: https://api.twilio.com/2010-04-01/Accounts/AC1234567890abcdef1234567890abcdef/Messages.json
  5. HTTP Method: POST
  6. Authentication: Basic Auth
  7. Enter your Twilio Account SID as the username
  8. Enter your Twilio Auth Token as the password
  9. HTTP Body Encoding: application/x-www-form-urlencoded
  10. HTTP Body (using the approved Template 3; replace the fake SID with your recovery template's SID): 
    From=whatsapp:+14155551234&To=whatsapp:+19165551234&ContentSid=HX11111111111111111111111111111111&ContentVariables={"1":"Monitor __MONITOR_ID__","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__ - Link to the monitor in the dashboard
  • __MONITOR_ID__ - Unique monitor identifier
  • __INCIDENT_ID__ - Unique incident identifier
  1. Click Save Webhook, then test it using the Test Button 🧪.

Once completed, your Twilio WhatsApp integration is configured!

Verify Both Templates

  1. Test both saved webhooks. In Twilio's messaging logs, verify that each request used the correct approved Content SID, that ContentVariables parsed as JSON, and that both From and To retained the whatsapp:+ prefix.
  2. Confirm each message arrives on the recipient's WhatsApp device. Test data uses monitor ID 54123 and a sample incident URL; the webhook test does not simulate a real recovery.
  3. For a real down/recovery test, use a dedicated test monitor and recipient with both alerts attached. Confirm the down and recovery templates arrive even outside a 24-hour customer-service window. This sends real messages and can incur charges.

Enabling Alerts on Monitors

Follow Add an alert to a monitor, using Alert Type → Webhook for both rules:

Event Webhook
Monitor Down Twilio WhatsApp - Monitor Down
Monitor Up Twilio WhatsApp - Monitor Up

Then verify both approved templates, including real recipient delivery outside the customer-service window.

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:

  1. Go to UptimeObserver and log in to your account.
  2. Navigate to your monitors and remove the Twilio WhatsApp webhook alerts from the Monitor Alerts section.
  3. Navigate to the Integrations section from your dashboard.
  4. Select Webhooks from the list of available integration options.
  5. 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

Need Help?

If you need assistance with Twilio WhatsApp integration, reach out using the "Need Help?" button on the bottom right corner or email us at support@uptimeobserver.com.