Skip to content

Twilio SMS Integration Guide

Overview

Integrating UptimeObserver with Twilio SMS enables real-time SMS notifications when your monitors go down or come back up. This integration uses webhooks to send alerts directly to your phone via Twilio's messaging service.

Note

This integration uses Webhooks on all plans, subject to advertised webhook allowances. Twilio charges separately.

Cost Notice

Twilio charges per SMS message sent. Please review Twilio's pricing before implementing this integration to understand the costs involved.

Prerequisites

Before setting up this integration, you'll need:

  1. A Twilio account (sign up at twilio.com)
  2. Your Twilio Account SID
  3. Your Twilio Auth Token
  4. A Twilio phone number (in E.164 format, e.g., +14155551234)
  5. The recipient phone number(s) to receive alerts (in E.164 format)

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

E.164 Phone Number Format

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

Examples: - US: +14155551234 - UK: +447911123456 - India: +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

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)

Enter raw form values

Paste each body below as one line, with literal + in phone numbers. UptimeObserver URL-encodes form values after substitution; do not pre-encode them. The examples use monitor IDs and generated incident links because an ampersand in a name or root cause would create an extra form field. See body encoding and substitution.

1. Incident Webhook Setup

This webhook sends an SMS when a monitor goes down.

  1. Friendly name: Twilio SMS - 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: 
    From=+14155551234&To=+19165551234&Body=ALERT: Monitor __MONITOR_ID__ is DOWN. Details: __INCIDENT_URL__

Important Configuration Notes

  • Replace +14155551234 with your Twilio phone number (From)
  • Replace +19165551234 with the recipient's phone number (To)
  • SMS messages are limited to 160 characters. Messages exceeding this limit will be split into multiple SMS messages, incurring additional charges.
  • Ensure phone numbers are in E.164 format
  1. Click Save Webhook, then test it using the Test Button 🧪.

2. Resolution Webhook Setup

This webhook sends an SMS when a monitor comes back up.

  1. Friendly name: Twilio SMS - 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: 
    From=+14155551234&To=+19165551234&Body=RESOLVED: Monitor __MONITOR_ID__ is back UP. Incident: __INCIDENT_URL__

Available Variables

You can customize your SMS 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 SMS integration is configured!

Verify Both Messages

  1. Test each saved webhook with the Test button. Check Twilio's messaging logs and the recipient's phone; a successful API response alone does not prove delivery.
  2. Expect the sample monitor ID 54123 and a sample incident link. The test data is the same for both webhooks, so the fixed DOWN and UP text in the bodies distinguishes the messages.
  3. For a full event test, attach both alerts to a dedicated test monitor, let it go Down, then restore it. Confirm one down message and one recovery message with the actual monitor ID and incident link. This sends real SMS 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 SMS - Monitor Down
Monitor Up Twilio SMS - Monitor Up

Then verify both messages, including recipient delivery rather than only the API response.

Troubleshooting

SMS Not Received

Issue: No SMS received after webhook triggers

Solutions: - Incorrect phone number format: Ensure both From and To numbers are in E.164 format (+[country code][number]) - Authentication failure: Verify your Account SID and Auth Token are entered correctly in the Basic Auth fields - Twilio trial account limitations: Trial accounts can only send SMS to verified phone numbers. Upgrade to a paid account or verify recipient numbers in Twilio Console - Insufficient Twilio credit: Check your Twilio account balance - Geographic restrictions: Some countries have restrictions on SMS delivery. Check Twilio's supported countries

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

Message Truncation

Issue: SMS message appears cut off or incomplete

Solutions:

  • SMS messages are limited to 160 characters per segment
  • Messages exceeding 160 characters are split into multiple SMS (each incurring separate charges)
  • Shorten your message template or remove less critical variables

Delayed Message Delivery

Issue: SMS arrives several minutes after the incident

Solutions:

  • SMS delivery times can vary based on carrier and network conditions (typically 1-10 seconds)
  • Check Twilio's status page for any service issues
  • Review Twilio's SMS logs in the console to see when the message was queued vs. delivered
  • Consider geographic distance between Twilio's servers and the recipient's carrier

Message Not Delivered to Multiple Recipients

Issue: Need to send alerts to multiple phone numbers

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 SMS - Monitor Down (John), Twilio SMS - 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 SMS 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 SMS webhooks.

In Twilio:

No action needed in Twilio - the integration only uses standard API endpoints. However, you may want to: - Review your Twilio phone numbers and release any that are no longer needed - Check your Twilio account usage to understand SMS costs incurred

Need Help?

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