Getting started with an SMS Channel

This article details the steps required to set up an SMS channel for use with the Sinch Conversation API.

Prerequisites

Before you can set up an SMS channel on the Conversation API, you need to do the following:

General requirements

Note

If you have already completed the Conversation API Getting started steps, you can skip this section.

Sign up for the Sinch Customer Dashboard.
Get access to the Conversation API.
Create your app.
Create your access key. Any API calls you make will require authentication information provided by your access key.

Refer to the Conversation API Getting started section for more information on any of these steps.

SMS Requirements

You must ensure that you have at least one service plan associated with your Sinch account. You must also have a virtual number assigned to that service plan.

Note

Usually, each Sinch account is provided one service plan upon creation. Additionally, one test number is usually available for new Sinch accounts.

For more information on creating an SMS service account, see How do I create an SMS service plan?. For more information on assigning a virtual number to an SMS service account, see How do I assign a virtual number to an SMS service plan?.

Warning:

The Conversation API is regional. Your Conversation API App must be created in the same region that your service plan is provisioned. If your Conversation API App is created in a different region than the service plan is provisioned, the SMS channel will report errors.

Configuring the Conversation API and SMS integration

After ensuring that you meet the above prerequisites, you must enable the SMS integration for your Conversation API app. You can do so using the Sinch Customer Dashboard, or using the API.

Enabling the SMS integration using the Sinch Customer Dashboard

When enabling the SMS channel through the Sinch Customer Dashboard, select your app and click SET UP CHANNEL next to the relevant SMS channel. Then, select your configured service plan from the drop-down box and confirm the integration.You must also configure at least one Conversation API webhook which will trigger POST callbacks to the given URL. For more information on how to do this using the Customer Dashboard, see How to add a webhook to a Conversation API app.

Enabling the SMS integration using the API

To setup the SMS integration programmatically, use the following snippet to configure the channel credentials for the app with the SMS channel:

Copy

Copied

{
  "channel_credentials": [
    {
      "channel": "SMS",
      "static_bearer": {
        "claimed_identity": "{{SERVICE_PLAN_ID}}",
        "token": "{{API_TOKEN}}"
      }
    }
  ]
}

Replace {{SERVICE_PLAN_ID}} and {{API_TOKEN}} with your Sinch SMS service plan ID and API token.

Note

Any API calls you make will require authentication information provided by your access key. For more information, see this Overview.

You must also configure at least one Conversation API webhook which will trigger POST callbacks to the callback URL. For more information on how to do this programmatically, click here.

Next steps

After configuring the channel, you need to set the channel priority in your app. Then, it's time to send your first message.

You must know your contact's channel/idenity pair or contact_id prior to sending a message. For SMS, the channel is SMS and the identityis just the contact's phone number. To get a list of any existing contact_id values, you can make a GET request to the contact webhook. For more information, see the API reference.

Important property!

If you are planning to send an SMS message using a free test number, make sure you understand the SMS_SENDER property. You'll need to add it to your code and set it to your free test number.

If you already know how to set channel priority, or your channel priority is already established, you can begin sending and receiving messages in your preferred language: