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"
    toExternalId: "+14155559999"
    message: "Hello from Outeract!"
  ) {
    id
    status {
      success
      externalMessageId
    }
  }
}

MMS with Image#

mutation {
  sendMessage(
    platformConnectionId: "pc_sms_123"
    toExternalId: "+14155559999"
    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. Constructs validation URL from request
2. Calculates HMAC-SHA1 signature using Auth Token
3. Compares with X-Twilio-Signature header
4. Rejects invalid requests

Resources#

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