Skip to main content

Calls API

Tovie Platform provides the Calls API for working with outbound telephony.

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

  1. Configure telephony.
  2. Connect a telephone channel.
  3. Create a call campaign.

API methods​

The API provides methods for the following operations:

  1. Adding phone numbers with parameters to the campaign.

    • POST /api/calls/campaign/{token}/addPhones
    • GET /api/crmCalls/campaign/{token}/addPhone
    • POST /api/crmCalls/campaign/{token}/addPhone
    • GET /api/crmCalls/campaign/{token}/test/addPhone

  2. Canceling previously created call jobs.

    • POST /api/calls/campaign/{token}/callJob/cancel

  3. Obtaining reports by call job ID or by phone number.

    • POST /api/calls/campaign/{token}/callJob/getReport
    • POST /api/calls/campaign/{token}/callAttempt/getReport

  4. Retrieving call campaign information.

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

  5. Pausing, resuming, and stopping the campaign.

    • POST /api/calls/campaign/{token}/control/pause
    • POST /api/calls/campaign/{token}/control/resume
    • POST /api/calls/campaign/{token}/control/stop
tip
A detailed description of the Calls API: methods, request parameters, response formats, examples, returned errors

Request parameters​

Required parameters​

Requests to the Calls API must contain the following required parameters:

  • host_name is the host where the campaign is running.
  • token is a unique token for controlling the campaign.
tip
You can obtain the token on the Outbound call campaigns tab by clicking either the  icon next to the campaign name or  > Copy API token.

For example, in the case of https://platform.tovie.ai/, the request URL for adding phone numbers to the campaign will look like this:

https://platform.tovie.ai/api/calls/campaign/8231.7056.1b131df1/addPhones

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://platform.tovie.ai/api/calls/campaign/8231.7056.1b131df1/addPhone?phone=16500000000&Idempotence-Key=d5f41bd4'
POST methods​

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

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

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 caused a request to add a phone number to the campaign to be executed twice. The phone number and the data passed as payload were identical.

  • If the requests did 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.
  • If the requests had an idempotence key, then a duplicate call job will not be created. The second request will return the ID of the same call job as the first request had created earlier.
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 UUID is recommended so that keys are guaranteed to be unique.

The idempotence key applies to all projects and call campaigns on the account. To add the same phone numbers to the different call campaigns, you need to use different idempotence keys.

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.