Управление своими конференциями (conferences)

Обзор

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

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

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

Запросы

HTTP verb Endpoint Описание

GET

/rest/v1/user/sip/conferences

Получение списка конференций

LOOKUP

/rest/v1/user/sip/conferences

Поиск конферениции по ключу

GET

/rest/v1/user/sip/conferences/<confid>

Получение данных конференции

DELETE

/rest/v1/user/sip/conferences/<confid>

Завершение конференции

GET

/rest/v1/user/sip/conferences/<confid>/paticipants

Получение списка участников конференции

POST

/rest/v1/user/sip/conferences/<confid>/paticipants

Добавление участника в конференцию

GET

/rest/v1/user/sip/conferences/<confid>/paticipants/<parid>

Получение данных участника

DELETE

/rest/v1/user/sip/conferences/<confid>/paticipants/<parid>

Удаление участника конференции

GET

/rest/v1/user/sip/conferences/<confid>/topology

Получение текущей топологии

POST

/rest/v1/user/sip/conferences/<confid>/topology

Изменение текущей топологии

Получение списка конференций

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

Конференция относится к домену, если маршрутизация на нее проходит через КАФ этого домена (сущность featurecode с типом conference).

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

Запрос

Table 1. Параметры запроса (необязательные)
Имя Тип Описание

filter

object

Фильтр по значениям полей.

mask

str

Список полей для вывода. Доступные поля для выдачи: confid, confroomnum, confnumber, uri, site, startts, uris

offset

int

Смещение в списке ресурсов, подлежащих выдаче.

limit

int

Максимальное количество ресурсов в списке.

order

array<object|str>

Порядок сортировки ресурсов в списке.

flat

bool

Преобразование в плоский вид составных полей.

countonly

bool

Возврат лишь количества элементов.

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

Пример запроса
GET /rest/v1/user/sip/conferences?offset=0&limit=2 HTTP/1.1

Ответ

Возвращает ограниченное количество полей: confid, confroomnum, confnumber, uri, site, startts, uris. При указании других полей в mask они будут проигнорированы.

Возвращает список объектов, каждый из которых представляет собой отдельный диалог. Состав возвращаемых полей ограничен: confid, confroomnum, confnumber, uri, site, startts, uris. При указании других полей в параметре mask они будут проигнорированы.

Table 2. Поля конференции:
Поле Описание

confid

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

confroomnum

Номер конференц-комнаты. Строковое представление числа в десятичном виде. Используется совместно с префиксом featurecode в телефонном номере доступа в конференцию.

confnumber

Номер конференции. Строковое представление числа в шестнадцатиричном виде. Используется в идентификаторе конференции confid.

confuri

Строковое представление URI конференц-комнаты.

Формат: "<sip:conf-ROOMNUMBER@DOMAIN>".

site

Название сайта, серверы которого обслуживают конференцию.

startts

Тайм-штамп времени поступления инициирующего SIP-запроса INVITE на сервер конференций. Является представлением момента времени и может быть преобразован к конкретной дате в любом часовом поясе.

Например, 1571743463336.
Пример ответа
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "confid": "rCF-005-PhKjyX",
    "confnumber": "PhKjyX",
    "confroomnum": "9",
    "confuri": "<sip:conf-9@test.rootdomain.ru>",
    "site": "SITE1",
    "startts": 1572033454296
  }
]

Поиск конферениции по ключу

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

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

Поиск конференции производится либо непосредственно, либо через диалог, одним из участников которого является конференция, а другим любой другой SIP-UA.

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

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

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

dialogid

str

Значение для поиска диалога с конференцией.

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

Например, "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-пользователей является одним из абонентов.

confid

str

Значение для поиска конференции.

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

Например, "rDlg-002-6FpTv2".

confuri

str

Значение для поиска конференции.

SIP URI конференц-комнаты "<sip:conf-ROOMNUMBER@domain>". Значение содержится в SIP-сообщениях диалога на стороне, связанной с конференцией.

Например, "<sip:conf-387@sample.domain>"

confroomnum

str

Значение для поиска конференции.

Номер конференц-комнаты. Строковое представление числа в десятичном виде. Используется совместно с префиксом featurecode в телефонном номере доступа в конференцию.

Например, "387"

confnumber

str

Значение для поиска конференции.

Номер конференции. Строковое представление числа в шестнадцатиричном виде. Используется в идентификаторе конференции confid.

Например, "6FpTv2".

Запрос

Пример запроса
LOOKUP /rest/v1/user/sip/conferences HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "sipuserphonenumber":"12"
}

Ответ

Пример успешного ответа
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8

[
  "rCF-005-PhKjyX"
]
Пример неуспешного ответа
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "error_code": 1404,
  "error_message": "Conference not found"
}

Получение данных конференции

Возвращает информацию об активной конференции.

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

Запрос

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

confid

str

Идентификатор конференции.

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

mask

str

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

flat

bool

Преобразование в плоский вид составных полей.
Пример запроса
GET /rest/v1/user/sip/conferences/rCF-005-PhKjyX HTTP/1.1

Ответ

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

Table 5. Поля возвращаемого объекта:
Поле Описание

confid

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

confroomnum

Номер конференц-комнаты. Строковое представление числа в десятичном виде. Используется совместно с префиксом featurecode в телефонном номере доступа в конференцию.

confnumber

Номер конференции. Строковое представление числа в шестнадцатиричном виде. Используется в идентификаторе конференции confid.

confuri

Строковое представление URI конференц-комнаты.

Формат: "<sip:conf-ROOMNUMBER@DOMAIN>".

site

Название сайта, серверы которого обслуживают конференцию.

startts

Тайм-штамп времени поступления инициирующего SIP-запроса INVITE на сервер конференций. Является представлением момента времени и может быть преобразован к конкретной дате в любом часовом поясе.

Например, 1571743463336.
Пример ответа
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "confid": "rCF-005-PhKjyX",
  "confnumber": "PhKjyX",
  "confroomnum": "9",
  "confuri": "<sip:conf-9@test.rootdomain.ru>",
  "site": "SITE1",
  "startts": 1572033454296
}

Завершение конференции

Завершает активную конференцию. Сервер выступает инициатором разрыва для всех участников конференции (отправляет каждому SIP-запрос BYE). Если конференция имеет исходящие звонки, не завершенные окончательным ответом 2xx-6xx, то всем вызываемым абонентам отправляется SIP-запрос CANCEL.

Результат возвращается сразу после размещения запроса в очереди сервера конференций – без ожидания завершения конференции и ответов всех абонентских устройств.

Запрос

Пример запроса
DELETE /rest/v1/user/sip/conferences/rCF-005-PhKjyX HTTP/1.1

Ответ

Пример успешного ответа
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "confid": "rCF-005-PhKjyX"
}
Пример неуспешного ответа
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "error_code": 1404,
  "error_message": "Conference not found"
}

Получение списка участников конференции

Особенности

Возвращает список активных участников конференции.

Запрос

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

confid

str

Идентификатор конференции.

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

filter

object

Фильтр по значениям полей.

mask

str

Список полей для вывода. Доступные поля для выдачи: confid, confroomnum, confnumber, uri, site, startts, uris

offset

int

Смещение в списке ресурсов, подлежащих выдаче.

limit

int

Максимальное количество ресурсов в списке.

order

array<object|str>

Порядок сортировки ресурсов в списке.

flat

bool

Преобразование в плоский вид составных полей.

countonly

bool

Возврат лишь количества элементов.

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

Пример запроса
GET /rest/v1/user/sip/conferences/rCF-005-PhKjyX/participants?offset=0&limit=2 HTTP/1.1

Ответ

Table 7. Поля участника:
Поле Описание

participantid

Идентификатор участника конференции. Используется в endpoint.

state

Состояние участника. Варианты значений: "active" и "calling".

callid

Call-Id плеча между b2b и conf. Содержится в соответствующем заголовке SIP-запроса INVITE (полученного или отправленного).

На схеме: Abonent-UA – B2BUA – CONF-UA – Call-Id плеча между B2BUA и CONF-UA.

luri

