# Set up an SMS Channel for Apidaze When you add an Apidaze SMS channel, the number you provision with Apidaze is tied to your Cloud Voice system, and your agents can hold text conversations with customers straight from the Cloud Voice App. This page covers the two halves of the setup: building the channel in Cloud Voice, then pointing Apidaze back at your system with a webhook. ## Requirements Confirm your system meets the following before you begin. - **Firmware**: Version **84.23.0.24** 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 Apidaze channel handles both plain text messages and multimedia messages (MMS). Which MMS file types are accepted is decided by Apidaze. | Limit | Value | | --- | --- | | Maximum file size | 100 MB | | File retention period | 72 hours | :::caution For an MMS such as an image, the SMS provider 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 the SMS provider is located is permitted, or the file transfer will fail. ::: ## Before you begin Get the following from Apidaze: - Your API key - Your Secret - The phone number you will use to send and receive messages :::note If you plan to message customers in the United States, register the number for 10DLC (10-digit long code, the US carrier standard for business text messaging) first. Without registration, message delivery can be interrupted. ::: ## Step 1. Create and configure the SMS channel in Cloud Voice 1. Sign in to the PBX web portal and go to **Messaging > Message Channel**. 2. Click **Add** and choose **SMS**. 3. On the **Authentication** tab, enter your Apidaze credentials. ![Cloud Voice, Authentication tab where you enter the Apidaze API key and secret for a new SMS channel](/images/pbx/apidaze-auth-setting-pce.png) - **Name**: A label that makes the channel easy to recognize. - **ITSP** (Internet Telephony Service Provider): Select **Apidaze**. - **API Key**: The API key from Apidaze. - **Secret**: The Secret from Apidaze. 4. On the **Messaging Setting** 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. Check 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 **Accompanying Text for Chat File**, enter the default text to send alongside any chat file. The recipient sees this text next to the file. ![Cloud Voice, field for the default text that accompanies a shared chat file](/images/pbx/text-with-files.png) ![Cloud Voice, how the accompanying text appears next to a file on the recipient's side](/images/pbx/accompany-text.png) 4. 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. 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. 5. Click **Save**. 5. Click **Save**. ## Step 2. Configure the webhook in Apidaze 1. In the PBX web portal, go to **Messaging > Message Channel**. 2. Open the SMS channel you just created. 3. On the **Authentication** tab, copy the **Webhook URL**. ![Cloud Voice, Authentication tab showing the webhook URL to copy into Apidaze](/images/pbx/apidaze-webhook-pce.png) 4. In Apidaze, set the messaging webhook for your phone number to the URL you copied. This lets Apidaze deliver inbound messages to your system. ## 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 Apidaze SMS channel with a connected status](/images/pbx/apidaze-success.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.