# Set up an SMS Channel for SIPTRUNK

A SIPTRUNK SMS channel ties a SIPTRUNK DID number to your Cloud Voice system, letting agents hold text conversations with customers right inside the Cloud Voice App. The setup runs in three stages: you generate a webhook URL in Cloud Voice, register that webhook and an API key over in SIPTRUNK, then build the channel in Cloud Voice with the SIPTRUNK credentials and number.

## Requirements

### On your Cloud Voice system

- **Firmware**: Version **84.23.0.24** or later.
- **Domain name**: The domain must contain no 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 runs on a custom root domain rather than one of the standard IZT-provided cloud domains, install a valid domain certificate before you continue. Without it, the channel fails authentication or cannot receive messages.
:::

### On SIPTRUNK

- **Telephone number**: The DID number (or numbers) must be SMS/MMS capable and registered for 10DLC.

:::caution
Under US A2P 10DLC rules, any 10-digit long code number used for application-to-person messaging must be registered. Messages sent to US numbers from an unregistered 10DLC number are blocked. If you message US-based customers, complete 10DLC registration for your numbers to keep delivery from being interrupted.
:::

:::tip
If you do not yet have a suitable number, ask your service provider to provision the SMS/MMS-capable DIDs you need.
:::

## Supported message types and limits

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

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

:::caution
For a multimedia message such as an image, the SMS provider pulls the file from a link your system generates. If you use an Allowed Country/Region IP Access Protection rule, make sure the country where the SMS provider is located is permitted, or the file transfer will fail.
:::

## Step 1. Get a webhook URL from Cloud Voice

You need this URL when you set up the number in SIPTRUNK, so obtain it first.

1. Sign in to the PBX web portal and go to **Messaging > Message Channel**.
2. Click **Add** and choose **SMS**.
3. In the **ITSP** list, select **SIPTRUNK**, then copy the **Webhook URL**.

   :::caution
   The URL is regenerated as soon as you leave this page. Use the current webhook URL when you configure SIPTRUNK, not an older copy.
   :::

   
   ![Cloud Voice, ITSP set to SIPTRUNK with the webhook URL ready to copy](/images/pbx/webhook-for-siptrunk-pce.png)

## Step 2. Configure messaging in SIPTRUNK

Sign in to the SIPTRUNK customer portal and complete the following.

1. Note the DID number you want to add to the SMS channel.

   ![SIPTRUNK portal showing the DID number to use for messaging](/images/pbx/siptrunk-did-number.png)

2. Set up a messaging webhook for that DID number.

   1. Create a webhook using the webhook URL you copied from Cloud Voice.

      ![Creating a webhook in SIPTRUNK with the Cloud Voice webhook URL](/images/pbx/siptrunk-configure-webhook.png)

   2. Assign the webhook to the DID number.

      ![Assigning the messaging webhook to the DID number in SIPTRUNK](/images/pbx/set-webhook-for-did-number-siptrunk-pce.png)

3. Create an API key for the Cloud Voice integration, then note the **Access Key** and **Secret Key**.

   :::caution
   Copy and store the **Secret Key** before you close the pop-up window. It is shown only once.
   :::

   ![SIPTRUNK API key screen listing the access key and secret key](/images/pbx/siptrunk-api-key.png)

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

Now build the channel and fill in the credentials and number you got from SIPTRUNK.

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

   
   ![Cloud Voice, Authentication tab for entering the SIPTRUNK access key and secret key](/images/pbx/siptrunk-auth-setting-pce.png)

   - **Name**: A label that makes the channel easy to recognize.
   - **ITSP**: Select **SIPTRUNK**.
   - **Access Key**: Paste the access key from SIPTRUNK.
   - **Secret Key**: Paste the secret key from SIPTRUNK.

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 your SMS provider enforces, messages can fail to deliver. Confirm the sending-rate limit on your account with the provider 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 provisioned 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 API. With this option selected, the system pushes inbound messages to the platform, and you can track them through the New Message Notification event (event code 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 SIPTRUNK SMS channel with a connected status](/images/pbx/siptrunk-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 your SMS provider 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.