# Set up an SMS Channel for Telnyx

A Telnyx SMS channel links a number you own on Telnyx to your Cloud Voice system, letting your agents hold text conversations with customers directly in the Cloud Voice App. Because the channel's webhook URL is generated on your system and changes each time you leave the page, the setup runs in a specific order: grab the webhook first, wire up Telnyx with it, then come back and finish building the channel.

## Requirements

Confirm your system meets the following before you start.

- **Firmware**: Version **84.23.0.123** or later.
- **Domain name**: The domain must not contain any underscore characters. An underscore causes the channel to fail authentication or stop receiving messages, because the third-party platform rejects it.
- **Domain certificate**: A valid domain certificate must be installed.

:::note
If your Cloud Voice system uses a custom root domain rather than a standard IZT-provided domain, install a valid domain certificate first. Without it, the channel fails authentication or fails to receive messages.
:::

## Supported message types and limits

The Telnyx channel carries both plain text messages and multimedia messages (MMS). Which MMS file types are accepted is decided by Telnyx.

| Limit | Value |
| --- | --- |
| Maximum file size | 100 MB |
| File retention period | 72 hours |

:::caution
For an MMS such as an image, Telnyx fetches the file from a link your system generates. If you have an Allowed Country/Region IP Access Protection rule in place, make sure the country where Telnyx is located is permitted, or the file transfer will fail.
:::

## Overview

The setup has three stages:

