SMS

Connects a Twilio phone number to an agent flow for SMS. Every incoming text on that number, from any sender, is routed to the same flow.

1. Prerequisites

Three values to collect

1. Account SID (starts with AC)
2. Auth Token
3. Twilio phone number, in E.164 format (e.g. +15558675310)

All three come from the Twilio Console: the Account SID and Auth Token are on the account dashboard, the phone number is whichever SMS-capable number you want to use. Once the integration exists in NeuraFlow (step 2 below), set the number's webhook in Twilio's messaging configuration to:

{BASE_URL}/api/v1/webhooks/sms

Console copy shows the wrong URL

The "Add SMS Number" screen in the console currently displays {BASE_URL}/api/v1/webhooks/channels/sms as the webhook URL to paste into Twilio. That route doesn't exist. The SMS webhook router is mounted at /api/v1/webhooks/sms (no channels/ segment). Use the URL above, not the one shown on screen.

Optionally also set a status callback URL for delivery status (queued / sent / delivered / read / failed / undelivered):

{BASE_URL}/api/v1/webhooks/sms/status

2. Configuration

Three console routes:

Route	Purpose
/channels/sms	List the organization's SMS integrations
/channels/sms/create	Create an integration
/channels/sms/{id}/edit	Reconfigure or disable it

Create

/channels/sms/create shows the (incorrect, see above) webhook URL in an on-screen alert, then a single card:

Field	Required	Placeholder
Twilio Phone Number	Yes	+15558675310
Account SID	Yes	ACXXXXXXXX...
Auth Token	Yes	Auth Token
Friendly Name	No	e.g. Support Line
Agent Flow	Yes	Select an agent flow

If the org has no agent flows, an inline warning replaces normal validation and links to Create an Agent Flow (/agent-builder/create); the button (labelled Add Number, not "Create" or "Save") is disabled until at least one flow exists.

Add Number validates client-side in order ("Phone number is required.", "Account SID is required.", "Auth Token is required.", "Agent Flow is required."), then calls POST /channels/sms/integrations with all five fields plus the current organization_id. On success it toasts "SMS integration created successfully!" and navigates to the edit page. On failure the toast text is the server's detail message directly (not a separate description line, unlike the edit screen below), falling back to "Failed to create SMS integration" if the server sent nothing.

Edit

/channels/sms/{id}/edit has three cards, no tabs, more than WhatsApp's two.

Status: Integration Enabled toggle, folded into the same Save Changes call as everything else.

Twilio Configuration:

Field	Required	Notes
Twilio Phone Number	Yes
Account SID	Yes
Auth Token	No	Always loads blank. Leave blank to keep the existing one
Friendly Name	No	Shown in the entity switcher and page title in place of the phone number when set

Agent Configuration: Agent Flow only.

Save Changes validates "Phone number is required.", "Account SID is required.", "Agent Flow is required." (Auth Token not required here), then calls PUT /channels/sms/integrations/{id}, omitting auth_token from the request if it's still blank. On success it toasts "SMS integration saved successfully." and clears the Auth Token field. On failure it toasts "Failed to save configuration." with the server's detail as the description.

3. Other

Incoming messages are matched to an integration by the Twilio To number, so one webhook URL serves every SMS integration across every organization. Empty messages are acknowledged and dropped.

Unlike WhatsApp, Twilio request signature verification is enforced here: an invalid X-Twilio-Signature gets a 403 and the message is never processed.