Calls API

The JAICP platform provides the Calls API to work with telephony.

The API provides the following capabilities:

Adding phone numbers with parameters to the broadcast.
Obtaining a report by the call task ID.
Obtaining a report by the phone number for a single broadcast.

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

API methods

A detailed description of the Calls API: methods, request parameters, response formats, examples, returned errors >

Access control is checked by the broadcast token only.

The API provides the following methods:

Method	Description
`POST https://<host_name>/api/calls/campaign/{token}/addPhones`	Adding phone numbers with parameters to the broadcast.
`POST https://<host_name>/api/calls/campaign/{token}/getReport`	Obtaining a `JSON` report via a call task ID or via a phone number.
`POST https://<host_name>/api/calls/campaign/{token}/callJob/cancel`	Canceling new calls to a phone number or call task ID. Please note that you can only cancel calls to numbers that are added using the Calls API.
`POST https://<host_name>/api/calls/campaign/{token}/control/start`	Starting a new voice broadcast.
`POST https://<host_name>/api/calls/campaign/{token}/control/pause`	Pausing a voice broadcast.
`POST https://<host_name>/api/calls/campaign/{token}/control/resume`	Resuming a paused voice broadcast.
`POST https://<host_name>/api/calls/campaign/{token}/control/stop`	Stopping a voice broadcast.

You can copy host_name from the address bar; it is formatted as follows: http://<host_name>.just-ai.com/.

For example, for https://zb04.just-ai.com/ the method for phone number addition will have the following form:

https://zb04.just-ai.com/api/calls/campaign/123456.789.mBoMyfZLZqKHIPKjFjWYfRw9hgfIV9InFC4bHGVw5ND/addPhones

The token is configured when creating a voice broadcast in the platform. To copy the token, navigate to the broadcast list > click the icon next to the broadcast name > Copy API token.

When adding a phone number to a specific broadcast queue, a call task with a unique ID is created. Here, if this phone number is added to this broadcast again, a new call task with another ID will be created.

Note that the report about the calls completed will contain information about call date, duration and result as well as all data written to the script by the method $dialer.reportData($header, $value, $order).

Defining a call policy via the Calls API

You can configure custom calling parameters when you use API to add a number to a calling campaign.

To do so, pass the CallJobParameters parameters in the query body when you invoke the addPhones method.

If no parameters are passed, the number is added to the queue and calls are made as usual. If you add a custom policy number, it gets higher priority than other numbers according to the calling policy.

Learn more about calling policies

Call statuses

In the API response, the field jobStatus describes the status of the number for each call at the time of report generation.

Значение поля	Описание
`longСallWithResult`	A result has been set after the call completion.
`longCallWithNoResult`	No result has been set after the call completion.
`noAnswer`	No subscriber response has been detected for all call attempts.
`planned`	The call is currently queued, for example, because all the lines are busy now.
`notDone`	This status will be set if the broadcast has been completed but no calls were made. For example, the broadcast was completed manually.
`inProcess`	Call attempt or conversation with a subscriber is in progress.
`onRetry`	A retry.
`canceled`	The status will be set if the calls were canceled via Calls API.
`nonexistentNumber`	The status will be set if the call is made to a non-existent phone number.