SMS (Twilio)

Sophon connects to SMS using Twilio. You'll create a Twilio account, get a phone number, and configure webhooks so incoming SMS messages are routed to Sophon.

Prerequisites

• A Twilio account (free trial available)
• A Twilio phone number with SMS capability
• A public URL for webhook delivery (or a tunneling tool like ngrok for development)

Step-by-Step Setup

1. Get Your Twilio Credentials

1. Log into the Twilio Console
2. On the dashboard, copy your Account SID (starts with AC)
3. Copy your Auth Token (click to reveal)

2. Get a Phone Number

If you don't have a Twilio number yet:

1. Go to Phone Numbers > Manage > Buy a Number
2. Search for a number with SMS capability
3. Click Buy (trial accounts get one free number)

3. Configure the Webhook

1. Go to Phone Numbers > Manage > Active Numbers
2. Click on your phone number
3. Under Messaging > A message comes in, set:
   • Webhook: https://your-domain.com/api/channels/sms/webhook
   • HTTP Method: POST
4. Click Save

For local development:

ngrok http 8080
# Use: https://xxxx.ngrok.io/api/channels/sms/webhook

4. Configure in Sophon Dashboard

1. Go to Channels and click Add Channel
2. Select SMS (Twilio)
3. Enter the Account SID (AC...)
4. Enter the Auth Token
5. Enter the Twilio Phone Number in E.164 format (e.g., +1234567890)
6. Click Test Connection
7. Click Activate

5. Test It

Send an SMS to your Twilio phone number. Sophon should respond.

Note: On Twilio trial accounts, you can only send SMS to verified phone numbers. Add recipient numbers in the Twilio Console under Phone Numbers > Verified Caller IDs.

Configuration Reference

channels.json Example

{
  "id": "sms-twilio",
  "type": "sms",
  "name": "Sophon SMS",
  "enabled": true,
  "config": {
    "accountSid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "authToken": "<encrypted>",
    "phoneNumber": "+1234567890"
  },
  "routing": {
    "agentId": "default",
    "dmBehavior": "main-session"
  },
  "status": "connected"
}

Limitations

• Text only — SMS does not support images, files, or rich formatting. Consider using WhatsApp Business for media support.
• Message length — SMS messages are limited to 1,600 characters. Longer responses from Sophon will be split into multiple SMS segments.
• Cost — Twilio charges per SMS sent and received. Monitor usage in the Twilio Console.
• International — Sending SMS to international numbers may require additional Twilio configuration and incurs higher costs.

Troubleshooting

• "Authentication error" — The Account SID or Auth Token is wrong. Copy them directly from the Twilio Console dashboard.
• SMS not received by Sophon — Verify the webhook URL is correct and publicly accessible. Check Twilio's Monitor > Logs > Messaging for delivery status.
• "Queue overflow" — Twilio has rate limits per phone number. For high volume, consider upgrading to a Twilio short code or toll-free number.
• Trial account limitations — Trial accounts can only send to verified numbers. Add numbers under Phone Numbers > Verified Caller IDs or upgrade your account.
• Webhook returns 404 — Ensure Sophon is running and the SMS channel is activated. The endpoint /api/channels/sms/webhook must be accessible.