Управление звонками (calls)

Содержание

Обзор
Запросы
См. также

Обзор

Управляет существующими активными звонками (диалогами B2B) посредством команд API (без использования инициатив со стороны SIP-устройств).

Управлению доступны любые звонки, инициированные в системе как через API, так и с SIP-устройств и сервисов SIP-UA.

Обслуживание запросов производится ролью mware.

Для работы требуется наличие роли callstore.

Сервис доступен также из сценариев через компонент Операция.

Запросы

HTTP verb Endpoint Описание

HTTP verb	Endpoint	Описание
`GET`	`/rest/v1/uc/calls`	Получение списка звонков (GET)
`POST`	`/rest/v1/uc/calls`	Инициация нового звонка (POST)
`INVITE`	`/rest/v1/uc/calls`	Инициация нового звонка (INVITE)
`INVITEBYIVR`	`/rest/v1/uc/calls`	Инициация нового звонка с обслуживанием в IVR (INVITEBYIVR)
`LOOKUP`	`/rest/v1/uc/calls`	Поиск идентификатора звонка (LOOKUP)
`GET`	`/rest/v1/uc/calls/<id>`	Получение информации о звонке (GET)
`REFER`	`/rest/v1/uc/calls/<id>`	Перевод звонка на номер (REFER)
`REFERREPLACES`	`/rest/v1/uc/calls/<id>`	Перевод звонка с подменой (REFERREPLACES)
`SWITCHCONF`	`/rest/v1/uc/calls/<id>`	Преобразование звонка в конференцию (SWITCHCONF)
`REFERCONF`	`/rest/v1/uc/calls/<id>`	Перевод звонка в конференцию (REFERCONF)
`NOTIFY`	`/rest/v1/uc/calls/<id>`	Отправка события управления устройством (NOTIFY)
`SEND_DTMF`	`/rest/v1/uc/calls/<id>`	Отправка DTMF сигнала в плечо (SEND_DTMF)
`SETUP_ASR`	`/rest/v1/uc/calls/<id>`	Запуск/остановка стенографирования речи одной из сторон (SETUP_ASR)
`SETUP_RECORD`	`/rest/v1/uc/calls/<id>`	Включение/выключение (добавление/удаление) канала записи диалога (SETUP_RECORD)
`SETUP_BINDINGS`	`/rest/v1/uc/calls/<id>`	Управление метками диалога (SETUP_BINDINGS)
`DELETE`	`/rest/v1/uc/calls/<id>`	Завершение звонка (DELETE)

GET

/rest/v1/uc/calls

Получение списка звонков (GET)

POST

/rest/v1/uc/calls

Инициация нового звонка (POST)

INVITE

/rest/v1/uc/calls

Инициация нового звонка (INVITE)

INVITEBYIVR

/rest/v1/uc/calls

Инициация нового звонка с обслуживанием в IVR (INVITEBYIVR)

LOOKUP

/rest/v1/uc/calls

Поиск идентификатора звонка (LOOKUP)

GET

/rest/v1/uc/calls/<id>

Получение информации о звонке (GET)

REFER

/rest/v1/uc/calls/<id>

Перевод звонка на номер (REFER)

REFERREPLACES

/rest/v1/uc/calls/<id>

Перевод звонка с подменой (REFERREPLACES)

SWITCHCONF

/rest/v1/uc/calls/<id>

Преобразование звонка в конференцию (SWITCHCONF)

REFERCONF

/rest/v1/uc/calls/<id>

Перевод звонка в конференцию (REFERCONF)

NOTIFY

/rest/v1/uc/calls/<id>

Отправка события управления устройством (NOTIFY)

SEND_DTMF

/rest/v1/uc/calls/<id>

Отправка DTMF сигнала в плечо (SEND_DTMF)

SETUP_ASR

/rest/v1/uc/calls/<id>

Запуск/остановка стенографирования речи одной из сторон (SETUP_ASR)

SETUP_RECORD

/rest/v1/uc/calls/<id>

Включение/выключение (добавление/удаление) канала записи диалога (SETUP_RECORD)

SETUP_BINDINGS

/rest/v1/uc/calls/<id>

Управление метками диалога (SETUP_BINDINGS)

DELETE

/rest/v1/uc/calls/<id>

Завершение звонка (DELETE)

Получение списка звонков (GET)

Возвращает список активных диалогов в пределах текущего домена.

У любого диалога есть две стороны: вызывающая (A) и вызываемая (B). Абонентов, представляющих сторону B, может быть один или несколько в зависимости от состояния диалога.

Диалог относится к домену, если хотя бы один из его абонентов (плечей диалога) принадлежит домену (является учетной записью провайдера, SIP-пользователя, конференцией или сценарием IVR).

Запрос

Table 1. Параметры запроса
Имя	Тип	Описание
`filter`	`object`	Фильтр по значениям полей.
`mask`	`str`	Список полей для вывода. Доступные поля для выдачи: `acallid, callids, dialogid, esgdlg, esgcallid, inviteid, status, legs, localuri, remoteuri, site, startts, uris, opts`.
`offset`	`int`	Смещение в списке ресурсов, подлежащих выдаче.
`limit`	`int`	Максимальное количество ресурсов в списке.
`order`	`array<object\|str>`	Порядок сортировки ресурсов в списке.
`flat`	`bool`	Преобразование в плоский вид составных полей.
`countonly`	`bool`	Возврат лишь количества элементов.

Подробно про формат параметров GET-запроса

Пример запроса

GET /rest/v1/uc/calls?offset=0&limit=1 HTTP/1.1

Ответ

Возвращает список объектов, каждый из которых представляет собой отдельный диалог. Состав возвращаемых полей ограничен: acallid, callids, dialogid, esgdlg, esgcallid, inviteid, status, legs, localuri, remoteuri, site, startts, uris, opts. При указании других полей в параметре mask они будут проигнорированы.

Table 2. Поля диалога:
Поле	Описание
`acallid`	Call-Id инициирующей стороны диалога. Содержится в соответствующем заголовке инициирующего SIP-запроса INVITE.
`callids`	Список всех Call-Id активных участников диалога. Каждая сторона диалога имеет свой Call-Id, каждый вызываемый форк имеет уникальный Call-Id.
`dialogid`	Идентификатор активного диалога, применяемый при формировании endpoint. Уникален в рантайме, однако не является глобально уникальным и может повторяться через некоторое время в рамках одной и той же системы.
`esgdlgid`	Идентификатор диалога роли esg. Имеет непустое значение только в том случае, если диалог создан на основании внешнего входящего звонка с учетной записи провайдера. Может использоваться в качестве идентификатора сессии обслуживания внешнего абонента, поскольку в ходе перевода звонка диалог esg не изменяется.
`esgcallid`	CallId внешнего абонента, скрытый за ролью esg. Имеет непустое значение только в том случае, если диалог создан на основании внешнего входящего звонка с учетной записи провайдера.
`inviteid`	Глобально уникальный идентификатор вызова, приводящего к диалогу. Формируется при поступлении в систему SIP-запроса INVITE и существует вплоть до завершения диалога. Присутствует во всех событиях CDR класса callevents.
`status`	Генеральное состояние диалога. Варианты значений: `"forking"` – состояние вызова. От инициации до окончательного ответа `2xx` от вызываемой стороны. `"dialog"` – состояние диалога. После окончательного ответа `2xx` от вызываемой стороны до окончания диалога. На деле машина состояний диалога имеет гораздо больше состояний, но все они укладываются в генеральные состояния.
`legs`	Список плечей диалога. Каждый диалог всегда имеет ровно одного инициатора (вызывающая сторона `A`) и произвольное количество вызываемых плечей (сторона `B`) в связи с форкингом. В генеральном состоянии `status=forking`: диалог может содержать более одного вызываемого плеча `B`; вызываемые плечи могут добавляться и удаляться в зависимости от процесса маршрутизации вызова и его реализации для конкретного диалога. В генеральном состоянии `status=dialog` плечо стороны `B`: присутствует в единственном экземпляре; представляет собой ответившего абонента; не изменяется вплоть до завершения диалога. Каждый элемент списка является объектом.
`localuri`	Строковое представление URI из заголовка `To` инициирующего SIP-запроса INVITE (local URI стороны `A`). Формат: `"<sip:USERNAME@DOMAIN>"`, где `USERNAME` и `DOMAIN` строго соответствуют значениям в заголовке.
`remoteuri`	Строковое представление URI из заголовка `From` инициирующего SIP-запроса INVITE (remote URI стороны `A`). Формат: `"<sip:USERNAME@DOMAIN>"`, где `USERNAME` и `DOMAIN` строго соответствуют значениям в заголовке.
`site`	Название сайта, серверы которого обслуживают диалог.
`startts`	Тайм-штамп времени поступления инициирующего SIP-запроса INVITE в систему. Является представлением момента времени и может быть преобразован к конкретной дате в любом часовом поясе. Например, `1571743463336`.
`uris`	Список всех URI, участвующих в звонке. Каждый SIP-пользователь, являющийся абонентом диалога, имеет два URI, один из которых указан через `login`, другой через `phonenumber`.
`opts`	Объект с дополнительными параметрами диалога. Содержит: `referred-by` – значение заголовка Referred-By из инициирующего SIP-запроса INVITE. `replaces` – значение заголовка Replaces из инициирующего SIP-запроса INVITE.

Table 3. Поля плеча диалога в значении поля legs:
Поле	Описание
`callid`	Call-Id плеча. Содержится в соответствующем заголовке SIP-запроса INVITE (полученного или отправленного).
`expirets`	Ограничение времени вызова абонента в миллисекундах. Имеет значение только для плеча стороны `B`.
`localuri`	Строковое представление local URI. Для плеча стороны `А` – из заголовка `To` инициирующего SIP-запроса INVITE, для плеча стороны `B` – из заголовка `From` отправляемого SIP-запроса INVITE. Формат: `"<sip:USERNAME@DOMAIN>"`, где `USERNAME` и `DOMAIN` строго соответствуют значениям в заголовке.
`remoteuri`	Строковое представление remote URI. Для плеча стороны `А` – из заголовка `From` инициирующего SIP-запроса INVITE, для плеча стороны `B` – из заголовка `To` отправляемого SIP-запроса INVITE. Формат: `"<sip:USERNAME@DOMAIN>"`, где `USERNAME` и `DOMAIN` строго соответствуют значениям в заголовке.
`side`	Код стороны диалога: `"a"` – вызывающая сторона; `"b"` – вызываемая сторона.

