Протестировать методы API можно на странице интерактивного обозревателя API и без написания кода
Некоторые ресурсы, описанные на странице, по умолчанию могут быть не доступны из-за типа приложения (см. Создание и авторизация приложений)

Ресурс инициации вызова позволяет с помощью API инициировать вызов между номерами. После успешного API-запроса системой вызываются все номера-источники вызова, а после поднятия трубки одним из них начинает вызываться номер назначения.

В ресурсе можно использовать Переменные . Необходимо сначала задать их в ресурсе Переменные . Затем при запросе на callback их можно использовать вместо параметров запроса через:

  1. “@{VAR_NAME}” , если это extension_id в url запроса

  2. “$cv({VAR_NAME})” , если это параметр в теле запроса

Переменные может использовать только пользователь клиента. См. пример ниже

Описание структур данных

Имя

Тип

Обязательный

Значение по умолчанию

Описание

allow_public_transfer

boolean

нет

true

Разрешать перевод вызова при звонке на внешний номер

announce_sound_id

long

нет

Идентификатор звука, который проиграется при поднятии трубки номером-источником до того, как начнет вызываться номер назначения

call_duration

long

нет

Системное значение

Максимальная продолжительность разговора в секундах

caller_id_name

string

нет


Имя вызывающего абонента. Если значение не будет задано, будет использовано имя внутреннего номера, от имени которого инициируется вызов

caller_id_number

string

нет


Номер вызывающего абонента. Если значение не будет задано, будет использован внутренний номер, от имени которого инициируется вызов

src_ani

string

нет

Номер из списка внешних номеров клиента, который будет передан в качестве АОНа при вызове внешнего номера или номеров из массива src_num. Не передается на внутренние номера. В случае указания номера не из списка внешних номеров клиента (DID) src_ani будет проигнорирован

dst_ani

string

нет


Номер из списка внешних номеров клиента, который будет передан в качестве АОНа при вызове внешнего номера из dst_num. Не передается на внутренние номера. В случае указания номера не из списка внешних номеров клиента (DID) dst_ani будет проигнорирован

dst_announce_sound_id

long

нет


Идентификатор звука, который проиграется при поднятии трубки на вызываемой стороне, будет слышен всем участникам разговора. Проигрывается только для звонков по внешней сети.

dst_dtmf

string

нет


Последовательность DTMF-тонов, которые будут переданы номеру dst_num, как только вызов dst_num будет отвечен. Допустимы цифры 0123456789*#, а также символы W и w. W – пауза длиной в одну секунду, w – пауза длинной в полсекунды

dst_num

string

да


Номер назначения вызова. В отличии от src_num, тут отрабатывают все правила входящего вызова для номера и могут быть указаны очереди, голосовое меню (IVR)

src_caller_id_name

string

нет


Имя вызывающего абонента, которое будет передано на номера из src_num. Если значение не будет задано, будет использован параметр caller_id_name. Если caller_id_name не задан, будет использовано имя внутреннего номера, от имени которого инициируется вызов

src_caller_id_number

string

нет


Номер вызывающего абонента, который будет передан на номера из src_num. Если значение не будет задано, будет использован параметр caller_id_number. Если caller_id_number не задан, будет использован внутренний номер, от имени которого инициируется вызов

src_num

string

да


Массив номеров-источников вызова, например, список внутренних и/или мобильных номеров. Тут не могут быть указаны внутренние номера типа "IVR". Номера из массива вызываются без учета правил входящего вызова

transfer_after_dst_hangup

string

нет


Номер, на который система переведет вызов, если сторона инициации вызова src_num останется последней в разговоре

transfer_after_src_hangup

string

нет


Номер, на который система переведет вызов, если сторона назначения dst_num останется последней в разговоре

callback_rate_limit

int

нет

У каждого клиента существует ограничение на количество вызовов - calls limit. В случае, если необходимо, чтобы callback не занимал весь лимит звонков, а только % вызовов от calls limit - необходимо указать callback_rate_limit от 0% до 100%, чем больше %- тем выше вероятность, что callback не пройдет, а при 100% callback точно отобьется ошибкой callback_rate_limit_exceeded

