Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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

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

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

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

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

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

Table of Contents

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

Expand
titleРазвернуть

Имя

Тип

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

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

Описание

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 останется последней в разговоре

wait_for_pickup

long

нет


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

Максимальное время ожидания снятия трубки в секундах. Сначала ожидается снятие трубки номерами-источниками вызова, затем ожидается снятие трубки на номере назначения 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 для ресурса истории вызовов

Info

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

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

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

  • ext_id = 34535

  • caller_id_name = Ivan

Tabs
[{"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"}]

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

Expand
titlePOST /extension/{extension_id}/callback/

POST /extension/{extension_id}/callback/

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

Параметры URL

Имя

Тип

extension_id

string

Параметры JSON

Имя

Тип

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

allow_public_transfer

boolean

нет

announce_sound_id 

long

нет

call_duration

long

нет

caller_id_name

string

нет

caller_id_number

string

нет

dst_ani 

string

нет

dst_announce_sound_id 

long

нет

dst_dtmf

string

нет

dst_num

string

да

src_caller_id_name

string

нет

src_caller_id_number

string

нет

src_num

array [string]

да

transfer_after_dst_hangup 

string

нет

transfer_after_src_hangup

string

нет

wait_for_pickup

long

нет

Поля ответа

Имя

Тип

call_api_id

string

call_id

string