Twilio Messaging

How inbound works

Twilio sends a signed, form-encoded HTTP POST to the connector's webhook. Connic verifies it, prepares the message input, and queues a run for each linked agent. The webhook returns an empty TwiML response; replies are sent separately through an outbound connector.

Inbound and outbound connectors can reuse the saved Twilio connection used by Twilio Voice. A connection stores the Account SID, region, and that region's Auth Token. The channel and sender belong to each connector.

Inbound setup

1. 1

   Prepare the Twilio sender

   Use a messaging-enabled Twilio number or a registered WhatsApp or RCS sender. Clear any existing incoming-message webhook or TwiML app before assigning the sender to Connic. If a Messaging Service contains the sender, set its incoming-message handling to Defer to sender's webhook. For a WhatsApp test, activate the Twilio Sandbox and join it from the test phone.

2. 2

   Create the inbound connector

   Add Twilio Messaging from the connector marketplace and select Inbound. Choose an existing Twilio connection or create one with the Account SID, region, and regional Auth Token. Select the channel, then choose the Twilio sender from the dropdown. Save the connector. Connic automatically registers its incoming-message webhook in Twilio for SMS/MMS numbers and registered WhatsApp and RCS senders. Setup errors appear when saving.

3. 3

   WhatsApp Sandbox only: enter the webhook in Twilio

   The Sandbox requires manual setup because Twilio provides no documented public API for changing its webhook. Select WhatsApp Sandbox in Connic, save, and copy Incoming-message webhook from the connector details. In Twilio's Sandbox settings, paste the exact URL into When a Message Comes in, select HTTP POST, and save. See Twilio's Sandbox webhook instructions.

4. 4

   Link and test the agent

   Link the connector to a deployed agent and keep the connector enabled. Send a message to the configured sender, then inspect the run input. To reply automatically, also create and link an outbound connector using the same Twilio connection, channel, and sender.

When changing senders, Connic configures the new sender and removes the old webhook only if it still points to this connector. Deleting the inbound connector also removes its owned webhook. Sandbox settings must be updated manually when switching away from the Sandbox or deleting its connector. Messaging setup leaves the number's Voice settings unchanged.

Inbound configuration

• Twilio connection: The saved account and regional credentials, shared with other Twilio connectors.
• Channel: SMS / MMS, WhatsApp, or RCS. Create a separate connector for each channel and sender.
• Twilio sender: Choose the receiving number or channel sender from the connected account. It must match the webhook's To address.
• Incoming-message webhook: Generated and registered automatically when saved. The WhatsApp Sandbox requires the manual step above.

Agent input payload

The agent receives normalized addresses and message text at the top level. raw preserves the original Twilio form fields, including channel-specific fields when supplied. This example shows a text-only WhatsApp message.

{
  "message_sid": "SM00000000000000000000000000000001",
  "channel": "whatsapp",
  "from": "whatsapp:+14155550124",
  "to": "whatsapp:+14155550123",
  "text": "What is the status of order 12345?",
  "conversation_id": "twilio_messaging:9e0f77d9-2fd8-5a8e-8d47-59fbf5b8a091",
  "raw": {
    "AccountSid": "AC00000000000000000000000000000000",
    "MessageSid": "SM00000000000000000000000000000001",
    "From": "whatsapp:+14155550124",
    "To": "whatsapp:+14155550123",
    "Body": "What is the status of order 12345?",
    "NumMedia": "0"
  }
}

Incoming media

Connic downloads incoming attachments into the standard files input. Each file has name, mime_type, base64-encoded data, and byte size. The connector accepts up to 10 attachments with a combined 10 MiB download limit per message. Media requires a US1 connection.

When an attachment cannot be downloaded or exceeds the limit, Connic rejects the webhook instead of starting the agent with incomplete files. A media-only message can have empty text; the agent should also inspect files.

Conversation history and example agent

The stable conversation_id identifies a conversation by inbound connector, account, region, channel, Twilio sender, and customer. To keep history across messages, configure session.key as input.conversation_id and redeploy the agent. Sessions are not enabled automatically.

name: messaging-assistant
model: connic/gpt-5.6-terra
system: |
  Answer the incoming message clearly and briefly.
  Ask for missing information before making assumptions.
  Return the reply as plain text.
session:
  key: input.conversation_id
  ttl: 86400

This example sets a session TTL of 86,400 seconds. With an automatic outbound connector linked, the agent's plain-text result becomes the reply. See Agent YAML for session configuration.

Troubleshooting inbound messages