Пример ответа

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 целевого звонка могут быть получены из интерфейса подписки на события системы.

Абонент, от имени которого заказан исходящий звонок, после снятия трубки слышит все сигналы КПВ организованного исходящего вызова.

Запрос

Table 4. Параметры запроса
Имя	Тип	Описание
`mode`	`str`	Режим указания стороны X инициатора создаваемого вызова. Возможные варианты: `"number"` – Звонок на номер (поле `from` содержит номер). Используется по умолчанию. `"sipuser"` – Звонок на пользователя (поле `from` содержит логин).
`from`	`str`	В зависимости от режима (`mode`) - номер вызывающего абонента X, либо логин учетной записи SIP-пользователя.
`to`	`str`	Номер вызываемого абонента Y. Позволяет задавать символы `'` и `,`. Первый такой символ выделяет оставшуюся последовательность в качестве донабора DTMF после получения ответа, а каждый последующий такой символ обеспечивают паузу в 1 секунду в наборе DTMF.
`callerid`	`str`	Номер инициатора первого вызова. Отображается абоненту X. По умолчанию используется значение поля `from` (вызов от себя самого).
`callername`	`str`	Имя инициатора первого вызова. По умолчанию `"callmanager"`.
`calltimeout`	`int`	Таймаут первого вызова в сеундах. Является ограничением стандартного время вызова. По умолчанию 30 сек.
`binding`	`str`	Метка, привязываемая к звонку. По умолчанию не назначается.
`response_mode`	`int`	Режим возврата ответа. Чем больше значение, тем позже отправляется ответ, и тем больше контекстной информации в ответе содержится. Возможные варианты: `0` – отправлять ответ сразу после инициации вызова IVR→X. Отправляется почти моментально без ожидания ответов от абонентов X и Y. В ответе содержится только CallId инициирующего вызова IVR→X. `1` – отправлять ответ после получения предварительного ответа от X (`100-199`, IVR→X). `2` – отправлять ответ после получения окончательного ответа от X (`200-699`, IVR→X). `3` – отправлять ответ после получения предварительного ответа от Y (`101-199`, X→Y). Ответ `100` исключается, поскольку его отправляет не абонент, а сервер. Начиная с этого режима в контексте звонка содержится информация о целевом диалоге. `4` – отправлять ответ после получения окончательного ответа от Y (`200-699`, X→Y). Начиная с этого режима в ответе содержится достоверная информация об успешности соединения X→Y. `5` - отправлять ответ после полного завершения операции и всех ее процессов (исключая сам диалог X→Y, который может продолжаться несколько часов). По умолчанию `3`.

Пример запроса

POST /rest/v1/uc/calls 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
}

Ответ

Table 5. Описание полей
Поле	Описание
`result`	Итоговый результат по операции. Варианты значений.
`ivrcallid`	Call-Id инициирующего автоматического звонка IVR→X (отличается от CallId плечей целевого диалога). Присутствует в любом случае.
`acallid`	Call-Id звонка, поступившего в систему от абонента X к абоненту Y после обработки SIP-запроса REFER. Это Call-Id плеча `A` целевого диалога X→Y. При некоторых неудачных результатах операции может отсутствовать.
`last_response`	Response-Line последнего полученного ответа от абонента Y, по результатам которого сформирован ответ на запрос. При некоторых неудачных результатах операции может отсутствовать.
`dialogid`	Идентификатор целевого диалога X→Y. При некоторых неудачных результатах операции может отсутствовать. Также может отсутствовать если длительность диалога 0 секунд.

Table 6. Варианты значений поля result
Значение	Описание
`"ok"`	Ответ сформирован на этапе, где не выявлено проблем для успешного создания диалога X→Y. Например, для `response_mode=0` – сценарий IVR успешно инициализирован для вызова IVR→X. `response_mode=1` – получен предварительный ответ от абонента X (IVR→X). `response_mode=2` – получен окончательный ответ `2xx` от абонента X (IVR→X). `response_mode=3` – получен окончательный ответ `2xx` от абонента X (IVR→X) и инициализирован вызов X→Y, получен предварительный ответ `18x` или окончательный ответ `2xx` от абонента Y. `response_mode=4` – получен окончательный ответ `2xx` от абонента X (IVR→X) и инициализирован вызов X→Y, получен окончательный ответ `2xx` от абонента Y. `response_mode=5` – диалог X→Y установлен, после некоторого небольшого таймаута инициализирующие процессы завершены.
`"rejected"`	Вызов IVR→X завершился неудачей (`4xx-6xx`), либо вызов X→Y завершился неудачей (`4xx-6xx`). Отправить неудачный ответ мог как сервер, так и абонентское устройство. В случае, если неудачный ответ получен от абонента X, результат не содержит информации о диалоге X→Y, поля `acallid`, `dialogid`, `last_response` отсутствуют. В случае, если неудачный ответ получен от абонента Y, результат содержит поля `acallid` и `last_response` о диалоге X→Y и не содержит `dialogid`.
`"redirected"`	Вызов IVR→X завершился переадресацией SIP-UA (`3xx`), либо вызов X→Y завершился переадресацией SIP-UA (`3xx`). Значение является гипотетическим, поскольку обработкой `3xx`-переадресаций занимается сам сервер (роль b2b), автоматически инициируя альтернативные форки.
`"timeout"`	Вызов IVR→X после предварительного ответа завершился таймаутом. Значение является гипотетическим, поскольку при отсутствии финального ответа сервер (роль b2b), завершает вызов автоматической эмуляцией ответа `408 Timeout`.
`"error"`	Не получен ответ от абонента X, либо другая неожиданная ситуация. В ответе могут отсутствовать поля `acallid`, `dialogid`, `last_response`.
`"undefined"`	Абонент 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"
}

Инициация нового звонка (INVITE)

Метод синонимичен POST.

Инициация нового звонка с обслуживанием в IVR (INVITEBYIVR)

Инициирует вызов абонента Y и запускает указанный сценарий для его обслуживания.

Поддерживается донабор DTMF символов после ответа абонента с управляемыми паузами.

Операция проводится через запуск скрытого служебного сценария, осуществляющего подготовленный дозвон до инициатора (компонент сценария Исходящий звонок) с передачей управления специально подготовленному скрытому IVR-сценарию с компонентами Генерация DTMF и Запуск вложенного сценария.

Схема процесса: IVR→X.

События CDR целевого звонка могут быть получены из интерфейса подписки на события системы.

Запрос

Table 7. Параметры запроса
Имя	Тип	Описание
`to`	`str`	Номер вызываемого абонента Y. Позволяет задавать символы `'` и `,`. Первый такой символ выделяет оставшуюся последовательность в качестве донабора DTMF после получения ответа, а каждый последующий такой символ обеспечивают паузу в 1 секунду в наборе DTMF.
`callerid`	`str`	Номер инициатора первого вызова. Отображается абоненту X. По умолчанию используется значение поля `from` (вызов от себя самого).
`callername`	`str`	Имя инициатора первого вызова. По умолчанию `"callmanager"`.
`calltimeout`	`int`	Таймаут первого вызова в сеундах. Является ограничением стандартного время вызова. По умолчанию 30 сек.
`use_intercom`	`bool`	Выключатель режима intercom для вызова абонента. По умолчанию выключено.
`binding`	`str`	Метка, привязываемая к звонку. По умолчанию не назначается. Наследуется всеми дальнейшими переведенными вызовами.
`headers`	`str`	Список дополнительных заголовков для INVITE-запроса в строковом виде, разделенных переносом строки (CLCR).
`response_mode`	`int`	Режим возврата ответа. Чем больше значение, тем позже отправляется ответ, и тем больше контекстной информации в ответе содержится. Возможные варианты: `0` – отправлять ответ сразу после инициации вызова IVR→X. Отправляется почти моментально без ожидания ответов от абонентов X и Y. В ответе содержится только CallId инициирующего вызова IVR→X. `1` – отправлять ответ после получения предварительного ответа от X (`100-199`, IVR→X). `2` – отправлять ответ после получения окончательного ответа от X (`200-699`, IVR→X). По умолчанию `2`.
`dtmf_proto`	`str`	Протокол отправки DTMF символов донабора. Отправке после ответа абонента подлежат все символы, переданные в номере после запятой. Причем каждая запятая - это пауза в одну секунду. Возможные варианты: `rfc2833` `sipinfo`
`scriptcode`	`str`	Код сценария IVR, которому надлежит обслуживать абонента.
`key`	`str`	Строка, которая будет отправлена в качестве первого параметра в сценарий, а при соответствии ее значения JSON объекту, задаст начальные значения переменным, чьи имена являются ключами объекта.

Пример запроса

INVITEBYIVR /rest/v1/uc/calls HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "to": "22",
  "scriptcode": "test_play",

  "response_mode": 2,
  "callerid": "100",
  "callername": "callmanager",
  "calltimeout": 30,
  "use_intercom": false,
  "binding": "sample_label",
  "headers": "X-Header-Sample-1: 123\r\nX-Header-Sample-2: a; b; c"
}

Ответ

Table 8. Описание полей
Поле	Описание
`result`	Итоговый результат по операции. Варианты значений.
`ivrcallid`	Call-Id инициирующего автоматического звонка IVR→X (отличается от CallId плечей целевого диалога). Присутствует в любом случае.
`sipcode`	Код последнего полученного ответа от абонента X, по результатам которого сформирован ответ на запрос. При некоторых неудачных результатах операции может отсутствовать.
`dialogid`	Идентификатор целевого диалога IVR→X. При некоторых неудачных результатах операции может отсутствовать. Также может отсутствовать если длительность диалога 0 секунд.

Table 9. Варианты значений поля result
Значение	Описание
`"ok"`	Ответ сформирован на этапе, где не выявлено проблем для успешного создания диалога X→Y. Например, для `response_mode=0` – сценарий IVR успешно инициализирован для вызова IVR→X. `response_mode=1` – получен предварительный ответ от абонента X (IVR→X). `response_mode=2` – получен окончательный ответ `2xx` от абонента X (IVR→X). `response_mode=3` – получен окончательный ответ `2xx` от абонента X (IVR→X) и инициализирован вызов X→Y, получен предварительный ответ `18x` или окончательный ответ `2xx` от абонента Y. `response_mode=4` – получен окончательный ответ `2xx` от абонента X (IVR→X) и инициализирован вызов X→Y, получен окончательный ответ `2xx` от абонента Y. `response_mode=5` – диалог X→Y установлен, после некоторого небольшого таймаута инициализирующие процессы завершены.
`"rejected"`	Вызов IVR→X завершился неудачей (`4xx-6xx`), либо вызов X→Y завершился неудачей (`4xx-6xx`). Отправить неудачный ответ мог как сервер, так и абонентское устройство. В случае, если неудачный ответ получен от абонента X, результат не содержит информации о диалоге X→Y, поля `acallid`, `dialogid`, `last_response` отсутствуют. В случае, если неудачный ответ получен от абонента Y, результат содержит поля `acallid` и `last_response` о диалоге X→Y и не содержит `dialogid`.
`"redirected"`	Вызов IVR→X завершился переадресацией SIP-UA (`3xx`), либо вызов X→Y завершился переадресацией SIP-UA (`3xx`). Значение является гипотетическим, поскольку обработкой `3xx`-переадресаций занимается сам сервер (роль b2b), автоматически инициируя альтернативные форки.
`"timeout"`	Вызов IVR→X после предварительного ответа завершился таймаутом. Значение является гипотетическим, поскольку при отсутствии финального ответа сервер (роль b2b), завершает вызов автоматической эмуляцией ответа `408 Timeout`.
`"error"`	Не получен ответ от абонента X, либо другая неожиданная ситуация. В ответе могут отсутствовать поля `acallid`, `dialogid`, `last_response`.
`"undefined"`	Абонент 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-пользователя, если он участвует в нескольких диалогах.

Запрос

Table 10. Параметры запроса
Параметр	Тип	Описание
`dialogid`	`str`	Значение для поиска. Идентификатор диалога, применяемый при формировании endpoint. Уникален в рантайме, однако не является глобально уникальным и может повторяться через некоторое время в рамках одной и той же системы. Например, `"rDlg-002-6FpTv2"`.
`inviteid`	`str`	Значение для поиска. Глобально уникальный идентификатор вызова, приводящего к диалогу. Формируется при поступлении в систему SIP-запроса INVITE и существует вплоть до завершения диалога. Присутствует во всех событиях CDR класса callevents. Например `"660df330-0623-b465-6927-c00000000002"`.
`callid`	`str`	Значение для поиска. Идентификатор звонка `Call-Id`. Произвольное строковое значение из соответствующего заголовка SIP-сообщений любой из сторон диалога. Например, `"3099649154@192.168.0.149"`.
`uri`	`str`	Значение для поиска. SIP URI: `"<sip:username@domain>"`. Значение формируется на основании заголовков `From` или `To`. Поиск осуществляется только по Remote-URI плечей диалога.
`from`	`str`	Значение для поиска. Номер телефона или логин SIP-пользователя, используемые в качестве `username`. Может использовать дополнительный параметр `mode`: `"number"` – поиск по номеру телефона. То есть прямой поиск по значению в `username`, а также если по указанному номеру обнаружен sipuser, то поиск по его логину в `username`. `"sipuser"` – поиск только по имени SIP-пользователя. Необходимо обязательное существование SIP-пользователя с указанным логином, в этом случае поиск по его логину в `username`. По умолчанию `mode=number`. Обнаруживаются диалоги, где одной из сторон выступает указанный абонент текущего домена. Поиск производится аналогично `uri`, при этом username формируется автоматически. Для учетной записи SIP-пользователя, как бы ни была она указана, поиск производится и для номера, и для логина.
`sipuserid`	`str`	Значение для поиска. Идентификатор учетной записи SIP-пользователя.
`sipuserlogin`	`str`	Значение для поиска. Логин учетной записи SIP-пользователя.
`sipuserphonenumber`	`str`	Значение для поиска. Номер телефона учетной записи SIP-пользователя.
`userid`	`str`	Значение для поиска. Идентификатор учетной записи пользователя системы. Если имеет место привязка учетных записей SIP-пользователей к пользователю системы, то обнаруживаются диалоги, где один из этих SIP-пользователей является одним из абонентов.

Пример запроса

LOOKUP /rest/v1/uc/calls HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "callid": "rB2-002-XPhrjh-01-3587482024@192.168.0.146"
}

Ответ

Пример успешного ответа

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8

[
  "rDlg-002-XPhrjh"
]

Пример неуспешного ответа

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "error_code": 1413,
  "error_message": "Dialog not found"
}

Получение информации о звонке (GET)

Возвращает информацию о диалоге.

Запрос

Table 11. Параметры запроса
Имя	Тип	Описание
`dialogid`	`str`	Идентификатор диалога, подлежащего переводу (master). Передается как часть Endpoint URI. В качестве параметра используется при отправке команды из сценария компонентом Операция. При отправке команды из сценария существуют и другие способы указания диалога, альтернативные этому. Все способы указания диалога перечислены ниже в порядке убывания приоритета с кратким описанием. Подробно о них см. в параметрах операции поиска звонка. * `dialogid` – по идентификатору диалога. * `inviteid` – по идентификатору вызова, приводящего к диалогу. * `callid` – по идентификатору `Call-Id` одного из плечей диалога. * `uri` – по URI одного из участников диалога: `"<sip:username@domain>"`. * `from` – по номеру телефона или логину SIP-пользователя. Используется дополнительный параметр `mode`: `"number"` или `"sipuser"`. * `sipuserid` – по идентификатору учетной записи SIP-пользователя. * `sipuserlogin` – по логину учетной записи SIP-пользователя. * `sipuserphonenumber` – по номеру телефона учетной записи SIP-пользователя. * `userid` – по идентификатор учетной записи пользователя системы.
`mask`	`str`	Список полей для вывода.
`flat`	`bool`	Преобразование в плоский вид составных полей.

Пример запроса

GET /rest/v1/uc/calls/rDlg-002-484FD3 HTTP/1.1

Ответ

Возвращает объект с представлением диалога.

Table 12. Поля диалога:
Поле	Описание
`acallid`	Call-Id инициирующей стороны диалога. Содержится в соответствующем заголовке инициирующего SIP-запроса INVITE.
`callids`	Список всех Call-Id активных участников диалога. Каждая сторона диалога имеет свой Call-Id, каждый вызываемый форк имеет уникальный Call-Id.
`dialogid`	Идентификатор активного диалога, применяемый при формировании endpoint. Уникален в рантайме, однако не является глобально уникальным и может повторяться через некоторое время в рамках одной и той же системы.
`esgdlgid`	Идентификатор диалога роли esg. Имеет непустое значение только в том случае, если диалог создан на основании внешнего входящего звонка с учетной записи провайдера. Может использоваться в качестве идентификатора сессии обслуживания внешнего абонента, поскольку в ходе перевода звонка диалог esg не изменяется.
`esgcallid`	CallId внешнего абонента, скрытый за ролью esg. Имеет непустое значение только в том случае, если диалог создан на основании внешнего входящего звонка с учетной записи провайдера.
`inviteid`	Глобально уникальный идентификатор вызова, приводящего к диалогу. Формируется при поступлении в систему SIP-запроса INVITE и существует вплоть до завершения диалога. Присутствует во всех событиях CDR класса callevents.
`status`	Генеральное состояние диалога. Варианты значений: `"forking"` – состояние вызова. От инициации до окончательного ответа `2xx` от вызываемой стороны. `"dialog"` – состояние диалога. После окончательного ответа `2xx` от вызываемой стороны до окончания диалога. На деле машина состояний диалога имеет гораздо больше состояний, но все они укладываются в генеральные состояния.
`legs`	Список плечей диалога. Каждый диалог всегда имеет ровно одного инициатора (вызывающая сторона `A`) и произвольное количество вызываемых плечей (сторона `B`) в связи с форкингом. В генеральном состоянии `status=forking`: диалог может содержать более одного вызываемого плеча `B`; вызываемые плечи могут добавляться и удаляться в зависимости от процесса маршрутизации вызова и его реализации для конкретного диалога. В генеральном состоянии `status=dialog` плечо стороны `B`: присутствует в единственном экземпляре; представляет собой ответившего абонента; не изменяется вплоть до завершения диалога. Каждый элемент списка является объектом.
`localuri`	Строковое представление URI из заголовка `To` инициирующего SIP-запроса INVITE (local URI стороны `A`). Формат: `"<sip:USERNAME@DOMAIN>"`, где `USERNAME` и `DOMAIN` строго соответствуют значениям в заголовке.
`remoteuri`	Строковое представление URI из заголовка `From` инициирующего SIP-запроса INVITE (remote URI стороны `A`). Формат: `"<sip:USERNAME@DOMAIN>"`, где `USERNAME` и `DOMAIN` строго соответствуют значениям в заголовке.
`site`	Название сайта, серверы которого обслуживают диалог.
`startts`	Тайм-штамп времени поступления инициирующего SIP-запроса INVITE в систему. Является представлением момента времени и может быть преобразован к конкретной дате в любом часовом поясе. Например, `1571743463336`.
`uris`	Список всех URI, участвующих в звонке. Каждый SIP-пользователь, являющийся абонентом диалога, имеет два URI, один из которых указан через `login`, другой через `phonenumber`.
`opts`	Объект с дополнительными параметрами диалога. Содержит: `referred-by` – значение заголовка Referred-By из инициирующего SIP-запроса INVITE. `replaces` – значение заголовка Replaces из инициирующего SIP-запроса INVITE.

