Telnyx 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 SMS:

type: telnyx_messaging
mode: inbound
connection: support-telnyx
config:
  channel: sms
  sender: "+14155550123"
agents:
  - messaging-assistant

An outbound connector that replies from the same number:

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

Connection

A Telnyx Connection holds the account credentials and can serve any number of Telnyx Messaging and Telnyx Voice connectors. The channel and sender belong to each connector. connic uses the API key to list senders, set webhooks, and send messages, and the public key to verify the signature of every event Telnyx sends. Edit the Connection to rotate the credentials of all its connectors.

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 (such as attachment-1.jpg), mime_type, base64-encoded data, and size in bytes. A message takes up to 50 files, at most 32 MiB combined.

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, 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 Telnyx messages"
model: connic/gpt-5.6-terra
system_prompt: |
  Answer the incoming message 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.

Shared numbers

SMS and WhatsApp can use the same number with separate inbound connectors and agents. Both connectors must use the same Connection, and they share one webhook URL; connic routes each message by channel and recipient. Deleting one connector keeps the other channel's route. Two inbound connectors can't use the same channel and sender.

External WhatsApp numbers

For a WhatsApp number that isn't hosted on Telnyx, connic can't find the messaging profile. Enter the profile ID in whatsapp_profile_id. connic checks that the profile belongs to the account, but it can't verify that the number's messages use it. Outbound connectors for the number need the same whatsapp_profile_id.

After creating the inbound connector, copy the Incoming-message webhook from the details drawer. In Telnyx, set it as the primary webhook of that messaging profile, select webhook API version 2, and make sure the number's incoming messages use the profile. The WhatsApp Business Account's lifecycle webhook is a separate setting and doesn't route messages.

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. This example sends a WhatsApp image with a caption:

{
  "to": "+14155550124",
  "text": "Your shipping label",
  "media_urls": ["https://example.com/shipping-label.png"],
  "media_type": "image"
}

• text: the message text. Optional for a message with only media.
• to: the recipient; see Recipients.
• media_urls: 1 to 10 public media URLs; see Media.
• media_type: for WhatsApp media, image, video, document, audio, or sticker.
• whatsapp_template: an approved template; 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 Telnyx Messaging connector, the customer who sent the message. Both connectors must use the same Connection, channel, sender, and messaging profile.

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; Telnyx fetches the files. Outbound media uses URLs, not the base64 files format of incoming messages.

• SMS/MMS: up to 10 media URLs. A message with media goes out as MMS.
• WhatsApp: one media URL with media_type. Images, videos, and documents take the text as a caption; audio and stickers can't carry text.
• RCS: text or one media URL. Send text and media in separate messages.

WhatsApp templates

Outside WhatsApp's customer service window, send an approved template. Set whatsapp_template on the connector as a default, or in the payload for one message. Identify the template by template_id, or by name and language.code. Optional components of type header, body, or button carry the parameters in the Telnyx WhatsApp format.

{
  "to": "+14155550124",
  "whatsapp_template": {
    "name": "order_confirmation",
    "language": {"code": "en_US"},
    "components": [{
      "type": "body",
      "parameters": [{"type": "text", "text": "12345"}]
    }]
  }
}

A template in the payload replaces the connector's default and can't be combined with text or media_urls. While the connector has a default template, every message uses it: the agent's text is ignored and media URLs are rejected. Templates need the WhatsApp channel. Register and approve them in Telnyx and WhatsApp.

Delivery and retries

A successful connector run means Telnyx accepted the request, not that the message was delivered. The run's output holds the Telnyx message ID; check the final delivery in Telnyx.

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