• Save fails during webhook setup: Resolve the reported Twilio error. Clear an existing incoming-message webhook or TwiML app, or set the sender's Messaging Service to Defer to sender's webhook before saving again.
• Sandbox sends Twilio's demo reply: Save the Connic URL under When a Message Comes in in the Sandbox settings with HTTP POST. Enabling the connector in Connic does not complete this Sandbox step.
• No agent run: Check the enabled connector, linked deployment, exact POST webhook URL, and sender's incoming-message settings in Twilio.
• Signature or account error: Check the selected connection's Account SID, region, and regional Auth Token. The URL in Twilio must match the generated URL.
• Channel or recipient error: Match the connector's channel and sender to the message's To address.
• Attachment failure: Inspect the connector run error and Twilio logs; confirm the media is available and below the combined download limit.

How outbound works

Automatic outbound connectors send a completed run's final output and can be limited to selected inbound connectors. Agent-tool and middleware connectors send when called. Connic resolves the recipient and submits the message to Twilio's Messaging API with the saved connection credentials.

Outbound setup

1. 1

   Select the connection and sender

   Create a Twilio Messaging connector in Outbound mode. Select the Twilio connection and channel, then choose a sender from the account's dropdown. The connection can also be used by Twilio Voice. For replies, use the same connection, channel, and sender as the inbound connector.

2. 2

   Set the destination and optional defaults

   Set Default recipient for notifications, or leave it empty to reply to incoming messages. Optionally add a Messaging Service SID containing the sender, a default Content Template SID, and template variables. Save the connector.

3. 3

   Choose how the agent sends

   Link the connector as automatic outbound, an agent tool, or middleware outbound. For automatic replies, select the inbound connector under Only selected inputs in the agent link settings. An outbound-only notification flow needs a configured recipient or an explicit to in its payload.

4. 4

   Check the first message

   Trigger the linked agent or call the connector. Inspect the outbound connector run, then check the returned Message SID in Twilio's Messaging Logs for delivery status.

Outbound configuration

• Twilio connection, channel, and sender: Required for every send. See the channel and region reference below.
• Default recipient: Optional destination used when the payload omits to.
• Messaging Service SID: Optional MG… identifier sent alongside the configured sender.
• Default Content Template SID: Optional HX… identifier for a template created in Twilio.
• Default template variables: A JSON object of string values, such as {"1": "Alex"}. Configuring variables requires a template SID.

Outbound payload

Automatic outbound accepts plain text or a JSON object. Agent-tool and middleware outbound use the JSON object shown below. An agent-tool connector has an editable tool name, defaulting to send_to_<connector_name>. Middleware calls the configured connector name through send_connector.

{
  "text": "Your order has shipped.",
  "to": "whatsapp:+14155550124",
  "media_urls": ["https://example.com/shipping-label.png"]
}

Supported fields are text, to, media_urls, content_sid, and content_variables. Text is limited to 1,600 characters. Supply text, media, or a template; a text field is optional for a media-only message. Omit to when a default recipient or matching inbound reply context supplies the destination.

Sending media

Supply public HTTP or HTTPS URLs without embedded credentials in media_urls. Twilio fetches the files. Connic accepts up to 10 URLs for MMS and one for WhatsApp or RCS; IE1 supports SMS text only. Outbound media uses URLs, not the base64 files format of inbound messages.

Channel-specific file types and size limits still apply. WhatsApp ignores text sent with audio, video, documents, or other non-image media; send the text and media separately. See Twilio's WhatsApp media behavior.

WhatsApp templates

Outside WhatsApp's 24-hour customer service window, use an approved template. Create it and complete approval in Twilio, then set its Content SID and variables in the connector or payload. See Twilio's template guide.

{
  "to": "whatsapp:+14155550124",
  "content_sid": "HX00000000000000000000000000000000",
  "content_variables": {"1": "12345", "2": "Friday"}
}

Payload values override the configured Content SID and variable object. Variable values must be strings. Template sends use content variables instead of text or media_urls; explicitly combining a template with these fields is rejected. When a Content SID is configured on the connector, plain generated text is ignored. Return content_variables to fill that template.

Delivery status and troubleshooting

A successful outbound connector run means Twilio accepted the API request. It does not confirm delivery. The result includes the Message SID and available status fields; check Twilio's Messaging Logs for the recipient's delivery status and channel errors.

• Missing recipient: Set to, configure a default, or check that the inbound and outbound connectors share the required connection and sender details.
• Rejected send: Check the Twilio error code, sender registration, channel address, regional support, and any template approval or variables.
• No automatic reply: Check the agent's outbound link and selected inputs, then inspect the agent result and outbound connector run.

Connic treats connection failures before submission and HTTP 429 responses as retryable. For an unknown submission outcome, including read/write failures or server errors, check Twilio's logs before resending. Retrying an already accepted request could send a duplicate message.