Table 13. Поля плечей диалога в значении поля legs:
Поле	Описание
`callid`	Call-Id плеча. Содержится в соответствующем заголовке SIP-запроса INVITE (полученного или отправленного).
`expirets`	Ограничение времени вызова абонента в миллисекундах. Имеет значение только для плеча стороны `B`.
`localuri`	Строковое представление local URI. Для плеча стороны `А` – из заголовка `To` инициирующего SIP-запроса INVITE, для плеча стороны `B` – из заголовка `From` отправляемого SIP-запроса INVITE. Формат: `"<sip:USERNAME@DOMAIN>"`, где `USERNAME` и `DOMAIN` строго соответствуют значениям в заголовке.
`remoteuri`	Строковое представление remote URI. Для плеча стороны `А` – из заголовка `From` инициирующего SIP-запроса INVITE, для плеча стороны `B` – из заголовка `To` отправляемого SIP-запроса INVITE. Формат: `"<sip:USERNAME@DOMAIN>"`, где `USERNAME` и `DOMAIN` строго соответствуют значениям в заголовке.
`side`	Код стороны диалога: `"a"` – вызывающая сторона; `"b"` – вызываемая сторона.

Пример ответа

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>"
  ]
}

Перевод звонка на номер (REFER)

Производит перевод звонка – абонента диалога (оппонента) – на указанный номер. Действует для любого активного диалога в текущем домене. Существуют стандартные ограничения при переводе диалога, находящегося в состоянии status=forking.

Схема процесса: X-Y | IVR→Y, IVR REFER Z, Y→Z.

Операция проводится через запуск скрытого служебного сценария, осуществляющего подготовленный дозвон до указанного абонента с подменой конкретного указанного диалога (компонент сценариев Дозвон с установленными заголовками Replaces и Referred-By), и последующую передачу управления специально подготовленному скрытому IVR сценарию с компонентом Перевод на номер. В качестве номера для перевода подставляется указанный номер referto. В случае неудачи при переводе следующий компонент сценария переводит вызов обратно на номер инициатора перевода.

Запрос

Table 14. Параметры запроса
Имя	Тип	Описание
`dialogid`	`str`	Идентификатор диалога, подлежащего переводу. Передается как часть Endpoint URI. В качестве параметра используется при отправке команды из сценария компонентом Операция. При отправке команды из сценария существуют и другие способы указания диалога, альтернативные этому. Все способы указания диалога перечислены ниже в порядке убывания приоритета с кратким описанием. Подробно о них см. в параметрах операции поиска звонка. `dialogid` – по идентификатору диалога. `inviteid` – по идентификатору вызова, приводящего к диалогу. `callid` – по идентификатору `Call-Id` одного из плечей диалога. `uri` – по URI одного из участников диалога: `"<sip:username@domain>"`. `from` – по номеру телефона или логину SIP-пользователя. Используется дополнительный параметр `mode`: `"number"` или `"sipuser"`. `sipuserid` – по идентификатору учетной записи SIP-пользователя. `sipuserlogin` – по логину учетной записи SIP-пользователя. `sipuserphonenumber` – по номеру телефона учетной записи SIP-пользователя. `userid` – по идентификатор учетной записи пользователя системы.
`by`	`str`	Сторона диалога инициирующая перевод звонка. `SIP URI` или `Call-Id`. На основании значения вычисляется оппозитная сторона, которую следует перевести. Именно ей отправляется SIP-запрос INVITE с Replaces из IVR и последующий SIP-запрос REFER.
`referto`	`str`	Номер, на который осуществляется перевод абонента. Позволяет задавать символы `'` и `,`. Первый такой символ выделяет оставшуюся последовательность в качестве донабора DTMF после получения ответа, а каждый последующий такой символ обеспечивают паузу в 1 секунду в наборе DTMF.
`response_mode`	`int`	Режим возврата ответа. Чем больше значение, тем позже отправляется ответ, и тем больше контекстной информации в ответе содержится. Возможные варианты: `0` – отправлять ответ сразу после инициации вызова IVR→Y. Отправляется почти моментально без ожидания ответов от абонентов Y и Z. В ответе содержится только CallId инициирующего вызова IVR→Y. `1` – отправлять ответ после получения предварительного ответа от Y (`100-199`, IVR→Y). `2` – отправлять ответ после получения окончательного ответа от Y (`200-699`, IVR→Y). `3` – отправлять ответ после получения предварительного ответа от Z (`101-199`, Y→Z). Ответ `100` исключается, поскольку его отправляет не абонент, а сервер. Начиная с этого режима в контексте звонка содержится информация о целевом диалоге. `4` – отправлять ответ после получения окончательного ответа от Z (`200-699`, Y→Z). Начиная с этого режима в ответе содержится достоверная информация об успешности соединения Y→Z. `5` - отправлять ответ после полного завершения операции и всех ее процессов (исключая сам диалог Y→Z, который может продолжаться несколько часов). По умолчанию `3`.
`binding`	`str`	Метка, привязываемая к подменяющему звонку и следом к переводному звонку. По умолчанию не назначается.

Пример запроса

REFER /rest/v1/uc/calls/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "referto": "13",
  "by": "<sip:11@test.rootdomain.ru>",
  "response_mode": 3
}

Ответ

Table 15. Описание полей
Поле	Описание
`dialogid`	Идентификатор диалога, подлежащего переводу. Совпадает с идентификатором в endpoint или переходит без изменений из параметров запроса.
`result`	Итоговый результат по операции. Варианты значений.
`ivrcallid`	Call-Id инициирующего автоматического звонка IVR→Y (отличается от CallId плечей целевого диалога). Присутствует в любом случае.
`new_acallid`	Call-Id звонка, поступившего в систему от абонента Y к абоненту Z после обработки SIP-запроса REFER. Это Call-Id плеча `A` целевого диалога Y→Z. При некоторых неудачных результатах операции может отсутствовать.
`new_last_response`	Response-Line последнего полученного ответа от абонента Z, по результатам которого сформирован ответ на запрос. При некоторых неудачных результатах операции может отсутствовать.
`new_dialogid`	Идентификатор целевого диалога Y→Z. При некоторых неудачных результатах операции может отсутствовать. Также может отсутствовать если длительность диалога 0 секунд.

Table 16. Варианты значений поля result
Значение	Описание
`"ok"`	Ответ сформирован на этапе, где не выявлено проблем для успешного создания диалога Y→Z. Например, для `response_mode=0` – сценарий IVR успешно инициализирован для вызова IVR→Y. `response_mode=1` – получен предварительный ответ от абонента Y (IVR→Y). `response_mode=2` – получен окончательный ответ `2xx` от абонента Y (IVR→Y). `response_mode=3` – получен окончательный ответ `2xx` от абонента Y (IVR→Y) и инициализирован вызов Y→Z, получен предварительный ответ `18x` или окончательный ответ `2xx` от абонента Z. `response_mode=4` – получен окончательный ответ `2xx` от абонента Y (IVR→Y) и инициализирован вызов Y→Z, получен окончательный ответ `2xx` от абонента Z. `response_mode=5` – диалог Y→Z установлен, после некоторого небольшого таймаута инициализирующие процессы завершены.
`"rejected"`	Вызов IVR→Y завершился неудачей (`4xx-6xx`), либо вызов Y→Z завершился неудачей (`4xx-6xx`). Отправить неудачный ответ мог как сервер, так и абонентское устройство. В случае, если неудачный ответ получен от абонента Y, результат не содержит информации о диалоге Y→Z, поля `acallid`, `dialogid`, `last_response` отсутствуют. В случае, если неудачный ответ получен от абонента Z, результат содержит поля `acallid` и `last_response` о диалоге Y→Z и не содержит `dialogid`.
`"redirected"`	Вызов IVR→Y завершился переадресацией SIP-UA (`3xx`), либо вызов Y→Z завершился переадресацией SIP-UA (`3xx`). Значение является гипотетическим, поскольку обработкой `3xx`-переадресаций занимается сам сервер (роль b2b), автоматически инициируя альтернативные форки.
`"timeout"`	Вызов IVR→Y после предварительного ответа завершился таймаутом. Значение является гипотетическим, поскольку при отсутствии финального ответа сервер (роль b2b), завершает вызов автоматической эмуляцией ответа `408 Timeout`.
`"error"`	Не получен ответ от абонента Y, либо другая неожиданная ситуация. В ответе могут отсутствовать поля `acallid`, `dialogid`, `last_response`.
`"undefined"`	Абонент Y удачно ответил на вызов IVR→Y, состояние вызова Y→Z неизвестно из-за отсутствия или неизвестного содержания SIP-запросов NOTIFY в диалоге, обслужившим REFER.

Пример ответа

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "dialogid": "rDlg-002-WOabz0",
  "result": "ok",
  "ivrcallid": "rIV-006-5avZy6B3IC5nivAvVS5B6n4prqT",
  "new_acallid": "1920460747@192.168.0.149",
  "new_dialogid": "rDlg-002-JKNked",
  "new_last_response": "SIP/2.0 180 Ringing"
}

Перевод звонка с подменой (REFERREPLACES)

Производит соединение абонентов двух различных активных диалогов текущего домена.

Абонент одного диалога связывается с абонентом другого диалога, а оппоненты отбиваются в соответствии с протоколом SIP (в частности, SIP-UA, получивший INVITE с Replaces, производит отправку BYE в сторону оппонента в подменяемом диалоге).

Cхема процесса в общем виде: X-Y, P-Q | IVR→Y, IVR REFER+REPLACES Q, Y→Q.