Строковое представление URI конференции (у всех участников одинаковое значение, совпадающиее со значением поля confuri конференции.

На схеме: Abonent-UA(URI1,Tag1) – (URI2,Tag2)B2BUA(URI3,Tag3) – (URI4,Tag4)CONF-UA – это URI4.

ltag

Локальный таг в URI конференции в диалоге с участником на плече с конференцией.

На схеме: Abonent-UA(URI1,Tag1) – (URI2,Tag2)B2BUA(URI3,Tag3) – (URI4,Tag4)CONF-UA – это Tag4.

ruri

Строковое представление URI участника.

Формат: "<sip:USERNAME@DOMAIN>", где USERNAME и DOMAIN строго соответствуют значениям в заголовке.

На схеме: Abonent-UA(URI1,Tag1) – (URI2,Tag2)B2BUA(URI3,Tag3) – (URI4,Tag4)CONF-UA – это URI3.

rtag

Таг в URI абонента в диалоге с участником на плече с конференцией.

На схеме: Abonent-UA(URI1,Tag1) – (URI2,Tag2)B2BUA(URI3,Tag3) – (URI4,Tag4)CONF-UA – это Tag3.
Пример ответа
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "participantid": "139cfa11-016e-04e2-7efe-02004c4f4f50",
    "state": "active",
    "callid": "rB2-002-1rG74m-01-934846955@192.168.0.146",
    "luri": "<sip:conf-9@test.rootdomain.ru>",
    "ltag": "rCF-005-9aGAQr",
    "ruri": "<sip:13@test.rootdomain.ru>",
    "rtag": "rB2-002-ARuy"
  },
  {
    "participantid": "5fade58d-016e-04e2-6ac5-02004c4f4f50",
    "state": "active",
    "callid": "rB2-002-MonYHz-01-2617018390@192.168.0.147",
    "luri": "<sip:conf-9@test.rootdomain.ru>",
    "ltag": "rCF-005-AHoiiQ",
    "ruri": "<sip:11@test.rootdomain.ru>",
    "rtag": "rB2-002-OZQo"
  },
  {
    "participantid": "6f6faa22-016e-047e-e0d8-02004c4f4f50",
    "state": "active",
    "callid": "rB2-002-aSB1Mw-01-17719884@192.168.0.149",
    "luri": "<sip:conf-9@test.rootdomain.ru>",
    "ltag": "rCF-005-CZ0Jjl",
    "ruri": "<sip:12@test.rootdomain.ru>",
    "rtag": "rB2-002-aoMh"
  }
]

Добавление участника в конференцию

Инициирует новый вызов из конференции на указанный номер.

Результат возвращается без ожидания ответа абонента сразу после добавления участника в конференцию.

Запрос

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

confid

str

Идентификатор конференции.

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

to

str

Номер вызываемого абонента.
Пример запроса
POST /rest/v1/user/sip/conferences/rCF-005-PhKjyX/participants HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "to":"2216"
}

Ответ

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

confid

Идентификатор конференции.

Дублирует идентификатор из endpoint. Может применяться при выполнении команды из сценария и указания конференции отличным от идентификатора способом.

participantid

Call-Id инициирующего автоматического звонка IVR→X (отличается от CallId плечей целевого диалога). Присутствует в любом случае.
Пример ответа
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "confid": "rCF-009-5HkaiZ",
  "participantid": "c47067b6-016d-9085-40fd-e0d55eb5fab1"
}

Получение данных участника

Возвращает информацию об участнике конференции.

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

Запрос

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

confid

str

Идентификатор конференции.

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

participantid

str

Идентификатор участника конференции.

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

mask

str

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

flat

bool

Преобразование в плоский вид составных полей.
Пример запроса
GET /rest/v1/user/sip/conferences/rCF-005-PhKjyX/participants/139cfa11-016e-04e2-7efe-02004c4f4f50 HTTP/1.1

Ответ

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

Table 11. Поля участника:
Поле Описание

participantid

Идентификатор участника конференции. Используется в endpoint.

state

Состояние участника. Варианты значений: "active" и "calling".

callid

Call-Id плеча между b2b и conf. Содержится в соответствующем заголовке SIP-запроса INVITE (полученного или отправленного).

На схеме: Abonent-UA – B2BUA – CONF-UA – Call-Id плеча между B2BUA и CONF-UA.

luri

