Управление своими звонками (calls_by_participation)
Обзор
Управляет существующими активными звонками (диалогами B2B) посредством команд API (без использования инициатив со стороны SIP-устройств).
Управлению доступны любые звонки: инициированные как через API, так и с SIP-устройств и сервисов SIP-UA. В отличие от API /rest/v1/uc/calls текущий endpoint предоставляет доступ только к тем диалогам, где одним из участников является учетная запись SIP-пользователя, принадлежащая пользователю, который выполняюет API-запрос.
Обслуживание запросов производится ролью mware.
Для работы требуется наличие роли callstore.
Запросы
| HTTP verb | Endpoint | Описание |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Получение списка звонков (GET)
Возвращает список активных диалогов в пределах текущего домена.
У любого диалога есть две стороны: вызывающая (A) и вызываемая (B). Абонентов, представляющих сторону B, может быть один или несколько в зависимости от состояния диалога.
Диалог относится к домену, если хотя бы один из его абонентов (плеч диалога) принадлежит домену (является учетной записью провайдера, SIP-пользователя, конференцией или сценарием IVR).
Результат выполнения запроса проходит дополнительную фильтрацию. Возвращаются только те диалоги, одним из участников которых является авторизованный пользователь (через любую из принадлежащих ему учетных записей sipuser).
Запрос
| Имя | Тип | Описание |
|---|---|---|
|
|
Фильтр по значениям полей. |
|
|
Список полей для вывода. Доступные поля для выдачи: |
|
|
Смещение в списке ресурсов, подлежащих выдаче. |
|
|
Максимальное количество ресурсов в списке. |
|
|
Порядок сортировки ресурсов в списке. |
|
|
Преобразование в плоский вид составных полей. |
|
|
Возврат лишь количества элементов. |
GET /rest/v1/uc/calls_by_participation?offset=0&limit=1 HTTP/1.1Ответ
Возвращает список объектов, каждый из которых представляет собой отдельный диалог. Состав возвращаемых полей ограничен: acallid, callids, dialogid, esgdlg, esgcallid, inviteid, status, legs, localuri, remoteuri, site, startts, uris, opts.
При указании других полей в параметре mask они будут проигнорированы.
| Поле | Описание |
|---|---|
|
Call-Id инициирующей стороны диалога. Содержится в соответствующем заголовке инициирующего SIP-запроса INVITE. |
|
Список всех Call-Id активных участников диалога. Каждая сторона диалога имеет свой Call-Id, каждый вызываемый форк имеет уникальный Call-Id. |
|
Идентификатор активного диалога, применяемый при формировании endpoint. Уникален в рантайме, однако не является глобально уникальным и может повторяться через некоторое время в рамках одной и той же системы. |
|
Идентификатор диалога роли esg. Имеет непустое значение только в том случае, если диалог создан на основании внешнего входящего звонка с учетной записи провайдера. Может использоваться в качестве идентификатора сессии обслуживания внешнего абонента, поскольку в ходе перевода звонка диалог esg не изменяется. |
|
CallId внешнего абонента, скрытый за ролью esg. Имеет непустое значение только в том случае, если диалог создан на основании внешнего входящего звонка с учетной записи провайдера. |
|
Глобально уникальный идентификатор вызова, приводящего к диалогу. Формируется при поступлении в систему SIP-запроса INVITE и существует вплоть до завершения диалога. Присутствует во всех событиях CDR класса callevents. |
|
Генеральное состояние диалога. Варианты значений:
На деле машина состояний диалога имеет гораздо больше состояний, но все они укладываются в генеральные состояния. |
|
Список плеч диалога.
Каждый диалог всегда имеет ровно одного инициатора (вызывающая сторона
В генеральном состоянии
Каждый элемент списка является объектом. |
|
Строковое представление URI из заголовка Формат: |
|
Строковое представление URI из заголовка Формат: |
|
Название сайта, серверы которого обслуживают диалог. |
|
Тайм-штамп времени поступления инициирующего SIP-запроса INVITE в систему. Является представлением момента времени и может быть преобразован к конкретной дате в любом часовом поясе. Например, |
|
Список всех URI, участвующих в звонке. Каждый SIP-пользователь, являющийся абонентом диалога, имеет два URI, один из которых указан через |
|
Объект с дополнительными параметрами диалога. Содержит:
|
| Поле | Описание |
|---|---|
|
Call-Id плеча. Содержится в соответствующем заголовке SIP-запроса INVITE (полученного или отправленного). |
|
Ограничение времени вызова абонента в миллисекундах. Имеет значение только для плеча стороны |
|
Строковое представление local URI. Для плеча стороны Формат: |
|
Строковое представление remote URI. Для плеча стороны Формат: |
|
Код стороны диалога:
|
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[
{
"acallid": "3113017065@192.168.0.149",
"callids": [
"rB2-002-484FD3-01-3113017065@192.168.0.149",
"3113017065@192.168.0.149"
],
"dialogid": "rDlg-002-484FD3",
"esgdlg": "",
"esgcallid": "",
"inviteid": "357924f1-0623-b685-c105-b80000000002",
"legs": [
{
"callid": "3113017065@192.168.0.149",
"expirets": "undefined",
"localuri": "<sip:sip3@test.rootdomain.ru>",
"remoteuri": "<sip:sip2@test.rootdomain.ru>",
"side": "a"
},
{
"callid": "rB2-002-484FD3-01-3113017065@192.168.0.149",
"expirets": 30000,
"localuri": "<sip:12@test.rootdomain.ru>",
"remoteuri": "<sip:sip3@test.rootdomain.ru>",
"side": "b"
}
],
"localuri": "<sip:sip3@test.rootdomain.ru>",
"opts": {
"referred-by": "<sip:sip1@test.rootdomain.ru>"
},
"remoteuri": "<sip:sip2@test.rootdomain.ru>",
"site": "SITE1",
"startts": 1571747612067,
"status": "forking",
"uris": [
"<sip:12@test.rootdomain.ru>",
"<sip:sip3@test.rootdomain.ru>",
"<sip:sip3@test.rootdomain.ru>",
"<sip:sip2@test.rootdomain.ru>"
]
}
]Инициация нового звонка (POST)
Инициирует вызов абонента X (номер в поле from) в режиме интерком, после ответа производит его перевод (SIP-запрос REFER) на абонента Y (номер в поле to).
Для инициации режима интерком-вызова в системе должен существовать featurecode соответствующего типа и быть доступен в маршрутизации как минимум для абонентов по направлению к самим себе, а также для абонента 100 (callmanager).
Операция проводится через запуск скрытого служебного сценария, осуществляющего подготовленный дозвон до инициатора
(компонент сценария Исходящий звонок)
с передачей управления специально подготовленному скрытому IVR-сценарию с компонентом Перевод на номер.
В качестве номера для перевода подставляется указанный номер to.
Схема процесса: IVR→X, IVR REFER Y, X→Y.
Запрос выполняется асинхронно. Ответ на запрос возвращается в момент, определяемый параметром response_mode.
Контекст процесса инициации вызова постепенно наполняется данными о звонке по мере его выполнения.
Содержание данных в ответе соответствует моменту его возврата – чем более поздняя точка процесса выбрана, тем больше данных и точнее результат.
События CDR целевого звонка могут быть получены из интерфейса подписки на события системы.
Абонент, от имени которого заказан исходящий звонок, после снятия трубки слышит все сигналы КПВ организованного исходящего вызова.
Запрос проходит предварительную фильтрацию. Для допуска к выполнению необходимо, чтобы авторизованный пользователь был инициатором нового вызова. То есть указанное значение параметра "from" относилось к авторизованному пользователю (через любую из принадлежащих ему учетных записей sipuser).
Запрос
| Имя | Тип | Описание | ||
|---|---|---|---|---|
|
|
Режим указания стороны X инициатора создаваемого вызова. Возможные варианты:
|
||
|
|
В зависимости от режима ( |
||
|
|
Номер вызываемого абонента Y. Позволяет задавать символы “'” и “,”. Первый такой символ выделяет оставшуюся последовательность в качестве донабора DTMF после получения ответа, а каждый последующий такой символ обеспечивают паузу в 1 секунду в наборе DTMF. |
||
|
|
Номер инициатора первого вызова. Отображается абоненту X. По умолчанию используется значение поля |
||
|
|
Имя инициатора первого вызова. По умолчанию |
||
|
|
Таймаут первого вызова в сеундах. Является ограничением стандартного время вызова. По умолчанию 30 сек. |
||
|
|
Метка, привязываемая к звонку. По умолчанию не назначается. |
||
|
|
Режим возврата ответа. Чем больше значение, тем позже отправляется ответ, и тем больше контекстной информации в ответе содержится. Возможные варианты:
По умолчанию |
||
|
|
Выключатель режима intercom для вызова абонента. По умолчанию выключено.
|
POST /rest/v1/uc/calls_by_participation HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"from": "14",
"to": "16",
"mode": "number",
"callerid": "100",
"callername": "callmanager",
"calltimeout": 30,
"use_intercom": true,
"binding": "sample_binding",
"response_mode": 5
}Ответ
| Поле | Описание |
|---|---|
|
Итоговый результат по операции. Варианты значений. |
|
Call-Id инициирующего автоматического звонка IVR→X (отличается от CallId плеч целевого диалога). Присутствует в любом случае. |
|
Call-Id звонка, поступившего в систему от абонента X к абоненту Y после обработки SIP-запроса REFER. Это Call-Id плеча |
|
Response-Line последнего полученного ответа от абонента Y, по результатам которого сформирован ответ на запрос. При некоторых неудачных результатах операции может отсутствовать. |
|
Идентификатор целевого диалога X→Y. При некоторых неудачных результатах операции может отсутствовать. Также может отсутствовать если длительность диалога 0 секунд. |
| Значение | Описание |
|---|---|
|
Ответ сформирован на этапе, где не выявлено проблем для успешного создания диалога X→Y. Например, для
|
|
Вызов IVR→X завершился неудачей ( В случае, если неудачный ответ получен от абонента X, результат не содержит информации о диалоге X→Y, поля |
|
Вызов IVR→X завершился переадресацией SIP-UA ( Значение является гипотетическим, поскольку обработкой |
|
Вызов IVR→X после предварительного ответа завершился таймаутом. Значение является гипотетическим, поскольку при отсутствии финального ответа сервер (роль b2b), завершает вызов автоматической эмуляцией ответа |
|
Не получен ответ от абонента X, либо другая неожиданная ситуация. В ответе могут отсутствовать поля |
|
Абонент X удачно ответил на вызов IVR→X, состояние вызова X→Y неизвестно из-за отсутствия или неизвестного содержания SIP-запросов NOTIFY в диалоге, обслужившим REFER. |
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"result": "ok",
"ivrcallid": "rIV-006-J8zgklJrGuVxZSlo1ZUWOjjJyl1",
"acallid": "3099649154@192.168.0.149",
"dialogid": "rDlg-002-6FpTv2",
"last_response": "SIP/2.0 100 Trying"
}Поиск идентификатора звонка (LOOKUP)
Производит поиск ресурса (активного диалога) по указанному ключу.
Возвращается список идентификаторов обнаруженных диалогов, подходящих по условиям поиска.
Применение поисковых полей производится по одному в порядке убывания приоритета в приведенной ниже таблице. Поисковые поля содержат в описании "Значение для поиска". Множественный возврат возможен, например, в случае поиска по логину SIP-пользователя, если он участвует в нескольких диалогах.
Результат выполнения запроса проходит дополнительную фильтрацию. Обнаруживаются только те диалоги, одним из участников которых является авторизованный пользователь (через любую из принадлежащих ему учетных записей sipuser).
Запрос
| Параметр | Тип | Описание |
|---|---|---|
|
|
Значение для поиска. Идентификатор диалога, применяемый при формировании endpoint. Уникален в рантайме, однако не является глобально уникальным и может повторяться через некоторое время в рамках одной и той же системы. Например, |
|
|
Значение для поиска. Глобально уникальный идентификатор вызова, приводящего к диалогу. Формируется при поступлении в систему SIP-запроса INVITE и существует вплоть до завершения диалога. Присутствует во всех событиях CDR класса callevents. Например |
|
|
Значение для поиска. Идентификатор звонка Например, |
|
|
Значение для поиска. SIP URI: |
|
|
Значение для поиска. Номер телефона или логин SIP-пользователя, используемые в качестве Может использовать дополнительный параметр
По умолчанию Обнаруживаются диалоги, где одной из сторон выступает указанный абонент текущего домена.
Поиск производится аналогично |
|
|
Значение для поиска. Идентификатор учетной записи SIP-пользователя. |
|
|
Значение для поиска. Логин учетной записи SIP-пользователя. |
|
|
Значение для поиска. Номер телефона учетной записи SIP-пользователя. |
|
|
Значение для поиска. Идентификатор учетной записи пользователя системы. Если имеет место привязка учетных записей SIP-пользователей к пользователю системы, то обнаруживаются диалоги, где один из этих SIP-пользователей является одним из абонентов. |
LOOKUP /rest/v1/uc/calls_by_participation HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"callid": "rB2-002-XPhrjh-01-3587482024@192.168.0.146"
}