Using Conversation API requires signing up for a free account on the Sinch Build Dashboard. If you haven't already done so, sign up now!
This guide will show you how to send a text message on Conversation API's SMS channel. You can use the principles included in this guide to send any message type on any channel supported by Conversation API. The structure of the API call is the same, regardless of the channel!
To start sending messages:
Get access and create your access key: Once you have created an account and logged in, select Conversation API from the left menu. Review the terms and conditions, select the I agree to the terms and conditions check box, and click GET ACCESS to proceed.
Then, create your access key. Access keys are used to authenticate calls when using Conversation API. Access keys are generated in the Sinch Build Dashboard. If you need assistance, you can review review our Community article on access key creation.
Make sure you have your access key, access key secret, and project ID readily available. This information will be required when making the API call to send the text message. The access key and access key secret must be recorded during access key creation. The project ID can be found on the Sinch Build Dashboard's Project Settings page.
Create a Conversation API app: The next step is to create and configure a Conversation API app. Follow the instructions on the Sinch Build Dashboard. You can also review our Community article on app creation.
After you create your app, make sure you record your app's ID. This information will be required when making the API call to send the text message.
Configure the SMS channel: To send and receive on the SMS channel, you have to complete some configuration steps.
First, if you don't already have a number, click here to learn how you can get a number from Sinch.
The sample code in this call makes use of the SMS_SENDER property, which needs to be populated with your Sinch number. Make sure you have that number readily available when making the API call.
Once you have a Sinch number, activate the SMS channel through the Sinch Build Dashboard. Select your app and click SET UP CHANNEL on the SMS row. Then, select your configured service plan from the drop-down box and confirm the integration.
Now you're ready to get started send a text message on Conversation API's SMS channel. The raw payload to send the text message is below:
{
"app_id": "YOUR_app_id",
"recipient": {
"identified_by": {
"channel_identities": [
{
"channel": "SMS",
"identity": "RECIPIENT_number"
}
]
}
},
"message": {
"text_message": {
"text": "Hello from Sinch's Conversation API!"
}
},
"channel_properties": {
"SMS_SENDER": "YOUR_sms_sender"
}
}
The placeholder values included in the payload above are detailed in the table below:
| Placeholder value | Your value |
|---|---|
YOUR_app_id | Your app ID, recorded in step 2. Find your app ID on your Sinch dashboard. |
RECIPIENT_number | The phone number of the recipient to which you want to send the message. |
YOUR_sms_sender | Your Sinch virtual phone number, recorded in step 3. This number is also available on the Sinch Build Dashboard. |
If you already have experience making API calls, you can create an app that sends the text message in your preferred coding language. Use the payload to make a POST API call to https://us.conversation.api.sinch.com/v1/projects/YOUR_project_id/messages:send, where YOUR_project_id is the project ID you recorded in step 1. Include authentication information in the header. Since this guide is intended to testing purposes, you can use your access key and access key secret (also recorded in step 1) to authenticate using basic authentication (we recommend using your access key and secret to create a short-lived OAuth2.0 token when working in production environments).
Alternatively, these guides will walk you through setting up a simple application in the following languages (make sure you bring all the information you gathered during this process!):
