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

Обзор

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

Управлению доступны любые звонки: инициированные как через API, так и с SIP-устройств и сервисов SIP-UA. В отличие от API /rest/v1/uc/calls текущий endpoint предоставляет доступ только к тем диалогам, где одним из участников является учетная запись SIP-пользователя, принадлежащая пользователю, который выполняюет API-запрос.

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

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

Запросы

HTTP verb Endpoint Описание

GET

/rest/v1/uc/calls_by_participation

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

POST

/rest/v1/uc/calls_by_participation

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

INVITE

/rest/v1/uc/calls_by_participation

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

INVITEBYIVR

/rest/v1/uc/calls_by_participation

[invitebyivr]

LOOKUP

/rest/v1/uc/calls_by_participation

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

GET

/rest/v1/uc/calls_by_participation/<id>

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

REFER

/rest/v1/uc/calls_by_participation/<id>

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

REFERREPLACES

/rest/v1/uc/calls_by_participation/<id>

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

SWITCHCONF

/rest/v1/uc/calls_by_participation/<id>

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

REFERCONF

/rest/v1/uc/calls_by_participation/<id>

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

NOTIFY

/rest/v1/uc/calls_by_participation/<id>

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

SEND_DTMF

/rest/v1/uc/calls_by_participation/<id>

Отправка DTMF-символа одной из сторон (SEND_DTMF)

SETUP_ASR

/rest/v1/uc/calls_by_participation/<id>

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

SETUP_RECORD

/rest/v1/uc/calls_by_participation/<id>

Запуск/остановка (добавление/удаление) канала записи диалога (SETUP_RECORD)

SETUP_BINDINGS

/rest/v1/uc/calls_by_participation/<id>

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

STOP_HOLD_MELODY

/rest/v1/uc/calls_by_participation/<id>

Остановка мелодии ожидания (STOP_HOLD_MELODY)

DELETE

/rest/v1/uc/calls_by_participation/<id>

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

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

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

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

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

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

Запрос

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

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

Запрос проходит предварительную фильтрацию. Для допуска к выполнению необходимо, чтобы авторизованный пользователь был инициатором нового вызова. То есть указанное значение параметра "from" относилось к авторизованному пользователю (через любую из принадлежащих ему учетных записей sipuser).

Запрос

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.

use_intercom

bool

Выключатель режима intercom для вызова абонента. По умолчанию выключено.

Должны существовать фичакод с типом 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
}

Ответ

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.

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

Производит поиск ресурса (активного диалога) по указанному ключу.

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

Применение поисковых полей производится по одному в порядке убывания приоритета в приведенной ниже таблице. Поисковые поля содержат в описании "Значение для поиска". Множественный возврат возможен, например, в случае поиска по логину SIP-пользователя, если он участвует в нескольких диалогах.

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

Запрос

Table 7. Параметры запроса
Параметр Тип Описание

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_by_participation 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)

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

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

Запрос

Table 8. Параметры запроса
Имя Тип Описание

dialogid

str

Идентификатор диалога, подлежащего переводу (master).

Передается как часть Endpoint URI.

mask

str

Список полей для вывода.

flat

bool

Преобразование в плоский вид составных полей.
Пример запроса
GET /rest/v1/uc/calls_by_participation/rDlg-002-484FD3 HTTP/1.1

Ответ

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

Table 9. Поля диалога:
Поле Описание

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

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

Запрос

Table 11. Параметры запроса
Имя Тип Описание

dialogid

str

Идентификатор диалога, подлежащего переводу.

Передается как часть Endpoint URI.

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_by_participation/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 12. Описание полей
Поле Описание

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 13. Варианты значений поля 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 в сторону оппонента в подменяемом диалоге).

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

Cхема процесса основного кейса: X-Y, X-Z | IVR→Y, IVR REFER+REPLACES Z, Y→Z.

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

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

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

Запрос

Table 14. Параметры перевода звонка по dialogid.
Имя Тип Описание

masterdialogid

str

Идентификатор диалога, подлежащего переводу (master).

Передается как часть Endpoint URI.

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_by_participation/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 15. Описание полей
Поле Описание

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 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→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-…​"), преобразовывать в конференцию не разрешается (не связано со сложностями реализации, просто стоит внешнее ограничение, чтобы не повисали пустые конференции, связанные между собой).

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

Запрос

Table 17. Параметры запроса
Имя Тип Описание

dialogid

str

Идентификатор диалога, подлежащего переводу (master).

Передается как часть Endpoint URI.

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_by_participation/rDlg-002-Maw6qN HTTP/1.1
Content-Type: application/json; charset=utf-8

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

Ответ

Table 18. Описание полей
Поле Описание

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 19. Варианты значений поля 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-устройства.

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

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

Запрос

Table 20. Параметры запроса
Имя Тип Описание