1. [Obtain a webhook URL in Cloud Voice](#step-1-obtain-a-webhook-url-in-cloud-voice)
2. [Configure a number for SMS on Telnyx](#step-2-configure-a-number-for-sms-on-telnyx)
3. [Create and configure the SMS channel in Cloud Voice](#step-3-create-and-configure-the-sms-channel-in-cloud-voice)

## Step 1. Obtain a webhook URL in Cloud Voice

You need the system's webhook URL before you can configure Telnyx, so collect it first.

1. Sign in to the PBX web portal and go to **Messaging > Message Channel**.
2. Click **Add** and choose **SMS**.
3. From the **ITSP** (Internet Telephony Service Provider) drop-down list, select **Telnyx**, then copy the **Webhook URL**.

   :::caution
   The webhook URL regenerates as soon as you leave this page. Always paste the current URL into Telnyx, and treat any URL you copied earlier as stale.
   :::

   
   ![Cloud Voice, Add SMS channel dialog with Telnyx selected and the webhook URL ready to copy](/images/pbx/webhook-for-telnyx-pce.png)

## Step 2. Configure a number for SMS on Telnyx

:::caution
Under US regulations for A2P (Application-to-Person) messaging, any 10DLC (10-digit long code) number used for A2P must be registered. Messages sent to US numbers from an unregistered 10DLC number are blocked. If you message US-based customers, confirm the registration requirements with Telnyx and complete number registration before you go live.
:::

Sign in to the [Telnyx portal](https://portal.telnyx.com) and complete the following.

1. Search for and buy a DID (Direct Inward Dialing) number that supports SMS.

   ![Telnyx portal search results for purchasing a DID number with SMS capability](/images/pbx/sms-telnyx-purchase-number-2.png)

2. Create a message profile and set its messaging webhook to the **Webhook URL** you copied in Step 1.

   :::note
   For any settings not covered here, configure them to suit your own requirements.
   :::

   
   ![Cloud Voice, Telnyx message profile with the messaging webhook set to your system's URL](/images/pbx/enter-pbx-webhook-on-telnyx-pce-2.png)

3. Assign the message profile to the DID number you purchased.

   
   ![Cloud Voice, assigning the message profile to the purchased Telnyx number](/images/pbx/assign-msg-profile-to-number-telnyx-1.png)

4. Create an API key for the integration with your system.

   :::caution
   Copy and store the API key the moment it is created. Telnyx shows it only once, and you cannot view it again after closing the key window.
   :::

   
   ![Cloud Voice, creating a new API key in the Telnyx portal](/images/pbx/telnyx-create-api-key-1.png)

   ![Telnyx one-time display of the generated API key](/images/pbx/telnyx-api-key.png)

5. On the **Public Key** page, note down the public key.

   ![Telnyx portal showing the API key alongside the account public key](/images/pbx/telnyx-api-key-and-public-key-1.png)

## Step 3. Create and configure the SMS channel in Cloud Voice

1. In the PBX web portal, go to **Messaging > Message Channel**.
2. Click **Add** and choose **SMS**.
3. On the **Authentication** tab, enter your Telnyx credentials.

   
   ![Cloud Voice, Authentication tab where you enter the Telnyx API key and public key for a new SMS channel](/images/pbx/telnyx-channel-auth-pce.png)

   - **Name**: A label that makes the channel easy to recognize.
   - **ITSP**: Select **Telnyx**.
   - **API Key**: Paste the API key you saved in Step 2.
   - **Public Key**: Paste the public key you noted in Step 2.

4. On the **Messaging Settings** tab, configure how the channel behaves.

   1. In **Message Sending Rate**, set the number of messages the system may send per second.

      :::note
      - When more messages are ready than the rate allows, the system queues them and releases them at the set rate.
      - If your rate is higher than the limit Telnyx enforces, messages can fail to deliver. Check the sending-rate limit on your account with Telnyx and ask them to raise it if you need more throughput.
      :::

   2. Set the session options as needed.

      | Setting | What it does |
      | --- | --- |
      | Close Session Automatically | Select this to have the system end sessions that have gone quiet for a set time, then enter the number of days in **Session Timeout (Days)**. |
      | Allow the Creation of Duplicate Active Sessions | Select this to let a new session start even when an active one already exists between the same sender and receiver. When an agent tries to start such a session in the Cloud Voice App, a prompt appears; if the agent continues, the existing session (with its full chat history) leaves the previous handler's list and moves to the new agent. |

      ![Session timeout option for automatically closing inactive conversations](/images/pbx/auto-closure-of-conversations.png)

   3. In the **Number** section, click **Add** to create a message routing rule.

      ![Rule that maps an SMS number to its inbound message destination](/images/pbx/sms-did-number-rule.png)

      - **Number**: Enter your purchased number or an alphanumeric sender ID.

        :::note
        Enter the number in E.164 format, `[+][country code][phone number]`, for example `+14102161183`.
        :::

      - **Destination for Inbound Messaging**: Choose where messages to this number are delivered.

        | Option | What it does |
        | --- | --- |
        | Extension | Pick an extension from the **Extension** list. Only that extension user receives inbound messages from the number. |
        | Message Queue | Pick a queue from the **Message Queue** list. Every agent in the queue sees new inbound sessions, but once an agent picks up a session, only that agent receives and answers its follow-up messages. |
        | Third-Party Message Analytics Platform (Transmitted via API) | Inbound messages are forwarded automatically to an external analytics platform over the API for further processing. |

        :::note
        Automatic forwarding to a third-party analytics platform requires your system to be integrated with that platform through the Cloud Voice API. With this option selected, the system pushes inbound messages to the platform, and you can track them by monitoring the New Message Notification API event (event 30031). A full set of message API interfaces is also available for richer interaction with the connected platform.
        :::

      - **Extensions allowed to create messaging sessions**: Select the extensions that may start a messaging conversation with customers.

   4. Click **Save**.

5. Click **Save**.

## Result

- The channel appears in the message channel list with a green **Status** indicator ![Channel connected](/images/pbx/trunk-ok.png), confirming it was created successfully.

  ![Message channel list showing the new Telnyx SMS channel with a connected status](/images/pbx/telnyx-sms-channel-ok.png)

- The system tracks how many messages the channel sends and receives. The **Total** column shows all sent messages, both delivered and failed.

  ![Message report with per-channel counts of sent and received messages](/images/pbx/message-report.png)

  :::note
  - The count includes only messages sent from agents' Cloud Voice App. To work out actual cost, ask Telnyx for the exact number of messages transmitted, a text longer than 160 characters is split into segments before sending and reassembled on delivery, which raises the sent count.
  - Use the time filter to narrow the statistics to a specific period.
  :::

## What to do next

Send a text message to your channel's phone number and confirm that the assigned agent receives it in the Cloud Voice App.