# Set up an SMS Channel for Aspsms An Aspsms SMS channel lets your team hold two-way text conversations with customers straight from the Cloud Voice App. Once the channel is live, inbound messages are routed to the extension or queue you choose, and agents can reply without leaving their client. This page walks you through obtaining a webhook, wiring up your number on Aspsms, and creating the matching channel in Cloud Voice. ## Requirements Before you begin, confirm your Cloud Voice system meets the following: - **Firmware**: Version 84.23.0.24 or later. - **Domain name**: The domain must not contain any underscore (`_`) characters. Aspsms rejects such hosts, which causes authentication to fail or messages not to arrive. - **Domain certificate**: A valid certificate must be installed on the system. :::caution If your system's root domain is one of the standard Cloud Voice domains (`ycmcloud.com`, `yeastarcloud.com`, or `yeastarycm.co.za`), no extra certificate work is needed. If you use a custom root domain instead, install a valid domain certificate first, or the channel will fail authentication or fail to receive messages. ::: ## Restriction The Aspsms channel handles text messages only. ## Prerequisites You need an Aspsms account with one or more phone numbers purchased specifically for two-way SMS. :::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 plan to text US-based customers, ask your service provider to confirm that 10DLC registration is complete before you go live. ::: ## Step 1. Get a webhook URL from Cloud Voice Cloud Voice generates the webhook URL that Aspsms uses to forward incoming messages. Grab it first, because you will paste it into the Aspsms portal in the next step. 1. Sign in to the Cloud Voice management portal and go to **Messaging > Message Channel**. 2. Click **Add** and choose **SMS**. 3. From the **ITSP** (Internet Telephony Service Provider) drop-down, select **Aspsms**, then copy the **Webhook URL**. ![Channel authentication panel with the ITSP set to Aspsms and the webhook URL ready to copy](/images/pbx/aspsms-auth-setting.png) :::caution The webhook URL is regenerated as soon as you leave this page. Always copy the current value and use that latest URL when you configure Aspsms. ::: ## Step 2. Configure the number for SMS on Aspsms Point your Aspsms number at the Cloud Voice webhook and collect the API credentials the channel will need. 1. Sign in to the [Aspsms portal](https://www.aspsms.com/en/login/). 2. In the left navigation bar, go to **Two-Way SMS > My Mobile Numbers**, then click **Edit** next to the number you want to use. ![List of mobile numbers on Aspsms with an Edit control beside each entry](/images/pbx/aspsms-numbers.png) 3. Scroll to the **Forward SMS as HTTP raw data** section and fill in the callback settings with your Cloud Voice webhook URL so that incoming messages are delivered to your system. ![Cloud Voice, HTTP raw data forwarding form on Aspsms filled in with the webhook host, header, and body](/images/pbx/aspsms-payload-setting-pce.png) a. In the **protocol://HOST** field, enter the protocol and domain taken from your webhook URL, for example `https://docs.example.yeastarcloud.com`. b. In the **HEADER** field, enter the request template below, replacing the variables with your own webhook details: ``` POST {{Webhook Path}} HTTP/1.1 Content-type: application/json Host: {{PBX domain}} Connection: keep-alive Content-Length: Accept: application/json Content-Type: application/json Accept: text/* ``` - `{{Webhook Path}}`: the path portion of your webhook URL. If the full URL is `https://docs.example.yeastarcloud.com/api/v1.0/webhook/aspsms/091e568fec824f52bb9e83abe68f7693`, the path is `/api/v1.0/webhook/aspsms/091e568fec824f52bb9e83abe68f7693`. - `{{PBX domain}}`: the domain from your webhook URL, without the `https://` prefix. c. In the **BODY** field, paste the following: ```json { "MessageDataHex":"", "Recipient":"", "Originator":"", "DateReceived":"" } ``` d. Click **Save**. 4. Collect the API credentials for the integration. a. Go to **Registered Users > API Credentials**. b. Record the **Userkey** and **API Password** for the next step. ![Aspsms API credentials page showing the Userkey and API password](/images/pbx/aspsms-credentials.png) ## Step 3. Create and configure the SMS channel in Cloud Voice Now build the channel in Cloud Voice using the credentials and number from Aspsms. 1. Sign in to the Cloud Voice management portal and go to **Messaging > Message Channel**. 2. Click **Add** and choose **SMS**. 3. On the **Authentication** tab, enter your Aspsms details. ![Channel authentication tab with fields for name, ITSP, user key, and password](/images/pbx/aspsms-integration-setting.png) - **Name**: A label that helps you recognize the channel. - **ITSP**: Select **Aspsms**. - **User Key**: Paste the Userkey you recorded from Aspsms. - **Password**: Paste the API password you recorded from Aspsms. 4. On the **Messaging Settings** tab, configure the channel. a. In the **Message Sending Rate** field, set how many messages the system may send per second. :::note - Messages beyond the configured rate are queued and released at the set rate. - If your rate is higher than the limit Aspsms allows for your account, messages may fail to send. Check the account's rate limit with your provider and raise it if needed. ::: b. Adjust the session settings to suit your workflow. | Setting | Description | |---------|-------------| | Close Session Automatically | Select the checkbox to end sessions after a period of inactivity, then enter the number of days in the **Session Timeout (Days)** field. | | Allow the Creation of Duplicate Active Sessions | Select the checkbox to permit a new session even when an active session with the same sender and receiver already exists. With this on, when an agent starts such a session in the Cloud Voice App, a prompt appears. If the agent continues, the existing session is removed from the previous handler's list and reassigned to the new agent, along with the full chat history. | ![Session timeout option with a field for the number of inactive days](/images/pbx/auto-closure-of-conversations.png) c. In the **Number** section, click **Add** to create a message routing rule. ![Message routing rule form with fields for the number and inbound destination](/images/pbx/sms-did-number-rule-1.png) - **Number**: Enter the number you purchased. :::note Use E.164 format, the international phone number standard: `[+][country code][phone number]`, for example `+41791234510`. ::: - **Destination for Inbound Messaging**: Choose where incoming messages from this number are delivered. | Option | Description | |--------|-------------| | Extension | Choose an extension from the **Extension** drop-down. Only that user receives inbound messages from the number. | | Message Queue | Choose a queue from the **Message Queue** drop-down. Every agent in the queue sees new inbound sessions, but once an agent picks up a session, only that agent receives and answers the follow-up messages in it. | | Third-Party Message Analytics Platform (Transmitted via API) | Inbound messages are forwarded automatically to an external analytics platform over the API for further processing. This requires your system to already be integrated with that platform via the API; incoming messages are then transmitted to it, and you can track them through the New Message Notification API event (event 30031) and the messaging API set. | - **Extensions allowed to create messaging sessions**: Select the extensions permitted to start a message conversation with a customer. d. Click **Save**. 5. Click **Save**. ## Result - The channel is created and appears in the message channel list with a **Status** of ![OK status indicator](/images/pbx/trunk-ok.png). ![Message channel list showing the Aspsms channel with a healthy status](/images/pbx/aspsms-succeeded.png) - Cloud Voice tracks the number of messages sent and received on the channel. The **Total** column counts all outbound messages, both delivered and failed. :::note - Only messages sent from agents' Cloud Voice App are counted. To work out actual cost, check with your provider for the exact count, since messages longer than 160 characters are split into segments before delivery and reassembled on arrival, which raises the number of sent segments. - Use the time filter to narrow the statistics to a specific period. ::: ![Message report with sent and received totals and a time filter](/images/pbx/message-report.png) ## What to do next Send a test text message to the number and confirm that the assigned agent receives it in the Cloud Voice App.