Стандартный кейс: абонент соединяет двух своих оппонентов в разных активных диалогах, а сам освобождается. Тогда схема процесса: X-Y, X-Z | IVR→Y, IVR REFER+REPLACES Z, Y→Z. Но это не обязательно, могут быть выбраны совершенно произвольные диалоги по всему кластеру.

Поскольку участвуют два звонка, то название каждого из параметров содержит префикс: "master" или "slave".

Операция проводится через запуск скрытого служебного сценария, осуществляющего подготовленный дозвон до абонента одного диалога с подменой (компонент сценария "Дозвон" с установленными заголовками Replaces и Referred-By), последующей передачей управления специально подготовленному скрытому IVR сценарию с компонентом "Перевод с подменой". В качестве цели для перевода подставляется идентификатор второго указанного диалога (slave).

Запрос

Table 17. Параметры перевода звонка по `dialogid`.
Имя	Тип	Описание
`masterdialogid`	`str`	Идентификатор диалога, подлежащего переводу (master). Передается как часть Endpoint URI. В качестве параметра используется при отправке команды из сценария компонентом Операция. При отправке команды из сценария существуют и другие способы указания master-диалога, альтернативные этому. Все способы указания диалога перечислены ниже в порядке убывания приоритета с кратким описанием. Подробно о них см. в параметрах операции поиска звонка с добавлением префикса `"master"`. `masterdialogid` – по идентификатору диалога. `masterinviteid` – по идентификатору вызова, приводящего к диалогу. `mastercallid` – по идентификатору `Call-Id` одного из плечей диалога. `masteruri` – по URI одного из участников диалога: `"<sip:username@domain>"`. `masterfrom` – по номеру телефона или логинуSIP-пользователя. Используется дополнительный параметр `mode`: `"number"` или `"sipuser"`. `mastersipuserid` – по идентификатору учетной записи SIP-пользователя. `mastersipuserlogin` – по логину учетной записи SIP-пользователя. `mastersipuserphonenumber` – по номеру телефона учетной записи SIP-пользователя. `masteruserid` – по идентификатор учетной записи пользователя системы.
`masterby`	`str`	Сторона master-диалога инициирующая перевод звонка. `SIP URI` или `Call-Id`. На основании значения вычисляется оппозитная сторона, которую следует перевести. Именно ей отправляется SIP-запрос INVITE с Replaces из IVR и последующий SIP-запрос REFER.
`slavedialogid`	`str`	Идентификатор диалога, подлежащего подмене (slave). Существуют и другие способы указания slave-диалога, альтернативные этому. Все способы указания диалога перечислены ниже в порядке убывания приоритета с кратким описанием. Подробно о них см. в параметрах операции поиска звонка с добавлением префикса `"slave"`. `slavedialogid` – по идентификатору диалога. `slaveinviteid` – по идентификатору вызова, приводящего к диалогу. `slavecallid` – по идентификатору `Call-Id` одного из плечей диалога. `slaveuri` – по URI одного из участников диалога: `"<sip:username@domain>"`. `slavefrom` – по номеру телефона или логину SIP-пользователя. Используется дополнительный параметр `mode`: `"number"` или `"sipuser"`. `slavesipuserid` – по идентификатору учетной записи SIP-пользователя. `slavesipuserlogin` – по логину учетной записи SIP-пользователя. `slavesipuserphonenumber` – по номеру телефона учетной записи SIP-пользователя. `slaveuserid` – по идентификатор учетной записи пользователя системы.
`slaveby`	`str`	Сторона slave-диалога, подлежащая подмене. `SIP URI` или `Call-Id`. На основании значения вычисляется оппозитная сторона, у которой следует подменить плечо. Именно на нее нацеливается REFER с Replaces и как следствие ей отправляется SIP-запрос INVITE с Replaces от Y.
`response_mode`	`int`	Режим возврата ответа. Чем больше значение, тем позже отправляется ответ, и тем больше контекстной информации в ответе содержится. Возможные варианты: `0` – отправлять ответ сразу после инициации вызова IVR→Y. Отправляется почти моментально без ожидания ответов от абонентов Y и Q. В ответе содержится только CallId инициирующего вызова IVR→Y. `1` – отправлять ответ после получения предварительного ответа от Y (`100-199`, IVR→Y). `2` – отправлять ответ после получения окончательного ответа от Y (`200-699`, IVR→Y). `3` – отправлять ответ после получения предварительного ответа от Q (`101-199`, Y→Q). Ответ `100` исключается, поскольку его отправляет не абонент, а сервер. Начиная с этого режима в контексте звонка содержится информация о целевом диалоге. `4` – отправлять ответ после получения окончательного ответа от Q (`200-699`, Y→Q). Начиная с этого режима в ответе содержится достоверная информация об успешности соединения Y→Q. `5` - отправлять ответ после полного завершения операции и всех ее процессов (исключая сам диалог Y→Q, который может продолжаться несколько часов). По умолчанию `4`.
`binding`	`str`	Метка, привязываемая к подменяющему звонку и следом к переводному подменяющему звонку. По умолчанию не назначается.

Пример запроса

REFERREPLACES /rest/v1/uc/calls/rDlg-002-HKO7cn HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "masterby": "1771996496@192.168.0.147",
  "slavedialogid": "rDlg-002-YWR7ts",
  "slaveby": "2622745275@192.168.0.149",
  "response_mode": 4
}

Ответ

Table 18. Описание полей
Поле	Описание
`masterdialogid`	Идентификатор диалога, подлежащего переводу (master). Совпадает с идентификатором в endpoint или переходит без изменений из параметров запроса.
`slavedialogid`	Идентификатор диалога, подлежащего подмене (slave). Переходит без изменений из параметров запроса.
`result`	Итоговый результат по операции. Варианты значений.
`ivrcallid`	Call-Id инициирующего автоматического звонка IVR→Y (отличается от CallId плечей целевого диалога). Присутствует в любом случае.
`new_acallid`	Call-Id звонка, поступившего в систему от абонента Y к абоненту Z после обработки SIP-запроса REFER. Это Call-Id плеча `A` целевого диалога Y→Z. При некоторых неудачных результатах операции может отсутствовать.
`new_last_response`	Response-Line последнего полученного ответа от абонента Z, по результатам которого сформирован ответ на запрос. При некоторых неудачных результатах операции может отсутствовать.
`new_dialogid`	Идентификатор целевого диалога Y→Z. При некоторых неудачных результатах операции может отсутствовать. Также может отсутствовать если длительность диалога 0 секунд.

Table 19. Варианты значений поля result
Значение	Описание
`"ok"`	Ответ сформирован на этапе, где не выявлено проблем для успешного создания диалога Y→Z. Например, для `response_mode=0` – сценарий IVR успешно инициализирован для вызова IVR→Y. `response_mode=1` – получен предварительный ответ от абонента Y (IVR→Y). `response_mode=2` – получен окончательный ответ `2xx` от абонента Y (IVR→Y). `response_mode=3` – получен окончательный ответ `2xx` от абонента Y (IVR→Y) и инициализирован вызов Y→Q, получен предварительный ответ `18x` или окончательный ответ `2xx` от абонента Q. `response_mode=4` – получен окончательный ответ `2xx` от абонента Y (IVR→Y) и инициализирован вызов Y→Q, получен окончательный ответ `2xx` от абонента Q. `response_mode=5` – диалог Y→Q установлен, после некоторого небольшого таймаута инициализирующие процессы завершены.
`"rejected"`	Вызов IVR→Y завершился неудачей (`4xx-6xx`), либо вызов Y→Z завершился неудачей (`4xx-6xx`). Отправить неудачный ответ мог как сервер, так и абонентское устройство. В случае, если неудачный ответ получен от абонента Y, результат не содержит информации о диалоге Y→Q, поля `acallid`, `dialogid`, `last_response` отсутствуют. В случае, если неудачный ответ получен от абонента Q, результат содержит поля `acallid` и `last_response` о диалоге Y→Q и не содержит `dialogid`.
`"redirected"`	Вызов IVR→Y завершился переадресацией SIP-UA (`3xx`), либо вызов Y→Q завершился переадресацией SIP-UA (`3xx`). Значение является гипотетическим, поскольку обработкой `3xx`-переадресаций занимается сам сервер (роль b2b), автоматически инициируя альтернативные форки.
`"timeout"`	Вызов IVR→Y после предварительного ответа завершился таймаутом. Значение является гипотетическим, поскольку при отсутствии финального ответа сервер (роль b2b), завершает вызов автоматической эмуляцией ответа `408 Timeout`.
`"error"`	Не получен ответ от абонента Y, либо другая неожиданная ситуация. В ответе могут отсутствовать поля `acallid`, `dialogid`, `last_response`.
`"undefined"`	Абонент Y удачно ответил на вызов IVR→Y, состояние вызова Y→Q неизвестно из-за отсутствия или неизвестного содержания SIP-запросов NOTIFY в диалоге, обслужившим REFER.

Пример ответа

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "masterdialogid": "rDlg-002-HKO7cn",
  "slavedialogid": "rDlg-002-YWR7ts",
  "result": "ok",
  "ivrcallid": "rIV-006-OCXV3CJPkbUUlFx6v8O00kjTm22",
  "new_acallid": "3762659316@192.168.0.146",
  "new_dialogid": "rDlg-002-RqNtEp",
  "new_last_response": "SIP/2.0 200 OK"
}

Преобразование звонка в конференцию (SWITCHCONF)

Производит мягкое переключение обоих абонентов указанного диалога в конференц-комнату. Оба абонентских устройства получают SIP-запросы INVITE с Replaces, соединяются с IVR, которые их переводят на конференц-комнату с помощью SIP-запросов REFER. Абоненты могут находиться в разных доменах. Конференция будет создана в домене, в котором производится API-запрос преобразования (или исполняется сценарий, производящий операцию).