dialogid

str

Идентификатор диалога, подлежащего переводу в конференцию.

Передается как часть Endpoint URI.

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_by_participation/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 и сценарии. Состав поддерживаемых расширений определяется устройством. Качество поддержки расширения устройствами системой не гарантируется. В качестве рекомендации: использовать метод только в опциональном режиме и в случае, когда достоверно известно что все используемые устройства поддерживают метод и не предвидится иное.

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

Запрос

Table 21. Параметры запроса
Имя Тип Описание

dialogid

str

Идентификатор диалога, подлежащего переводу в конференцию.

Передается как часть Endpoint URI.

callid

str

Сторона диалога, управление устройством которой производится, Call-Id.

event

str

Название события для управления устройством (talk,hold,conference,refer,check-sync,…​)
Пример запроса
NOTIFY /rest/v1/uc/calls_by_participation/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-пакетов.

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

Запрос

Table 22. Параметры запроса
Имя Тип Описание

dialogid

str

Идентификатор диалога, подлежащего переводу в конференцию.

Передается как часть Endpoint URI.

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_by_participation/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)

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

Запрос

Table 23. Параметры запроса
Имя Тип Описание

dialogid

str

Идентификатор диалога, подлежащего переводу в конференцию.

Передается как часть Endpoint URI.

command

str

Операция: add (включение режима) или remove (выключение режима).

layer

str

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

callid

str

Сторона диалога, которую необходимо отправить на стенографирование, Call-Id.

side

str

Альтернативное указание стороны диалога (a - инициатор вызова, b - адресат вызова), либо Call-Id.

opposite

bool

Признак взятия другой стороны относительно указанной.

result_text

bool

Для операции остановки устанавливает режим ожидания и возврата итогового текста. В случае true (по умолчанию) ответ задерживается на 2-3 секунды.
Пример запроса
SETUP_ASR /rest/v1/uc/calls_by_participation/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)

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

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

Запрос

Table 24. Параметры запроса
Имя Тип Описание

dialogid

str

Идентификатор диалога, подлежащего переводу в конференцию.

Передается как часть Endpoint URI.

command

str

Операция: add (включение режима) или remove (выключение режима).

layer

str

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

callid

str

Сторона диалога, которую необходимо поставить на запись, Call-Id.

side

str

Альтернативное указание стороны диалога (a - инициатор вызова, b - адресат вызова), либо Call-Id.
Пример запроса
SETUP_RECORD /rest/v1/uc/calls_by_participation/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:…​").

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

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

Запрос

Table 25. Параметры запроса
Имя Тип Описание

dialogid

str

Идентификатор диалога, подлежащего переводу в конференцию.

Передается как часть Endpoint URI.

command

str

Операция:

  • get - возвращает все метки диалога в виде массива в поле 'labels'.

  • set - заменяет существующее множество меток на указанные. Требует параметр 'label' - строка или список строк.

  • add - добавляет указанные метки. Требует параметр 'label' - строка или список строк.

  • remove - удаляет указанные метки. Требует параметр 'label' - строка или список строк.

  • clean - очищает все метки диалога.

  • contains - проверяет наличие указанной метки в диалоге. Требует параметр 'label' - строка. Возвращает true или false в поле 'contains'.

label

str или array<str>

Указание метки или списка меток.
Пример запроса
SETUP_BINDINGS /rest/v1/uc/calls_by_participation/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"
}

Остановка мелодии ожидания (STOP_HOLD_MELODY)

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

Остановить можно на один раз или на весь диалог.

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

Запрос

Table 26. Параметры запроса
Имя Тип Описание

dialogid

str

Идентификатор диалога, подлежащего переводу в конференцию.

Передается как часть Endpoint URI.

mode

str

Операция:

  • temporary - останавливает текущую мелодию ожидания, если звонок находится на удержании, иначе возвращает ошибку. Используется по умолчанию.

  • once - останавливает текущую мелодию ожидания, если звонок находится на удержании, или иначе предотвращает воспроизведение мелодии ожидания для предстоящего удержания.

  • permanent - останавливает текущую мелодию ожидания и предотвращает воспроизведение мелодии ожидания для всех будущих удержаний текущего диалога.
Пример запроса
STOP_HOLD_MELODY /rest/v1/uc/calls_by_participation/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "mode": "once"
}

Ответ

Пример ответа
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.

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

Запрос

Пример запроса
DELETE /rest/v1/uc/calls_by_participation/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 с доступом к произвольным звонкам домена без ограничений по пользователям.

  • API /rest/v1/uc/conferences_by_participation для управления конференциями домена с участием авторизованного пользователя.

  • Роль b2b.

  • Роль mware.

  • Роль callstore.

  • Персонализация
  • Увеличить шрифт
  • Уменьшить шрифт