Calls API

The JAICP 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

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

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.

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://app.jaicp.com/, the request URL for adding phone numbers to the campaign will look like this:

https://app.jaicp.com/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.

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://app.jaicp.com/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://app.jaicp.com/api/calls/campaign/8231.7056.1b131df1/addPhones' \
--header 'Content-Type: application/json' \
--header 'Idempotence-Key: d5f41bd4' \
--data-raw '[
    {
        "phone": 16500000000
    }
]'

How to use

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.

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.

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.