Операция проводится через запуск скрытых служебных сценариев – по одному для каждого из абонентов, осуществляющих подготовленный дозвон до соответствующего абонента диалога с подменой (компонент сценария Исходящий звонок с установленными заголовками Replaces и Referred-By), с последующей передачей управления специально подготовленному скрытому IVR-сценарию с компонентом Перевод на номер. В качестве цели для перевода подставляется номер конференц-комнаты вместе с КАФ (featurecode типа conf). Номер для перевода может быть указан в параметре запроса referto, в противном случае вычисляется автоматически – маршрутизация должна быть настроена.

Схема процесса: X-Y | IVR1→X, IVR2→Y, IVR1 REFER CONF, IVR2 REFER CONF, X→CONF, Y→CONF.

Параметр запроса by указывает произвольный username или номер в текущем домене, от имени которого производится перевод обоих абонентов диалога в конференцию. Фактически необходимо использовать, если маршрутизация особенная, и не для всех открыт доступ к featurecode конференции.

Чтобы при получении одним абонентом INVITE с Replaces другой абонент не отвалился по BYE (получившая сторона отправляет BYE оппоненту подмененного диалога согласно протоколу SIP, а роль b2b пробрасывает его сквозь себя), роль b2b получает команду на временную паузу диалога (фактически, блокировка переотправки BYE – вместо этого при получении BYE запускается отложенная асинхронная операция отправки BYE на 3 секунды). После получения SIP-ответов 2xx от обоих абонентов на INVITE с Replaces, диалог выводится из паузы. В нормальной ситуации он к этому времени уже не существует.

В случае неудачи исходный разговор не восстанавливается. Теоретически возможна ситуация, когда одному абоненту удастся дозвониться до конференц-комнаты, а второму нет. В этом случае один получит отбой, а второй окажется в конференции наедине с собой.

Диалог, абонентом которого является конференция (username = "conf-…"), преобразовывать в конференцию не разрешается (не связано со сложностями реализации, просто стоит внешнее ограничение, чтобы не повисали пустые конференции, связанные между собой).

Запрос

Table 20. Параметры запроса
Имя	Тип	Описание
`dialogid`	`str`	Идентификатор диалога, подлежащего переводу (master). Передается как часть Endpoint URI. В качестве параметра используется при отправке команды из сценария компонентом Операция. При отправке команды из сценария существуют и другие способы указания диалога, альтернативные этому. Все способы указания диалога перечислены ниже в порядке убывания приоритета с кратким описанием. Подробно о них см. в параметрах операции поиска звонка. `dialogid` – по идентификатору диалога. `inviteid` – по идентификатору вызова, приводящего к диалогу. `callid` – по идентификатору `Call-Id` одного из плечей диалога. `uri` – по URI одного из участников диалога: `"<sip:username@domain>"`. `from` – по номеру телефона или логину SIP-пользователя. Используется дополнительный параметр `mode`: `"number"` или `"sipuser"`. `sipuserid` – по идентификатору учетной записи SIP-пользователя. `sipuserlogin` – по логину учетной записи SIP-пользователя. `sipuserphonenumber` – по номеру телефона учетной записи SIP-пользователя. `userid` – по идентификатор учетной записи пользователя системы.
`referto`	`str`	Полный номер конференции вместе с префиксом КАФ. Параметр необязательный. При его отсутствии генерируется случайный 8-значный номер конференц-комнаты, а в качестве префикса применяется префикс первого обнаруженного в домене featurecode с типом `conf`.
`by`	`str`	Номер или username абонента, от имени которого следует осуществлять перевод в конференц-комнату. Параметр необязательный. Значение по умолчанию: `"callmanager"`. Для указанного абонента должен быть доступным маршрут до конференц-комнаты (правила маршрутизации определяются сущностями route и vectorrule).
`response_mode`	`int`	Режим возврата ответа. Чем больше значение, тем позже отправляется ответ, и тем больше контекстной информации в ответе содержится. Возможные варианты: `0` – отправлять ответ сразу после инициации вызовов IVR1→X и IVR2→Y. Отправляется почти моментально без ожидания ответов от абонентов X и Y. В ответе содержится только CallId инициирующих вызовов IVR1→X и IVR2→Y. `1` – отправлять ответ после получения предварительных ответов от X и Y (`100-199`, IVR1→X, IVR2→Y). `2` – отправлять ответ после получения окончательных ответов от X и Y (`200-699`, IVR1→X, IVR2→Y). `3` – отправлять ответ после получения предварительных ответов от CONF (`101-199`, X→CONF, Y→CONF). Ответ `100` исключается, поскольку его отправляет не конференция, а один из серверов на границе. Начиная с этого режима в контексте операции содержится информация о целевых диалогах с конференцией. `4` – отправлять ответ после получения окончательных ответов от CONF (`200-699`, X→CONF, Y→CONF). Начиная с этого режима в ответе содержится достоверная информация об успешности соединений X→CONF и Y→CONF. `5` - отправлять ответ после полного завершения операции и всех ее процессов (исключая сами диалоги X→CONF и Y→CONF, которые могут продолжаться несколько часов). По умолчанию `4`.
`binding`	`str`	Метка, привязываемая к подменяющему звонку и следом к переводному звонку. По умолчанию не назначается.

Пример запроса

SWITCHCONF /rest/v1/uc/calls/rDlg-002-Maw6qN HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "referto":"*99358",
  "by":"sip3",
  "response_mode": 4
}

Ответ

Table 21. Описание полей
Поле	Описание
`dialogid`	Идентификатор диалога, подлежащего преобразованию в конференцию. Совпадает с идентификатором в endpoint или переходит без изменений из параметров запроса.
`referto`	Строка с номером, применяемым для перевода на конференцию. Указывает сгенерированный системой полный номер с префиксом, либо указанный в запросе в поле `referto`.
`result`	Итоговый результат по операции. Варианты значений.
`confid`	Идентификатор конференции, в которую перенаправлены абоненты.
`x_ivrcallid`	Call-Id инициирующего автоматического звонка IVR1→X (отличается от CallId плечей целевого диалога с конференцией). Присутствует в любом случае.
`x_new_acallid`	Call-Id звонка, поступившего в систему от абонента Y к абоненту Z после обработки SIP-запроса REFER. Это Call-Id плеча `A` целевого диалога Y→Z. При некоторых неудачных результатах операции может отсутствовать.
`x_new_last_response`	Response-Line последнего полученного ответа от абонента Z, по результатам которого сформирован ответ на запрос. При некоторых неудачных результатах операции может отсутствовать.
`x_new_dialogid`	Идентификатор целевого диалога Y→Z. При некоторых неудачных результатах операции может отсутствовать. Также может отсутствовать если длительность диалога 0 секунд.
`y_ivrcallid`	Call-Id инициирующего автоматического звонка IVR2→Y (отличается от CallId плечей целевого диалога с конференцией). Присутствует в любом случае.
`y_new_acallid`	Call-Id звонка, поступившего в систему от абонента Y к абоненту Z после обработки SIP-запроса REFER. Это Call-Id плеча `A` целевого диалога Y→Z. При некоторых неудачных результатах операции может отсутствовать.
`y_new_last_response`	Response-Line последнего полученного ответа от абонента Z, по результатам которого сформирован ответ на запрос. При некоторых неудачных результатах операции может отсутствовать.
`y_new_dialogid`	Идентификатор целевого диалога Y→Z. При некоторых неудачных результатах операции может отсутствовать. Также может отсутствовать если длительность диалога 0 секунд.

Table 22. Варианты значений поля result
Значение	Описание
`"ok"`	Ответ сформирован на этапе, где не выявлено проблем для успешного создания диалога Y→Z. Например, для `response_mode=0` – сценарии IVR успешно инициализированы для вызова IVR1→X и IVR2→Y. `response_mode=1` – получены предварительные ответы от абонентов X и Y (IVR1→X, IVR2→Y). `response_mode=2` – получен окончательные ответы `2xx` от абонентов X и Y (IVR1→X, IVR2→Y). `response_mode=3` – получен окончательные ответы `2xx` от абонентов X и Y (IVR1→X, IVR2→Y), после чего инициализированы вызовы X→CONF и Y→CONF, получены предварительные ответы `18x` или окончательные ответы `2xx` от CONF в обоих диалогах. `response_mode=4` – получен окончательные ответы `2xx` от абонентов X и Y (IVR1→X, IVR2→Y), после чего инициализированы вызовы X→CONF и Y→CONF, получены окончательные ответы `2xx` от CONF в обоих диалогах. `response_mode=5` – диалоги X→CONF и Y→CONF установлены, после некоторого небольшого таймаута инициализирующие процессы завершены.

Пример ответа

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "dialogid": "rDlg-002-Maw6qN",
  "referto": "*99358",
  "result": "ok",
  "confid": "rCF-005-ZIzwBi",
  "x_ivrcallid": "rIV-006-D0qaTIsaTzBoWDHiAYgCIOo7odO",
  "x_new_acallid": "27142922@192.168.0.149",
  "x_new_dialogid": "rDlg-002-UTx2LP",
  "x_new_last_response": "SIP/2.0 200 OK",
  "y_ivrcallid": "rIV-006-TTBdJOR0ifh8HYiE9sVwqqJ31HW",
  "y_new_acallid": "817803971@192.168.0.147",
  "y_new_dialogid": "rDlg-002-XVRAsk",
  "y_new_last_response": "SIP/2.0 200 OK"
}

Перевод звонка в конференцию (REFERCONF)

Производит перевод указанного звонка (оппонента в диалоге) на существующую конференцию. Это аналог операции перевод на номер с автоматическим поиском конференции, вычислением и подстановкой номера конференции для маршрутизации.

Операция проводится через запуск скрытого служебного сценария, осуществляющего подготовленный дозвон до указанного абонента с подменой конкретного указанного диалога (компонент сценария "Дозвон" с установленными заголовками Replaces и Referred-By) и последующей передачей управления специально подготовленному скрытому IVR сценарию с компонентом "Перевод на номер". В качестве номера для перевода подставляется номер обнаруженной конференции, как featurecode + confroomnum. В случае неудачи перевода следующий компонент переводит абонента обратно на номер переводившего.

