Using RESTful APIs

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 System Configurator > User and Role Management > Users > [user] > Authentication > Assign Expiration Time for Service Account.

• 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.

1. For a new GET request define:
   1. Request URL: in this case an URL ending with rci/queues (1)
   2. Authorization type: basic authentication (2)
   3. User ID and password for basic authentication (3)

      This is your Sinch Contact Pro user.

   4. API Key header and password you received from Sinch (4)

   

   

2. 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.

1. Define the following:
   1. Request URL: in this case an URL ending with cmi/callbacks
   2. Authorization type: basic authentication
   3. User ID and password for basic authentication

      This is your Sinch Contact Pro user.

   4. API Key header and password you received from Sinch
2. Check that you have selected the PUT command and change data to be raw and JSON.
3. Copy an example from the CMI API document, modify it, and paste your query into the text input box.

   

4. Send your query.
5. 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.

1. Define the following:
   1. Request URL: in this case an URL ending with rmi/queueStatuses
   2. Authorization type: basic authentication
   3. User ID and password for basic authentication

      This is your Sinch Contact Pro user.

   4. API Key header and password you received from Sinch
2. Check that you have selected the GET command.
3. Fetch all queues and waiting times by calling rmi/queueStatuses.
4. 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:

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.