In this tutorial, you'll create and configure your first Conversation API app in the Sinch dashboard.
- Channels that are set up and registered to be included in the Conversation API.
- Service plan ID/Service ID/Sender Identity set up at corresponding channel portals.
- Access keys and Project ID which can be found in the Sinch dashboard.
Create a new app in the Sinch dashboard.
- Go to the Apps page.
- Click NEW APP.
- Add a display name and select US or EU from the Region drop-down.
Once you've created an App, you can't move it to another region.
Once a display name is created and a region is selected, a unique App ID will be generated for you.
Select which channels you want and add them to your app.
- Select your channel sender identity, if required, to configure your channel to work with your Conversation API App.
- Update the Callback URL of the underlying channel to point to the channel adapter of the Conversation API.
The Callback URL for most channels will be updated automatically which will overwrite the current Callback URL.
The Conversation API will try to send messages on the channels based on the priority preference you set. If there is no preference set, the API will try the order priority based on the following criteria:
- If a conversation with the contact exists: the active channel of the conversation is tried first.
- The existing channels for the contact, that are ordered by contact channel preferences (if given).
- Lastly the existing channels for the contact are ordered by the App priority.
You can define the App channel priority by reordering the channels that you have set up by taking these steps:
- Click REORDER.
- Drag and drop your channels to the order you want them in.
- Click SAVE.
Webhooks are callbacks triggered by specific events. When adding a Webhook you are prompted to specify a Target URL and events that should trigger a call to the specified URL. To configure webhooks:
- Go to Webhook.site and copy a target URL.
- Go to Apps and click your app name.
- Scroll down and click ADD WEBHOOK.
- Select your Target type, Target URL, Secret token and Triggers
The Secret Token can be used to sign the content of Conversation API callbacks. This way you can verify the integrity of the callbacks coming from Conversation API.
Your Project ID is used to group your Conversation API resources. You can find it by taking these steps:
- Go to your app page.
- In the Project pane, select the project you want to use and copy the Project ID that appears.
Access keys are required for authentication purposes when using the Conversation API. To generate that access keys, take these steps:
- Go to the Account details page and then go to Settings > Access Keys and click NEW KEY.
A client_id and client_secret will be provided when creating an Access Key in the portal. The secret is only shown after generation, copy and store it in a safe place.
To obtain an Access Token to Conversation API, use your clientid and clientsecret and call the OAuth 2.0 Token endpoint:
curl https://eu.auth.sinch.com/oauth2/token -d grant_type=client_credentials --user <client_id>:<client_secret>
curl https://auth.sinch.com/oauth2/token -d grant_type=client_credentials --user <client_id>:<client_secret>
The access token can be used in conjunction with your project ID to interact with the Conversation API. Read more about possible authentication methods at Authentication.
A Postman collection is available to download. There you can find examples to access our API endpoints.
In the collection there are variables that you need to fill with your own values and IDs to be able to send the requests:
The collection includes requests to manage your resources and to create the same Conversation App that we created on the portal via these requests!
You will also find requests to send messages and events to your contact via
* `TEXT` * `MEDIA` * `CHOICE` * `CARD` * `CAROUSEL` * `LOCATION` * `EVENT`
Conversation API integrates multiple channels that you can try. Channel Support contains detailed examples and screenshots about message types that you can try on supported channels!