variables

dict

нет

Динамические переменные, подробнее читать тут: Переменные (Динамические переменные, переданные в callback)

Пример использования callback с variables:

{
  "dst_num": "000116644",
  "src_num": [
    "341"
  ],
  "variables": {"autoanswer": "4", 
  "testvar": "'testval"}
}

wait_for_pickup

int

нет


Системное значение

Максимальное время ожидания снятия трубки в секундах. Сначала ожидается снятие трубки номерами-источниками вызова, затем ожидается снятие трубки на номере назначения dst-num. Если на dst-num проиграется early-media, то с момента проигрывания early-media возобновится таймер времени ожидания wait_for_pickup. Если за время wait_for_pickup трубка не будет снята, вызов не будет совершен (в случае передачи параметров transfer_after_* рекомендуется дожидаться истечения таймеров wait_for_pickup)

call_api_id

string

да


Возвращается в ответ на запрос callback. Используется для возможности последующего управления вызовом

call_id

string

да


Возвращается в ответ на запрос callback и является его идентификатором. По нему можно фильтровать события, относящиеся к данному callback, получать отчеты по его результатам. Является синонимом call_uuid для ресурса истории вызовов

Результат callback
После инициации вызова можно осуществить запрос на ресурс “История вызовов (/call_history/, /calls/)”:
GET /client/{client_id}/call_history/{call_uuid}
указав полученный в результате инициации вызова "call_id" в качестве "{call_uuid}"

Пример использования переменных в запросе

Использовать уже заданные в ресурсе Переменные переменные :

  • ext_id = 34535

  • caller_id_name = Ivan

