Using RESTful APIs
As Sinch Contact Pro comes with a comprehensive out-of-the-box restful interface (RI) offering, you can control objects, such as queues, users, and conversations, via APIs.
This section shows you how to perform basic actions by using an API platform such as Postman. The API stacks are split into different resources according to their purpose.
Function | Restful interface |
---|---|
Configuration | Restful Configuration Interface (RCI) |
Operation | |
Monitoring and reporting |
Every resource has its own access control to ensure that users have access only to objects they need. The objects in the Sinch Contact Pro system have identifying IDs but you can fetch them without the ID. It's only required when accessing them.
Prerequisites
- APIs enabled
APIs are not enabled by default so to open the access, create a service request to Sinch. Once the access is opened, you will receive an API key and a URL to access the resources.
Note: Treat the API keys like any password or secret. It's recommended that you occasionally rotate:- the API keys via a service request to Sinch
- API users’ passwords in System Configurator (SC)
- A Sinch Contact Pro user who has rights to the objects they need to
control, such as a queue or user.
You can limit access on a detailed level with the built-in user rights model the same way as with agent user rights. For example, if the purpose is to check how many customers are queueing in a queue called Sales Queue, the user rights can be limited so that the user has only rights for the Sales Queue.
We recommend that you create several API users who have dedicated tasks. This way one account can't see, edit, or delete too much data, and losing one user ID/password combination isn't too harmful. It's easier to inactivate a compromised account without affecting too many integrations. The normal Sinch Contact Pro password policy applies also to the API users. For extending the password expiration time, use the setting .
- Traffic from the corporate LAN to Amazon Web Services (AWS)
allowed
You need to add to the allowlist all IP address ranges of the AWS region on which your tenant is running. Allow addresses as instructed in AWS IP address ranges.
However, if you want to limit API access to certain source IP addresses only, you have to send Sinch a detailed list of IP addresses. Note that if your integration service is running on a cloud service with dynamic addressing, the integration could stop working if your service gets a new dynamically assigned IP address which isn't listed.
Using restful interfaces
Choose an API platform tool such as Postman. For instructions how to use the tool you've chosen, see their documentation.
Example 1
This example shows how to read and access data stored in Sinch Contact Pro. In this example, we read all queues in the system the user has rights to read. This happens with the RCI\queue resource.
- For a new GET request define:
- Request URL: in this case an URL ending with rci/queues (1)
- Authorization type: basic authentication (2)
- User ID and password for basic authentication (3)
This is your Sinch Contact Pro user.
- API Key header and password you received from Sinch (4)
- Submit the request and you receive a list of queues you have rights to. For
example, if you have rights only to Queue A and not to Queue B, the query
returns only Queue A.
Example 2
This example shows how to insert data into Sinch Contact Pro with the PUT command. In this example, we create a new callback request using the cmi/callbacks resource.
- Define the following:
- Request URL: in this case an URL ending with cmi/callbacks
- Authorization type: basic authentication
- User ID and password for basic authentication
This is your Sinch Contact Pro user.
- API Key header and password you received from Sinch
- Check that you have selected the PUT command and change data to be raw and JSON.
- Copy an example from the CMI API document, modify it, and paste your query into
the text input box.
- Send your query.
- Wait for the response and check response status and possible response body. If
you receive a status code 4XX or 5XX, check the error message.Note: PUT and POST requests try to update/create the resources every time you execute the request (by clicking Send in Postman). Depending on the resource, this may cause unwanted effects, so make sure you check the responses each time.
Example 3
This example shows how to read data from a specific resource. In this example, we fetch waiting times for a specific queue. The best way to fetch queue waiting time is rmi/queueStatuses.
- Define the following:
- Request URL: in this case an URL ending with rmi/queueStatuses
- Authorization type: basic authentication
- User ID and password for basic authentication
This is your Sinch Contact Pro user.
- API Key header and password you received from Sinch
- Check that you have selected the GET command.
- Fetch all queues and waiting times by calling rmi/queueStatuses.
- To see one one specific queue, add the queue ID to the URL.
For example:
rmi/queueStatuses/AB2800D286F74EAB97B1072DC75A943D
Possible errors
It may happen that your query fails. All errors that a restful interface returns are HTTP error codes. Below are the most common errors with descriptions:
Error | Description |
---|---|
400 (http 400) – Bad Request | The request is not formatted correctly. |
401 (http 401) – Unauthorized. | The request has not been applied because it lacks valid authentication credentials for the target resource. Check the API key and your Sinch Contact Pro user. |
403 (http 403) – Forbidden | Authentication is correct but the user is not allowed to access the resource. Check user rights of the Sinch Contact Pro user. |
404 (http 404) - Not Found | The requested resource couldn't be found. Check the URL and its spelling.The URL is case sensitive. |
429 (http 429) | See Optimizing Your RI Query below. |
500 (http 500) - Internal Server Error | There is an issue in Sinch Contact Pro. If the error situation continues, contact Sinch. |
Optimizing your RI query
A wrongly made RI query can affect system performance and therefore we highly recommend you optimize and limit your queries:
- If you need to poll data in intervals, consider how often the data is needed. For example, polling interval 10 minutes compared to 10 seconds makes a big difference.
- Always limit your search by defining a time range instead of polling everything in the system. Longer queries will access reporting databases and will be slower whereas more recent data is returned from cache.
- Especially in systems with a large amount of data, limit the queries with relevant query parameters and filters.
- Pay attention to response times.
If your requests continuously take a long time, to protect your tenant’s performance for the live conversations, do the following:
- Consider limiting the query further.
- Execute your queries in smaller batches (for example shorter time range or fewer objects).
- Wait for your query to finish before you send the exactly same query again.
- In some cases consult Sinch via a service request to optimize your queries.
- The API gateway has a hard limit of 29 seconds. If your queries take longer, the API gateway will time out your query and return an error response. This limit can't be changed but instead you need to optimize your queries.
- Limiting user rights is recommended to protect your system but it also speeds up responses.
- We recommend you have a specific RI user for specific tasks. This way possible issues with a user do not break all integrations.
- The API gateway Sinch has created for you has a request quota. You can ask Sinch to increase the quota via a service request if you start receiving 429 responses.
- If you need to develop and test complex integrations, we recommend you place an order for an additional Sinch Contact Pro test tenant.