Строковое представление URI конференции (у всех участников одинаковое значение, совпадающиее со значением поля confuri конференции.

На схеме: Abonent-UA(URI1,Tag1) – (URI2,Tag2)B2BUA(URI3,Tag3) – (URI4,Tag4)CONF-UA – это URI4.

ltag

Локальный таг в URI конференции в диалоге с участником на плече с конференцией.

На схеме: Abonent-UA(URI1,Tag1) – (URI2,Tag2)B2BUA(URI3,Tag3) – (URI4,Tag4)CONF-UA – это Tag4.

ruri

Строковое представление URI участника.

Формат: "<sip:USERNAME@DOMAIN>", где USERNAME и DOMAIN строго соответствуют значениям в заголовке.

На схеме: Abonent-UA(URI1,Tag1) – (URI2,Tag2)B2BUA(URI3,Tag3) – (URI4,Tag4)CONF-UA – это URI3.

rtag

Таг в URI абонента в диалоге с участником на плече с конференцией.

На схеме: Abonent-UA(URI1,Tag1) – (URI2,Tag2)B2BUA(URI3,Tag3) – (URI4,Tag4)CONF-UA – это Tag3.
Пример ответа
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "participantid": "139cfa11-016e-04e2-7efe-02004c4f4f50",
  "state": "active",
  "callid": "rB2-002-1rG74m-01-934846955@192.168.0.146",
  "luri": "<sip:conf-9@test.rootdomain.ru>",
  "ltag": "rCF-005-9aGAQr",
  "ruri": "<sip:13@test.rootdomain.ru>",
  "rtag": "rB2-002-ARuy"
}

Удаление участника конференции

Исключает участника из конференции, в следствие чего абоненту отправляется SIP-запрос BYE.

Результат возвращается сразу после размещения запроса в очереди сервера конференций – без ожидания ответа абонентского устройства.

Запрос

Пример запроса
DELETE /rest/v1/user/sip/conferences/rCF-005-PhKjyX/participants/139cfa11-016e-04e2-7efe-02004c4f4f50 HTTP/1.1

Ответ

Пример успешного ответа
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "confid": "rCF-005-PhKjyX",
  "participantid": "139cfa11-016e-04e2-7efe-02004c4f4f50"
}
Пример неуспешного ответа
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "error_code": 1404,
  "error_message": "Call/Participant not found"
}

Получение текущей топологии

Возвращает текущую топологию конференции (кто кого слышит). Изначально в конференции все абоненты (участники конференции) друг друга слышат.

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

Запрос

Пример запроса
GET /rest/v1/user/sip/conferences/rCF-005-PhKjyX/topology HTTP/1.1

Ответ

Пример успешного ответа
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "from": "",
    "to": "",
    "enabled": true
  },
  {
    "from": "e846809b-0180-4b7a-aebb-7cd30a921f58",
    "to": "*",
    "enabled": false
  },
  {
    "from": "2919aaa2-0180-4b7a-d155-7cd30a921f58",
    "to": "e846809b-0180-4b7a-aebb-7cd30a921f58",
    "enabled": true
  }
]

Изменение текущей топологии

Применяет модификатор к текущей топологии конференции. Топология есть конфигурация голосовых потоков между участниками - кто кого слышит.

Изначально в конференции все абоненты (участники конференции) друг друга слышат. Такое правило неизменно и всегда присутствует в выдаче первым.

В любой момент можно установить блок от любого участника любому другому участнику. Для этого надо запостить команду на изменение топологии. За один запрос может быть применено сразу несколько команд списком. Все команды применяются последовательно.

Участники указываются через идентификаторы. Идентификаторы генерируются автоматически при поступлении звонка от абонента в конференцию и не изменяются при переводах, а также могут быть сгенерированны сервисом селекторных совещаний. Идентификаторы можно достать запросом GET '/rest/v1/uc/conferences/:id/participants', поле 'participantid'.

В качестве идентификаторов абонентов может быть указана "*", тогда на момент выполнения запроса она будет развернута в список всех абонентов, в том числе вызываемых. Однако после очередного подключения нового абонента он слышит всех, и все его слышат.

При опросе текущей топологии звездочки возвращаются только в первом элементе (он всегда присутствует) - все всех слышат.

Всякий раз применение новых правил изменяет текущую топологию с помощью слияния. Однако первое и основное правило "все всех слышат" всегда неизменно.

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

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

Запрос

Пример запроса
POST /rest/v1/user/sip/conferences/rCF-005-PhKjyX/topology HTTP/1.1

Ответ

Пример успешного ответа
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "confid": "rCF-0GB-KbQYEI"
}

См. также

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

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

  • Роль conf.

  • Роль mware.

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