Send SMS

Learn how to set up and send a message with SMS and Conversation API.

Add an SMS Channel to your Conversations API App

In this guide, you will learn how to add an SMS channel to your Sinch Conversations API Application. You can add your SMS channel one of two ways: either programmatically via the Sinch Conversation API or through the Sinch online portal. Before we begin, here are a few items you should already have:

  1. A text enabled long code or a short code registered with Sinch.
  2. Access to the Sinch dashboard where you can manage your long code or short code.
  3. An SMS Service Plan ID and Secret to authorize SMS text message requests.
  4. A Conversations App ID.
  5. A Sinch Project ID and associated Key ID and Key Secret.

If you are missing any of items 13 above, you should begin by registering online at Sinch.com. We'll show you how to create a New Conversation App and get authentication credentials for items 4 and 5.

Create a New Conversations App

To create a new Conversations App, simply sign in to your Sinch Dashboard account and use the menu on the left to access Conversations > Apps.

Click the New App button on the right, "Name" your App, choose an appropriate region for it, and click Create.

dashboard image

Add an SMS Channel to your Conversations App

In your Sinch Dashboard, navigate to Conversations > Apps. Click the name of the app that you want to add the SMS Channel to.

app added

Under Set up channels find SMS channel and click on Set Up Channel.

new sms channel

For setting up the SMS channel, you need to choose your SMS Service Plan ID from the drop-down and click Save.

new sms channel

You have now added an SMS Channel to your App. Just a few more steps to go.

new sms channel

Fetch Oauth2 Token needed for authentication

Go to the Access Keys page under Settings and create a new key by clicking the New Key button:

access keys

Be sure to copy and store in a safe place the Key Secret you will get. You won't be able to retrieve it again once you’ve created the key.

Then use the key id and key secret to obtain an access token:

curl https://auth.sinch.com/oauth2/token -d grant_type=client_credentials --user <key_id>:<key_secret>

Copy the token and use it in the Authorization header of your calls to Sinch Conversations API.

Send an SMS Message to a Contact

To send an SMS message to a Contact via the Sinch Conversations API App, send an HTTP POST with the following JSON:

Request Body schema: application/json
app_id
required
string

The ID of the app sending the message.

project_id
required
string

The project ID.

required
object (Recipient)
callback_url
string

Overwrites the default callback url for delivery reports for this message The REST URL should be of the form: http://host[:port]/path

channel_priority_order
Array of strings (Channel Identifier)

Explicitly define the channels and order in which they are tried when sending the message. Note that collection can't contain 'CHANNEL_UNSPECIFIED' value. Which channels the API will try and their priority is defined by:

  1. channel_priority_order if available.
  2. recipient.identified_by.channel_identities if available.
  3. When recipient is a contact_id:
    • if a conversation with the contact exists: the active channel of the conversation is tried first.
    • the existing channels for the contact are ordered by contact channel preferences if given.
    • lastly the existing channels for the contact are ordered by the app priority.
Items Enum: "CHANNEL_UNSPECIFIED" "WHATSAPP" "RCS" "SMS" "MESSENGER" "VIBER" "VIBERBM" "MMS"
object

Channel-specific properties. The key in the map must point to a valid channel property key as defined by the enum ChannelPropertyKeys. The maximum allowed property value length is 1024 characters.

object (Message originating from an app)
message_metadata
string

Metadata that should be associated with the message.

queue
string (MessageQueue)
Default: "NORMAL_PRIORITY"
Enum: "NORMAL_PRIORITY" "HIGH_PRIORITY"
ttl
string

The timeout allotted for sending the message. Passed onto channels which have support for it and emulated by Conversation API for channels without ttl support but with message retract/unsend functionality. Channel failover will not be performed for messages with expired TTL.

Content type
application/json
{
  • "app_id": "{APP_ID}",
  • "project_id": "{PROJECT_ID}",
  • "recipient": {
    }
}
curl --location --request POST 'https://eu.conversation.api.sinch.com/v1beta/projects/{project_id}/messages:send' \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer <access token>"
-d '{
    "app_id": "{{YOUR_APP_ID}}",
    "recipient": {
        "identified_by": {
            "channel_identities": [
                {
                    "channel": "SMS",
                    "identity": "+15551231212"
                }
            ]
        }
    },
    "message": {
        "text_message": {
            "text": "Text message from Sinch Conversation API."
        }
    },
}'

When sending SMS messages you can use a channel specific property called SMS_FLASH_MESSAGE, check out Channel Specific Properties for more info.