sunrai · help
Back to SunrAI

Connect Twilio (SMS)

Bring your own Twilio account to enable team-scoped SMS. Each team uses its own number and pays its own Twilio bill.

Updated4 min readintegrations

Bring your own Twilio. Each team connects their own Account SID + Auth Token, picks a default sending number, and sends SMS from inside SunrAI under their own brand and 10DLC registration.

What you'll learn

  • Why Twilio is BYO and what that means for you
  • How to connect your Twilio account
  • What's wired up today and what's coming
  • How inbound replies flow back into SunrAI

Why BYO

SMS regulation in the US (10DLC), carrier filtering, and rate-limit fairness all push towards per-team Twilio. So: every team brings their own Twilio account, their own registered brand, their own phone numbers. SunrAI is the application that uses them — it doesn't pay your bill or share your trust scores with another team's traffic.

Who can connect

Owner or Admin only. Members can see the connection status on the integrations page but cannot edit it. The credentials are encrypted at rest in the twilio_integrations table and are never returned to the browser after connection — only a masked preview.

Steps to connect

  1. Open Integrations → Twilio

    Settings → Integrations → Twilio.

  2. Get your Account SID and Auth Token

    From console.twilio.com, under Account → API keys & tokens, copy the Account SID and the Auth Token.

  3. Paste into SunrAI

    Enter both fields in the Twilio integration card, then click Connect. SunrAI calls the Twilio API once to validate, then encrypts and stores both values.

  4. Pick a default sending number

    From the dropdown of phone numbers active on your Twilio account, choose the default sender. You can also wire additional numbers later through the Channels settings.

  5. Point inbound webhooks at SunrAI

    In your Twilio console, for each phone number you want to use here, set the webhook URLs to:

    • A MESSAGE COMES IN → https://www.sunrai.ai/api/webhooks/sms-inbound
    • STATUS CALLBACK URL → https://www.sunrai.ai/api/webhooks/sms-status

    SunrAI validates each inbound request against your stored auth token — so signature verification is per-team.

What's wired up today

  • Outbound SMS from inside SunrAI — anywhere a contact has a phone number and the user can send messages (project detail, communication log, Buddies inbox drafts)
  • Inbound SMS — replies land on the customer's communication log via the sms-inbound webhook
  • Status callbacks — delivery / failure status updates the message row via the sms-status webhook
  • Per-team client cache with 5-minute TTL (so we don't decrypt your token on every send)

What's not wired up yet

  • Browser dialer for voice calls
  • Call recording + transcription
  • Voicemail drop
  • Conditional routing (e.g. send via Twilio for some teams, GHL for others, based on policy)

These are tracked as a follow-up after the current mega-PR ships.

Cost and compliance

You pay Twilio directly. SunrAI doesn't aggregate or mark up usage. You're responsible for:

  • 10DLC brand and campaign registration (otherwise messages will be filtered)
  • TCPA / consent — collecting and storing opt-ins
  • Opt-out handling — STOP / HELP keywords are standard Twilio behavior; SunrAI honors them and won't re-send to a number that opted out

Disconnecting

Click Disconnect on the integration card. A confirmation dialog asks you to acknowledge:

  1. Outbound sends from SunrAI stop immediately
  2. Inbound webhooks will return 401 for your numbers (so it's worth updating Twilio to point elsewhere or to a dead-letter URL)
  3. The stored credentials are deleted, not just marked inactive

You can reconnect any time with the same or different credentials.

Verify it worked

  • The Twilio card on Integrations shows Connected, with a masked Account SID and the default number you picked
  • Send a test SMS from any customer's communication log — it should reach the recipient and appear as Sent within seconds
  • Reply to the test SMS — the reply appears on the customer's communication log within a minute

Troubleshooting

"Connection failed: Twilio rejected our credentials." — Either the Account SID or Auth Token was copy-pasted with extra whitespace, or the token has been rotated in your Twilio console. Re-copy from Twilio and try again.

"Outbound messages stick at 'queued'." — Check the Twilio Console → Messaging → Logs for the actual error. Most often: an unregistered 10DLC campaign, an invalid number format, or insufficient account balance.

"Inbound replies aren't showing up." — Two checks: (1) the webhook URLs in Twilio console match exactly the URLs above (no trailing slash, https not http), (2) the auth token in Twilio matches the one SunrAI has stored. If you rotated the token, reconnect SunrAI.

Related

← More on Integrations