Using RESTful APIs

If your system has Restful Interfaces installed and enabled, 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.

Table 1. Restful interfaces
Function Restful interface
Configuration Restful Configuration Interface (RCI)
Operation
  • Contact Management Interface (CMI)
  • Directory and Presence Interface (DPI)
  • Outbound Interface (OBI)
  • Restful Task Interface (RTI)
Monitoring and reporting
  • Restful Analytics Interface (RAI)
  • License Reporting Interface (LRI)
  • Restful Monitoring Interface (RMI)

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 in Infrastructure Administrator (IA)
    Note: Treat the API keys like any password or secret. It's recommended that you occasionally rotate:
    • the API keys
    • 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.

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 (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
  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
  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:

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

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