Skip to main content

Calls API

Tovie DialogStudio provides a Calls API you can use to integrate Tovie DialogStudio telephony service with any external system.

With the help of Calls API you can:

  • start call campaigns;
  • add numbers to your database;
  • get reports for phone numbers and specific campaign tasks.

Getting started​

Before starting your work with the Calls API, you need to:

  1. Configure telephony.
  2. Make a call script.
  3. Configure and start a call campaign.

API methods​

Calls API provides the following methods.

  1. Adding phone numbers to the campaign list.

    • POST https://ds.tovie.ai/api/calls/campaign/{token}/addPhones

  2. Adding phone numbers from CRM to the campaign list.

    • GET https://ds.tovie.ai/api/crmCalls/campaign/{token}/addPhone
    • POST https://ds.tovie.ai/api/crmCalls/campaign/{token}/addPhone
    • GET https://ds.tovie.ai/api/crmCalls/campaign/{token}/test/addPhone

  3. Canceling previously created call jobs.

    • POST https://ds.tovie.ai/api/calls/campaign/{token}/callJob/cancel

  4. Pausing, resuming, and stopping the campaign.

    • POST https://ds.tovie.ai/api/calls/campaign/{token}/control/pause
    • POST https://ds.tovie.ai/api/calls/campaign/{token}/control/resume
    • POST https://ds.tovie.ai/api/calls/campaign/{token}/control/stop

  5. Retrieving call campaign information.

    • GET /api/calls/campaign/{token}
    • GET /api/calls/campaign/{token}/status

  6. Getting reports by call job ID or by phone number.

    • POST https://ds.tovie.ai/api/calls/campaign/{token}/callJob/getReport
    • POST https://ds.tovie.ai/api/calls/campaign/{token}/callAttempt/getReport
tip
A detailed description of the Calls API: methods, request parameters, response formats, examples, returned errors

Calls API token​

All Calls API requests must contain the {token} parameter — a unique identifier providing API access. The new token is generated every time you create a new call campaign from a CRM system.

You can copy the token on the call campaign page:

  1. Go to the Outbound calls tab.
  2. Click Create in the Campaign from CRM system section.
  3. In the Integration section, click Get token → Copy token.

Idempotence key​

In order to control the consistency of the created resources, client applications can generate and pass an idempotence key in their requests to the Calls API.

tip
The idempotence key is a string passed along with the request which guarantees that several requests with the same idempotence key and the same content will return the same response.

If such requests contain no idempotence key or it is different between them, the requests are considered different and are not guaranteed to return equal results.

Passing the idempotence key​

The GET method

For the GET /addPhone method, the idempotence is passed as an Idempotence-Key request parameter:

curl 'https://ds.tovie.ai/api/calls/campaign/8231.7056.1b131df1/addPhone?phone=16123456789&Idempotence-Key=d5f41bd4'

POST methods

All the POST methods require passing the idempotence key in an Idempotence-Key request header:

curl --request POST 'https://ds.tovie.ai/api/calls/campaign/8231.7056.1b131df1/addPhones' \
--header 'Content-Type: application/json' \
--header 'Idempotence-Key: d5f41bd4' \
--data-raw '[
    {
        "phone": 16123456789
    }
]'

How to use​

Passing the idempotency key in the request will help to avoid undesirable call duplicates in case of a technical error.

Suppose that a system failure causes a request to add a phone number to the campaign to be executed twice. The phone number and other data passed are identical in both requests.

  • If the requests do not contain an idempotence key, the first created call job will be followed by a second with its ID distinct from the first, and they will both be put into the queue. Therefore, the bot will call to the specified number twice.
  • If the requests have an idempotence key, then a duplicate call job will not be created. The second request will return the same call job ID as the first request and the bot will not call to the specified number twice.
caution
Use different keys for call campaigns with the same numbers. This way you can add the same numbers to the different call campaigns and avoid call duplicates within one call campaign.

Restrictions​

No restrictions are imposed on the key format: it may be an arbitrary string. However, using UUIDs is recommended so that keys are guaranteed to be unique.

caution
Idempotence keys expire 1 day after their first usage. After that period, requests with a key that was previously used can once again produce duplicates.