Схема процесса: X→CONF (hold), X→Y | IVR→Y, IVR REFER CONF, Y→CONF.

Перевод осуществляется в домене конференции. Если вдруг выполнение запроса производится в другом домене относительно конференции, то возвращается ошибка. Это возможно в том случае, если в конференции участвует абонент из другого домена, и указание конференции производится путем ссылки на его диалог.

После успешного завершения операции переводивший абонент X остается в режиме удержания конференции. Для возврата к ней ему требуется снять ее с удержания, пользуясь командами своего SIP-устройства.

Альтернативный данной операции подход – пользоваться методом "Перевод на номер", указывая номер, по которому доступна конкретная конференц-комната.

Запрос

Table 23. Параметры запроса
Имя	Тип	Описание
`dialogid`	`str`	Идентификатор диалога, подлежащего переводу в конференцию. Передается как часть Endpoint URI. В качестве параметра используется при отправке команды из сценария компонентом Операция. При отправке команды из сценария существуют и другие способы указания диалога, альтернативные этому. Все способы указания диалога перечислены ниже в порядке убывания приоритета с кратким описанием. Подробно о них см. в параметрах операции поиска звонка. `dialogid` – по идентификатору диалога. `inviteid` – по идентификатору вызова, приводящего к диалогу. `callid` – по идентификатору `Call-Id` одного из плечей диалога. `uri` – по URI одного из участников диалога: `"<sip:username@domain>"`. `from` – по номеру телефона или логину SIP-пользователя. Используется дополнительный параметр `mode`: `"number"` или `"sipuser"`. `sipuserid` – по идентификатору учетной записи SIP-пользователя. `sipuserlogin` – по логину учетной записи SIP-пользователя. `sipuserphonenumber` – по номеру телефона учетной записи SIP-пользователя. `userid` – по идентификатор учетной записи пользователя системы.
`by`	`str`	Сторона диалога, инициирующая перевод звонка в конференцию. `SIP URI` или `Call-Id`. На основании значения вычисляется оппозитная сторона, которую следует перевести. Именно ей отправляется SIP-запрос INVITE с Replaces из IVR и последующий SIP-запрос REFER.
`referdialogid`	`str`	Идентификатор диалога, одним из участников которого является конференция – назначение перевода. Это один из возможных способов указания конференции, являющейся целью перевода. Существуют и другие способы указания конференции, альтернативные этому. Все способы указания конференции перечислены ниже в порядке убывания приоритета с кратким описанием. Подробно о них см. в параметрах операции поиска звонка с добавлением префикса `"refer"`. Через указание диалога, одной из сторон которого является целевая конференция: `referdialogid` – по идентификатору диалога. `referinviteid` – по идентификатор вызова, приводящего к диалогу. `refercallid` – по идентификатору `Call-Id` одного из плечей диалога. `referuri` – по URI одного из участников диалога: `"<sip:username@domain>"`. `referfrom` – по номеру телефона или логину SIP-пользователя. Используется дополнительный параметр `mode`: `"number"` или `"sipuser"`. `refersipuserid` – по идентификатору учетной записи SIP-пользователя. `refersipuserlogin` – по логину учетной записи SIP-пользователя. `refersipuserphonenumber` – по номеру телефона учетной записи SIP-пользователя. `referuserid` – по идентификатор учетной записи пользователя системы. Через непосредственное указание конференции: `referconfid` – по идентификатору конференции. `referconfroomnum` – по номеру конференц-комнаты. `referconfnumber` – по телефонному номеру доступа в конференцию, содержащему префикс featurecode.
`response_mode`	`int`	Режим возврата ответа. Чем больше значение, тем позже отправляется ответ, и тем больше контекстной информации в ответе содержится. Возможные варианты: `0` – отправлять ответ сразу после инициации вызова IVR→Y. Отправляется почти моментально без ожидания ответов от абонентов Y и CONF. В ответе содержится только CallId инициирующего вызова IVR→Y. `1` – отправлять ответ после получения предварительного ответа от Y (`100-199`, IVR→Y). `2` – отправлять ответ после получения окончательного ответа от Y (`200-699`, IVR→Y). `3` – отправлять ответ после получения предварительного ответа от Z (`101-199`, Y→CONF). Ответ `100` исключается, поскольку его отправляет не SIP-UA конференции, а сервер. Начиная с этого режима в контексте звонка содержится информация о целевом диалоге. `4` – отправлять ответ после получения окончательного ответа от Z (`200-699`, Y→CONF). Начиная с этого режима в ответе содержится достоверная информация об успешности соединения Y→CONF. `5` - отправлять ответ после полного завершения операции и всех ее процессов (исключая сам диалог Y→CONF, который может продолжаться несколько часов). По умолчанию `3`.
`binding`	`str`	Метка, привязываемая к подменяющему звонку и следом к переводному звонку. По умолчанию не назначается.

Пример запроса

REFERCONF /rest/v1/uc/calls/rDlg-002-96Ptom HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "by": "2362769183@192.168.0.203",
  "referdialogid": "rDlg-002-96Ptom",
  "response_mode": 3
}

Ответ

Пример ответа

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "dialogid": "rDlg-002-96Ptom",
  "result": "ok",
  "ivrcallid": "rIV-006-1pq2q9apUWvHHJRXiImXOlPrOOC",
  "new_acallid": "1920460747@192.168.0.149",
  "new_dialogid": "rDlg-002-Uf38zV",
  "new_last_response": "SIP/2.0 180 Ringing"
}

Отправка события управления устройством (NOTIFY)

Реализует софтверное управление устройством абонента по инициативе сервера.

Производит отправку запроса NOTIFY с сообщением о событии на устройство указанного абонента. В частности, это может быть использовано для управления устройством в соответствии с расширением Cisco Broadsoft (https://pubhub.devnetcloud.com/media/broadsoft-docs/docs/pdf/BW-SIPAccessSideExtensionsInterfaceSpec.pdf) В зависимости от типа сообщения устройство может:

ответить на звонок (talk),
перейти в режим удержания (hold),
выйти из режима удержания (talk),
объединить удерживаемых абонентов в управляемой телефоном конференции (conference)
прочее

Операция проводится в режиме вызова для вызываемой стороны (talk), либо в режиме диалога для любой из сторон.

В соответствии с RFC3265 поддерживаемые события перечисляются устройством в заголовке Allow-Events в запросе INVITE или в ответе 1xx/2xx. Если устройство не поддерживает расширение, то оно не отправляет соответствующие значения в заголовке, и на этом основании сервер блокирует отправку NOTIFY-запроса.

Отправка сообщения асинхронная, итоговый результат работы не сообщается. Успешный ответ означает лишь факт отправки запроса.

Сервер не применяет расширения самостоятельно, но предоставляет возможность внешним по отношению к системе образом использовать их функциональность через API и сценарии. Состав поддерживаемых расширений определяется устройством. Качество поддержки расширения устройствами системой не гарантируется. В качестве рекомендации: использовать метод только в опциональном режиме и в случае, когда достоверно известно что все используемые устройства поддерживают метод и не предвидится иное.

Запрос

Table 24. Параметры запроса
Имя	Тип	Описание
`dialogid`	`str`	Идентификатор диалога, подлежащего переводу в конференцию. Передается как часть Endpoint URI. В качестве параметра используется при отправке команды из сценария компонентом Операция. При отправке команды из сценария существуют и другие способы указания диалога, альтернативные этому. Все способы указания диалога перечислены ниже в порядке убывания приоритета с кратким описанием. Подробно о них см. в параметрах операции поиска звонка. `dialogid` – по идентификатору диалога. `inviteid` – по идентификатору вызова, приводящего к диалогу. `callid` – по идентификатору `Call-Id` одного из плечей диалога. `uri` – по URI одного из участников диалога: `"<sip:username@domain>"`. `from` – по номеру телефона или логину SIP-пользователя. Используется дополнительный параметр `mode`: `"number"` или `"sipuser"`. `sipuserid` – по идентификатору учетной записи SIP-пользователя. `sipuserlogin` – по логину учетной записи SIP-пользователя. `sipuserphonenumber` – по номеру телефона учетной записи SIP-пользователя. `userid` – по идентификатор учетной записи пользователя системы.
`callid`	`str`	Сторона диалога, управление устройством которой производится, `Call-Id`.
`event`	`str`	Название события для управления устройством (`talk`,`hold`,`conference`,`refer`,`check-sync`,…)

Пример запроса

NOTIFY /rest/v1/uc/calls/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "callid": "4139247432@192.168.0.149",
  "event": "talk"
}

Ответ

Пример ответа

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "result": "ok",
  "dialogid": "rDlg-002-WOabz0"
}

Отправка DTMF сигнала в плечо (SEND_DTMF)

Реализует отправку DTMF символов в указанное плечо указанного диалога. Поддерживается отправка последовательностей. Ответ на запрос поступает сразу, но в плече возникает очередь отправки отдельных символов. Та же очередь используется при поступлении нескольких запросов.

Позволяет задавать последовательность DTMF символов, включающую символы ' и ,. Каждый такой символ обеспечивают паузу в 1 секунду в наборе DTMF.

В зависимости от указанного протокола (proto): * sipinfo - производит отправку запроса INFO с передачей DTMF символа. * rfc2833 - производит отправку RTP пакетов согласно протоколу RFC-2833.

Отправка сообщения асинхронная, итоговый результат работы не сообщается. Успешный ответ означает лишь факт отправки запроса или серии RTP-пакетов.

Запрос

