Twilio Messaging

In code

Declare the connectors in connectors/*.yaml. Quote phone numbers and IDs; unquoted, YAML reads a number such as +14155550123 as an integer and the deploy fails. An inbound connector that receives WhatsApp messages:

type: twilio_messaging
mode: inbound
connection: support-twilio
config:
  channel: whatsapp
  sender: "whatsapp:+14155550123"
agents:
  - messaging-assistant

An outbound connector that replies from the same sender:

type: twilio_messaging
mode: outbound
connection: support-twilio
config:
  channel: whatsapp
  sender: "whatsapp:+14155550123"
agents:
  - name: messaging-assistant
    outbound: { usage: automatic, source: [support-whatsapp] }  # replies to the inbound file's runs

Connection

A Twilio Connection holds the account credentials and can serve any number of Twilio Messaging and Twilio Voice connectors. The channel and sender belong to each connector. connic uses the credentials to list senders, set webhooks, and send messages, and the Auth Token to verify the signature of every request Twilio sends.

Generated values

connic sets these when the connector is created or its sender changes. Copy the webhook URL from the details drawer. Leave them out of YAML files; connic lint rejects them.

Attachments

connic downloads incoming media into files. Each file has name (the Twilio media SID with a file extension), mime_type, base64-encoded data, and size in bytes. A message takes up to 50 files, at most 32 MiB combined. Downloads need a US1 Connection.

An invalid or unavailable file is skipped on its own. At the first file over the count or size limit, connic keeps the files before it and omits that file and every later one. file_issues lists each omitted file with a code, a message, and the limit it hit, and the connector's logs record a warning. The run starts even when no file was accepted, unless Files required is on for the agent's link. The agent should check both files and file_issues.

Conversations

conversation_id stays the same for each combination of inbound connector, account, region, channel, sender, and customer. To keep the history across messages, set session.key to input.conversation_id and redeploy the agent; sessions aren't on by default. With an automatic outbound connector linked, the agent's plain-text result becomes the reply.

version: "1.0"
name: messaging-assistant
description: "Answers incoming Twilio messages"
model: connic/gpt-5.6-terra
system_prompt: |
  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 keeps a conversation for 86,400 seconds. See Agent YAML for the session settings.

WhatsApp Sandbox

Twilio offers no documented public API for the Sandbox webhook, so you set it yourself. Create the connector with the WhatsApp channel and the sender WhatsApp Sandbox (activation required), then copy the Incoming-message webhook from the details drawer. 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. Change the Sandbox settings yourself when you switch the connector to another sender or delete it.

Automatic payload

An automatic link sends the run's final output. Plain text becomes the message text. A JSON object can carry the fields of the agent-tool payload below; its text can also be in body, message, response, or output.

Agent-tool and middleware payload

The model or middleware passes a JSON object with these fields. Unknown fields fail validation. A message needs text, media, or a template.

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

• text: the message text, at most 1,600 characters. Optional for a message with only media.
• to: the recipient; see Recipients.
• media_urls: 1 to 10 public media URLs; see Media.
• content_sid and content_variables: a template and its variables; see WhatsApp templates.

Recipients

connic sends to the first recipient it finds:

1. to in the payload or the automatic output.
2. The connector's Default recipient.
3. For a run started by an inbound Twilio Messaging connector, the customer who sent the message. Both connectors must use the same Connection, channel, and sender.

A default recipient takes precedence over replies; leave it empty to answer each customer. Sending fails when no recipient is found.

Media

Pass public HTTP or HTTPS URLs without embedded credentials in media_urls; Twilio fetches the files. A message takes up to 10 URLs for MMS and one for WhatsApp or RCS. IE1 sends text only. Outbound media uses URLs, not the base64 files format of incoming messages.

Each channel's file types and size limits apply. WhatsApp ignores text sent with audio, video, documents, or other non-image media, so send that text in a separate message. See Twilio's WhatsApp media behavior.

WhatsApp templates

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

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

Payload values override the connector's content_sid and content_variables. Variable values must be strings. A payload with content_sid can't also carry text or media_urls. While the connector has a default Content SID, every message uses the template: plain text from the agent is ignored and media URLs are rejected. Return content_variables to fill the template.

Delivery and retries

A successful connector run means Twilio accepted the request, not that the message was delivered. The run's output holds the Message SID and the status fields Twilio returned; check Twilio's Messaging Logs for the delivery status and channel errors.

connic retries connection failures before submission and 429 responses, waiting as long as Twilio's Retry-After asks, for 3 attempts in total. Other failures aren't retried. When the outcome is unknown, such as after a read or write failure or a 5xx response, check Twilio's logs before you resend; Twilio may already have accepted the message.