[{"content":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"В разделе "},{"type":"text","text":"authentication ","marks":[{"type":"strong"}]},{"type":"text","text":"в поля "},{"type":"text","text":"client_id ","marks":[{"type":"strong"}]},{"type":"text","text":"и "},{"type":"text","text":"client_secret  ","marks":[{"type":"strong"}]},{"type":"text","text":"требуется ввести полученные при регистрации приложения значения "},{"type":"text","text":"Application_ID ","marks":[{"type":"strong"}]},{"type":"text","text":"и "},{"type":"text","text":"Application_Secret","marks":[{"type":"strong"}]},{"type":"text","text":", затем нажать на кнопку \""},{"type":"text","text":"Try it out!","marks":[{"type":"strong"}]},{"type":"text","text":"\". Если данные приложения верны, в ответ вернётся токен доступа ("},{"type":"text","text":"access_token","marks":[{"type":"strong"}]},{"type":"text","text":"). Полученный токен доступа следует ввести в поле \""},{"type":"text","text":"Access Token Field","marks":[{"type":"strong"}]},{"type":"text","text":"\" вверху страницы и сохранить его нажатием кнопки \""},{"type":"text","text":"Set Token","marks":[{"type":"strong"}]},{"type":"text","text":"\"."}]},{"type":"table","attrs":{"isNumberColumnEnabled":false,"layout":"default"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{},"content":[{"type":"paragraph","content":[{"type":"text","text":"метод"}]}]},{"type":"tableHeader","attrs":{},"content":[{"type":"paragraph","content":[{"type":"text","text":"ресурс"}]}]},{"type":"tableHeader","attrs":{},"content":[{"type":"paragraph","content":[{"type":"text","text":"данные"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{},"content":[{"type":"paragraph","content":[{"type":"text","text":"POST"}]}]},{"type":"tableCell","attrs":{},"content":[{"type":"paragraph","content":[{"type":"text","text":"/extension/@ext_id/callback/"}]},{"type":"paragraph","content":[]}]},{"type":"tableCell","attrs":{},"content":[{"type":"paragraph","content":[{"type":"text","text":"{\"caller_id_name\": \"$cv(caller_id_name)\",","marks":[{"type":"code"}]},{"type":"hardBreak"},{"type":"text","text":"\"dst_num\": \"string\",","marks":[{"type":"code"}]},{"type":"hardBreak"},{"type":"text","text":"\"src_num\": [\"string\"]}","marks":[{"type":"code"}]}]}]}]}]},{"type":"paragraph","content":[]}]},"id":"1ab97921-e7ca-452f-965a-4a763b57f8d3","label":"Интерактивный обозреватель API    ","type":"tab"},{"content":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Для отправки запросов с помощью программы cURL установим значения переменных "},{"type":"text","text":"url ","marks":[{"type":"strong"}]},{"type":"text","text":"и "},{"type":"text","text":"access_token","marks":[{"type":"strong"}]},{"type":"text","text":":"}]},{"type":"paragraph","content":[{"type":"text","text":"export url=\"https://<hostname>/api/ver1.0\"","marks":[{"type":"code"}]},{"type":"text","text":" "},{"type":"hardBreak"},{"type":"text","text":"(где hostname — hostname API-сервера провайдера IP-телефонии),"}]},{"type":"paragraph","content":[{"type":"text","text":"export access_token=\"8SNsrS0jV35vfmKqKeKtRrHfpbg4UX\"","marks":[{"type":"code"}]},{"type":"text","text":" "},{"type":"hardBreak"},{"type":"text","text":"(полученный токен доступа)."}]},{"type":"paragraph","content":[{"type":"text","text":"Отправим запрос:"}]},{"type":"codeBlock","attrs":{"language":"shell"},"content":[{"type":"text","text":"curl -H \"Authorization: Bearer ${access_token}\"  -H \"Content-Type: application/json\" -d '{\"caller_id_name\": \"$cv(caller_id_name)\",\"dst_num\": \"string\",\"src_num\": [\"string\"]}'  -X POST ${url}/extension/@ext_id/callback/"}]}]},"id":"59f02ace-6798-4ee6-8ed3-7c878969f35b","label":"Программа cURL    ","type":"tab"},{"content":{"version":1,"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Для отправки запросов на языке Python установим значения переменных URL и ACCESS_TOKEN:"}]},{"type":"paragraph","content":[{"type":"text","text":"URL = \"https://<hostname>/api/ver1.0\"","marks":[{"type":"code"}]},{"type":"hardBreak"},{"type":"text","text":"(где hostname — hostname API-сервера провайдера IP-телефонии),"}]},{"type":"paragraph","content":[{"type":"text","text":"ACCESS_TOKEN = \"8SNsrS0jV35vfmKqKeKtRrHfpbg4UX\"","marks":[{"type":"code"}]},{"type":"hardBreak"},{"type":"text","text":"(полученный токен доступа)."}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"type":"text","text":"#!/usr/bin/python\r\n\r\nimport requests\r\n\r\nurl = f'{URL}/extension/@ext_id/callback/'\r\nheaders = {\r\n    'Authorization': f'Bearer {ACCESS_TOKEN}',\r\n    'Content-Type': 'application/json'\r\n}\r\ndata = '''{\"caller_id_name\": \"$cv(caller_id_name)\",\"dst_num\": \"string\",\"src_num\": [\"string\"]}'''\r\nresponse = requests.post(url, headers=headers, data=data)\r\nprint(response.text)"}]}]},"id":"fe3b5416-5aa2-4f51-b4b2-2d3f3e4d8438","label":"На языке Python3    ","type":"tab"}]

Ресурсы раздела "Внутренний номер"

POST /extension/{extension_id}/callback/

Инициировать вызов. Указанный в пути extension_id должен быть идентификатором внутреннего номера типа ‘phone’

Параметры URL

Имя

Тип

extension_id

string

Параметры JSON

Имя

Тип

Обязательный

см “Описание структур данных” выше

см “Описание структур данных” выше

см “Описание структур данных” выше

Поля ответа

Имя

Тип

call_api_id

string

call_id

string