Skip to content

Twilio SMS Integration Guide

Twilio SMS + UptimeObserver Benefits

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 is available on all UptimeObserver plans.

Cost Notice

Twilio charges per SMS message sent. Please review Twilio's 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:

  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

Integration Walkthrough

  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 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_FRIENDLY_NAME__ is DOWN! Reason: __INCIDENT_ROOT_CAUSE__. 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_FRIENDLY_NAME__ is back UP! Incident resolved: __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__ - URL being monitored
  • __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!

3. Add Alerts to Your Monitor

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

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

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

Testing Your Integration

  1. After saving each webhook, click the Test Button 🧪 next to the webhook.
  2. You should receive an SMS message within a few seconds.
  3. If you don't receive the test SMS:
  4. Verify your Twilio credentials (Account SID and Auth Token)
  5. Check that phone numbers are in E.164 format
  6. Ensure your Twilio account has sufficient credit
  7. Check Twilio's SMS logs in the Twilio Console for delivery status

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