Table 25. Параметры запроса
Имя	Тип	Описание
`dialogid`	`str`	Идентификатор диалога, подлежащего переводу в конференцию. Передается как часть Endpoint URI. В качестве параметра используется при отправке команды из сценария компонентом Операция. При отправке команды из сценария существуют и другие способы указания диалога, альтернативные этому. Все способы указания диалога перечислены ниже в порядке убывания приоритета с кратким описанием. Подробно о них см. в параметрах операции поиска звонка. `dialogid` – по идентификатору диалога. `inviteid` – по идентификатору вызова, приводящего к диалогу. `callid` – по идентификатору `Call-Id` одного из плечей диалога. `uri` – по URI одного из участников диалога: `"<sip:username@domain>"`. `from` – по номеру телефона или логину SIP-пользователя. Используется дополнительный параметр `mode`: `"number"` или `"sipuser"`. `sipuserid` – по идентификатору учетной записи SIP-пользователя. `sipuserlogin` – по логину учетной записи SIP-пользователя. `sipuserphonenumber` – по номеру телефона учетной записи SIP-пользователя. `userid` – по идентификатор учетной записи пользователя системы.
`callid`	`str`	Сторона диалога, в которую необходимо направить DTMF-символ, `Call-Id`.
`side`	`str`	Альтернативное указание стороны диалога (`a` - инициатор вызова, `b` - адресат вызова), либо `Call-Id`.
`opposite`	`bool`	Признак взятия другой стороны относительно указанной.
`proto`	`str`	Выбор режима отправки DTMF-символа (`rfc2833`, `sipinfo`). По умолчанию `sipinfo`.
`dtmf`	`str`	DTMF-символ для отправки (`0-9*#`). Поддерживается только посимвольная отправка.

Пример запроса

SEND_DTMF /rest/v1/uc/calls/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "dtmf": "2",
  "proto": "rfc2833",
  "callid": "4139247432@192.168.0.149"
}

Ответ

Пример ответа

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "result": "ok",
  "dialogid": "rDlg-002-WOabz0"
}

Запуск/остановка стенографирования речи одной из сторон (SETUP_ASR)

Включает/выключает запись и распознавание в текст указанного плеча указанного диалога.

Успешный ответ на операцию включения означает лишь факт отправки запроса или серии RTP-пакетов.

При выключении режима ответ на запрос задерживается на несколько секунд до завершения сессии распознавания.

Для получения событий о результате по мере распознавания можно воспользоваться websocket api.

Режим работает при установленной и настроенной подсистеме стенографирования речи (мастер-домен, settings.record_asr_options)

Запрос

Table 26. Параметры запроса
Имя	Тип	Описание
`dialogid`	`str`	Идентификатор диалога, подлежащего переводу в конференцию. Передается как часть Endpoint URI. В качестве параметра используется при отправке команды из сценария компонентом Операция. При отправке команды из сценария существуют и другие способы указания диалога, альтернативные этому. Все способы указания диалога перечислены ниже в порядке убывания приоритета с кратким описанием. Подробно о них см. в параметрах операции поиска звонка. `dialogid` – по идентификатору диалога. `inviteid` – по идентификатору вызова, приводящего к диалогу. `callid` – по идентификатору `Call-Id` одного из плечей диалога. `uri` – по URI одного из участников диалога: `"<sip:username@domain>"`. `from` – по номеру телефона или логину SIP-пользователя. Используется дополнительный параметр `mode`: `"number"` или `"sipuser"`. `sipuserid` – по идентификатору учетной записи SIP-пользователя. `sipuserlogin` – по логину учетной записи SIP-пользователя. `sipuserphonenumber` – по номеру телефона учетной записи SIP-пользователя. `userid` – по идентификатор учетной записи пользователя системы.
`command`	`str`	Операция: `add` (включение режима) или `remove` (выключение режима).
`layer`	`str`	Указание уникального имени слоя. Поддерживается одновременно несколько слоев, при указании существующего слоя происходит его замещение. Для того, чтобы остановить запись и распознавание, также требуется указать существующий слой.
`callid`	`str`	Сторона диалога, в которую необходимо направить DTMF-символ, `Call-Id`.
`side`	`str`	Альтернативное указание стороны диалога (`a` - инициатор вызова, `b` - адресат вызова), либо `Call-Id`.
`opposite`	`bool`	Признак взятия другой стороны относительно указанной.
`result_text`	`bool`	Для операции остановки устанавливает режим ожидания и возврата итогового текста. В случае true (по умолчанию) ответ задерживается на 2-3 секунды.

Пример запроса

SEND_DTMF /rest/v1/uc/calls/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "layer": "default",
  "side": "b"
}

Ответ

Пример ответа

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "result": "ok",
  "dialogid": "rDlg-002-WOabz0",
  "layer": "default"
}

Включение/выключение (добавление/удаление) канала записи диалога (SETUP_RECORD)

Включает/выключает канал записи указанного диалога.

Запрос

Table 27. Параметры запроса
Имя	Тип	Описание
`dialogid`	`str`	Идентификатор диалога, подлежащего переводу в конференцию. Передается как часть Endpoint URI. В качестве параметра используется при отправке команды из сценария компонентом Операция. При отправке команды из сценария существуют и другие способы указания диалога, альтернативные этому. Все способы указания диалога перечислены ниже в порядке убывания приоритета с кратким описанием. Подробно о них см. в параметрах операции поиска звонка. `dialogid` – по идентификатору диалога. `inviteid` – по идентификатору вызова, приводящего к диалогу. `callid` – по идентификатору `Call-Id` одного из плечей диалога. `uri` – по URI одного из участников диалога: `"<sip:username@domain>"`. `from` – по номеру телефона или логину SIP-пользователя. Используется дополнительный параметр `mode`: `"number"` или `"sipuser"`. `sipuserid` – по идентификатору учетной записи SIP-пользователя. `sipuserlogin` – по логину учетной записи SIP-пользователя. `sipuserphonenumber` – по номеру телефона учетной записи SIP-пользователя. `userid` – по идентификатор учетной записи пользователя системы.
`command`	`str`	Операция: `add` (включение режима) или `remove` (выключение режима).
`layer`	`str`	Указание уникального имени слоя. Поддерживается одновременно несколько слоев, при указании существующего слоя происходит его замещение. Для того, чтобы остановить запись и распознавание, также требуется указать существующий слой.
`callid`	`str`	Сторона диалога, в которую необходимо направить DTMF-символ, `Call-Id`.

Пример запроса

SEND_DTMF /rest/v1/uc/calls/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "layer": "default"
}

Ответ

Пример ответа

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "result": "ok",
  "dialogid": "rDlg-002-WOabz0",
  "layer": "default"
}

Управление метками диалога (SETUP_BINDINGS)

Осуществляет управление метками указанного диалога.

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

На метках основана привязка к сеансам обслуживания в КЦ (название "seance_…"), а также механизм post call survey (название "PCS:…").

В компоненте сценария Операция управление метками доступно через отдельную группу команд (метки).

Запрос

Table 28. Параметры запроса
Имя	Тип	Описание
`dialogid`	`str`	Идентификатор диалога, подлежащего переводу в конференцию. Передается как часть Endpoint URI. В качестве параметра используется при отправке команды из сценария компонентом Операция. При отправке команды из сценария существуют и другие способы указания диалога, альтернативные этому. Все способы указания диалога перечислены ниже в порядке убывания приоритета с кратким описанием. Подробно о них см. в параметрах операции поиска звонка. `dialogid` – по идентификатору диалога. `inviteid` – по идентификатору вызова, приводящего к диалогу. `callid` – по идентификатору `Call-Id` одного из плечей диалога. `uri` – по URI одного из участников диалога: `"<sip:username@domain>"`. `from` – по номеру телефона или логину SIP-пользователя. Используется дополнительный параметр `mode`: `"number"` или `"sipuser"`. `sipuserid` – по идентификатору учетной записи SIP-пользователя. `sipuserlogin` – по логину учетной записи SIP-пользователя. `sipuserphonenumber` – по номеру телефона учетной записи SIP-пользователя. `userid` – по идентификатор учетной записи пользователя системы.
`command`	`str`	Операция: * `get` - возвращает все метки диалога в виде массива в поле 'labels'. * `set` - заменяет существующее множество меток на указанные. Требует параметр 'label' - строка или список строк. * `add` - добавляет указанные метки. Требует параметр 'label' - строка или список строк. * `remove` - удаляет указанные метки. Требует параметр 'label' - строка или список строк. * `clean` - очищает все метки диалога. * `contains` - проверяет наличие указанной метки в диалоге. Требует параметр 'label' - строка. Возвращает true или false в поле 'contains'.
`label`	`str или array<str>`	Указание метки или списка меток.
`callid`	`str`	Сторона диалога, в которую необходимо направить DTMF-символ, `Call-Id`.

Пример запроса

SEND_DTMF /rest/v1/uc/calls/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "command": "add",
  "label": ["aaa", "bbb"]
}

Ответ

Пример ответа

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "result": "ok",
  "dialogid": "rDlg-002-WOabz0"
}

Завершение звонка (DELETE)

Завершает диалог. Сервер выступает инициатором разрыва для обоих абонентов (отправляет SIP-запрос BYE обоим абонентам). Если диалог находится в состоянии вызова, то всем вызываемым абонентам отправляется SIP-запрос CANCEL.

В текущей версии завершение носит внешний характер без указания в событиях класса callevents признака привязки к действиям стороны A или стороны B.

При выполнении запроса из сценария и обнаружении нескольких диалогов производится завершение их всех.

Запрос

Пример запроса

DELETE /rest/v1/uc/calls/rDlg-002-9dEcfh HTTP/1.1

Ответ

Пример успешного ответа

HTTP/1.1 200 Ok
Content-Type: application/json; charset=utf-8

{
  "dialogid": "rDlg-002-9dEcfh"
}

Пример неуспешного ответа

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "error_code": 1413,
  "error_message": "Dialog not found"
}

См. также

API /rest/v1/uc/calls_by_participation для управления ограниченным набором звонков домена с участием авторизованного пользователя.
API /rest/v1/uc/conferences для управления произвольными конференциями домена.
Компонент сценариев Операция.
Роль b2b.
Роль mware.
Роль callstore.