Telnyx Messaging

How inbound works

Telnyx sends signed JSON events to the connector's webhook. Connic verifies each incoming message, prepares its input, and queues a run for each linked agent. Replies are sent through a separate outbound connector.

Both directions can reuse the saved account connection used by Telnyx Voice. It stores the API key and public key. Each Messaging connector selects its own channel and sender.

Inbound setup

1. 1

   Prepare the Telnyx sender

   Use a messaging-enabled Telnyx number or an enabled, registered WhatsApp number or RCS agent. For SMS and WhatsApp, use a messaging profile dedicated to this number. Move any other numbers or short codes to a different profile. Clear any failover webhook or Telnyx AI assistant routing on the selected profile or RCS agent before setup.

2. 2

   Create the inbound connector

   Add Telnyx Messaging from the marketplace and select Inbound. Choose or create a Telnyx connection with the API key and account public key. Select the channel, then choose the sender from the account's dropdown. Save the connector.

3. 3

   Complete message routing

   Connic automatically sets the webhook on the number's assigned messaging profile, or on the selected RCS agent. For an external WhatsApp number without a discoverable Telnyx number assignment, provide its existing profile ID and complete the manual setup below.

4. 4

   Link an agent and test

   Link a deployed agent and keep the connector enabled. Send a message to the selected sender and inspect the run input. For automatic replies, add an outbound connector using the same saved connection, channel, sender, and messaging profile.

External WhatsApp numbers

A WhatsApp number registered with Telnyx can require manual setup when Connic cannot discover its messaging-profile assignment. Enter the existing profile ID in whatsapp_profile_id. Connic checks that the profile belongs to the account, but cannot verify the external number's routing to it.

After saving, copy the generated Incoming-message webhook from the connector details. In Telnyx, set it as the primary webhook on that number's messaging profile, select webhook API version 2, and ensure the number's incoming messages use that profile. The WhatsApp Business Account lifecycle webhook is a separate setting and does not replace this message route.

Inbound configuration

• Telnyx connection: The saved account credentials shared with other Telnyx connectors.
• Channel and sender: SMS/MMS, WhatsApp, or RCS and a sender from the connected account. Create a separate connector for each channel and sender.
• WhatsApp messaging profile: The existing profile ID required when the WhatsApp number's assignment cannot be discovered. It is also required for outbound sends from that number.
• Incoming-message webhook: Generated when saved. Automatic setup installs it; manual WhatsApp setup displays it for entry in Telnyx.

Shared numbers and removal

SMS and WhatsApp can use the same number with separate connectors and agents. Reuse the same saved Telnyx connection and number profile. Both channels share one webhook address; Connic routes received messages by channel and recipient. The profile must not contain unrelated numbers or short codes.

Removing one connector preserves the other channel's route. Changing senders or removing the last inbound connector clears its old webhook only if it still matches the Connic URL. This also applies to a manually installed WhatsApp webhook. A different URL entered later in Telnyx remains untouched. Messaging setup does not change the number's Voice application.

Agent input and sessions

The example shows the normalized message fields. The input also contains raw with the original Telnyx message payload. Phone numbers use E.164 format without channel prefixes; an RCS recipient is the agent ID.

{
  "event_id": "7a3a86b3-0e77-48f6-914a-63ad28b7d64e",
  "message_id": "4031938e-60e4-4235-a8dd-0b1c55a23e7a",
  "channel": "whatsapp",
  "from": "+14155550124",
  "to": "+14155550123",
  "text": "Has order 12345 shipped?",
  "conversation_id": "telnyx_messaging:9e0f77d9-2fd8-5a8e-8d47-59fbf5b8a091"
}

To retain context across messages, set session.key to input.conversation_id and redeploy. Sessions are not enabled automatically. The conversation identity separates connectors, channels, senders, and customers. This example keeps session history for 86,400 seconds.

name: messaging-assistant
model: connic/gpt-5.6-terra
system: |
  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

Incoming media

Connic downloads supported attachments into files. Each file contains name, mime_type, base64-encoded data, and byte size. Up to 10 attachments with a combined 10 MiB download limit are accepted per message.

Unavailable or oversized attachments cause the webhook to fail before an agent starts. Media-only messages can have empty text; include files in the agent's handling and choose a model that supports the relevant media.

Troubleshooting inbound messages

• Save fails: Check the reported Telnyx error, enable the sender and profile, and remove unrelated profile members or conflicting failover and AI assistant routing.
• No agent run: Check the enabled connector, linked deployment, and exact webhook URL. For manual WhatsApp setup, verify the number's profile assignment and webhook API version 2 in Telnyx.
• Signature or sender error: Use the public key from the connected Telnyx account and match the configured channel, sender, and profile to the incoming message.
• Attachment failure: Check Telnyx's webhook delivery details and confirm that the media is available and below the combined download limit.

Outbound setup

1. 1

   Select the connection and sender

   Create Telnyx Messaging in Outbound mode. Select the saved connection, channel, and sender. For replies, match the inbound connector's connection, channel, sender, and profile. External WhatsApp numbers require the same whatsapp_profile_id.

2. 2

   Set optional defaults

   Set Default recipient for notifications, or leave it empty to reply to each incoming customer. Optionally set a default WhatsApp template. Save the connector; outbound setup does not install an incoming webhook.

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. Notification runs need an explicit or default recipient.

4. 4

   Check the first message

   Trigger the linked agent or call the connector. Inspect the outbound connector run, then use the returned message ID to check delivery in Telnyx.

Outbound payload

Automatic outbound accepts plain text or a JSON object. Agent-tool and middleware calls use an object with text and optional to, media_urls, media_type, or whatsapp_template. Middleware calls the configured connector through send_connector.

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

This example sends a WhatsApp image with a caption. For automatic text output, body, message, response, and output are also accepted text fields. Explicit connector calls use text. Supply text, media, or a template; media-only messages can omit text.

Text and media limits

Use 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 attachments.

• SMS/MMS: Up to 10 media URLs. Adding media sends MMS. Telnyx's message API limits total MMS media to 1 MB.
• WhatsApp: Text supports up to 4096 UTF-8 bytes. One media URL requires media_type: image, video, document, audio, or sticker. Images, videos, and documents accept captions up to 1024 UTF-8 bytes. Send audio and stickers separately from text.
• RCS: Text supports up to 3072 characters, or send one media URL. Text and media must be sent separately.

WhatsApp templates

Outside WhatsApp's customer-service conversation window, use an approved template. Set whatsapp_template in the connector as a default or in the payload for a single message. Identify it by template_id, or by name and language.code. Optional components supply 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"}]
    }]
  }
}

An explicit template replaces the configured default and must be sent separately from text and media URLs. A configured default template replaces the agent's free-form text. Template registration and approval take place in Telnyx and WhatsApp.

Delivery status and troubleshooting

A successful outbound connector run records Telnyx's acceptance and message ID. Check final delivery in Telnyx; API acceptance does not confirm delivery to the recipient.

• Missing recipient: Set to, configure a default, or check the matching inbound reply context.
• Rejected send: Check the provider error, sender registration, messaging profile, channel limits, and any template approval or parameters.
• No automatic reply: Check the agent's outbound link, selected inputs, final output, and outbound connector run.

Connection failures before submission and HTTP 429 responses can be retried. For ambiguous timeouts or server errors, check Telnyx before resending; the first request may already have been accepted.