SMS Integration (Twilio)

Connect Twilio to Outeract for global SMS messaging with delivery tracking and MMS support.

Overview

Prerequisites

• Twilio account (sign up)
• Twilio phone number
• Account SID and Auth Token

Setup Guide

Step 1: Get Twilio Credentials

1. Log in to Twilio Console
2. On the dashboard, find:
   • Account SID (starts with AC)
   • Auth Token (click to reveal)
3. Copy both values

Step 2: Get a Phone Number

1. In Twilio Console, go to Phone Numbers → Manage → Buy a number
2. Search for a number with SMS capability
3. Purchase the number
4. Note the phone number (E.164 format: +14155551234)

Step 3: Create Platform Connection

mutation {
  createPlatformConnection(
    platformName: SMS
    name: "Twilio SMS"
    config: {
      account_sid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      auth_token: "your-auth-token"
      phone_number: "+14155551234"
    }
  ) {
    id
    webhookUrl
  }
}

Step 4: Configure Twilio Webhook

1. In Twilio Console, go to Phone Numbers → Manage → Active numbers
2. Click your number
3. Under Messaging, set:
   • A MESSAGE COMES IN: Webhook, <YOUR_WEBHOOK_URL>, HTTP POST

Step 5: Test the Connection

Send a text message to your Twilio number and verify it appears in Outeract.

Supported Features

Message Types

Delivery Status

SMS supports delivery tracking:

• queued - Message queued at Twilio
• sent - Sent to carrier
• delivered - Delivered to device
• failed - Delivery failed

Sending Messages

Basic SMS

mutation {
  sendMessage(
    platformConnectionId: "pc_sms_123"
    recipientUserId: "user-uuid"
    message: "Hello from Outeract!"
  ) {
    id
    eventTypeName
  }
}

MMS with Image

mutation {
  sendMessage(
    platformConnectionId: "pc_sms_123"
    recipientUserId: "user-uuid"
    message: "Check out this photo!"
    fileIds: ["file_xyz789"]
  ) {
    id
  }
}

**Note**: MMS requires an MMS-enabled phone number and is only available in US/Canada.

External ID Format

SMS uses E.164 phone number format:

Always include the + prefix and country code.

Webhook Events

Inbound Message

{
  "event_id": "evt_abc123",
  "event_type": "message.inbound",
  "payload": {
    "message": {
      "text": "Hello!",
      "role": "user"
    },
    "platform": "sms",
    "external_message_id": "SM123..."
  },
  "edges": {
    "sent_by": {
      "external_id": "+14155559999"
    }
  }
}

Delivery Status Update

{
  "event_id": "evt_xyz789",
  "event_type": "message.status",
  "payload": {
    "status": "delivered",
    "external_message_id": "SM123..."
  }
}

Message Concatenation

SMS messages longer than 160 characters are automatically split:

Twilio handles concatenation automatically but charges per segment.

Rate Limits

Troubleshooting

“Invalid phone number”

• Ensure E.164 format (+ prefix)
• Verify country code is correct
• Check if number is a valid mobile number

“Message failed to send”

• Check Twilio account balance
• Verify Auth Token is current
• Check if number is SMS-enabled

“Not receiving messages”

• Verify webhook URL is configured in Twilio
• Check webhook URL is publicly accessible
• Ensure webhook is set to POST

“Carrier filtering”

Some carriers filter messages that appear spammy:

• Avoid URL shorteners
• Use business language
• Register for A2P 10DLC (US)

A2P 10DLC Registration (US)

For business messaging in the US, register for A2P 10DLC:

1. Brand Registration: Register your business with The Campaign Registry
2. Campaign Registration: Register your messaging use case
3. Number Association: Link your phone numbers to the campaign

This improves deliverability and throughput.

International Messaging

Twilio supports SMS to 180+ countries. Rates and regulations vary by country.

Security

Outeract validates Twilio webhooks using request signatures:

1. Takes the URL Twilio was configured with: Outeract’s public BASE_URL plus the webhook path and query (the raw request URL is only a fallback, since behind the load balancer it has the internal scheme)
2. Appends the POSTed form parameters, sorted by name
3. Calculates the HMAC-SHA1 signature using the Auth Token
4. Compares with the X-Twilio-Signature header and rejects the request on a mismatch

Because the signature is keyed on the Auth Token, the connection must use the account’s Auth Token, not an API key secret.

Resources

• Twilio Console
• Twilio SMS Documentation
• E.164 Format Reference
• A2P 10DLC Guide