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

Обзор

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

Управлению доступны любые конференции, в том числе и селекторные совещания, управление которыми производится также независимо через /rest/v1/api/selectors.

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

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

Запросы

HTTP verb Endpoint Описание

GET

/rest/v1/uc/conferences

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

LOOKUP

/rest/v1/uc/conferences

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

GET

/rest/v1/uc/conferences/<confid>

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

DELETE

/rest/v1/uc/conferences/<confid>

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

GET

/rest/v1/uc/conferences/<confid>/paticipants

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

POST

/rest/v1/uc/conferences/<confid>/paticipants

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

GET

/rest/v1/uc/conferences/<confid>/paticipants/<parid>

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

DELETE

/rest/v1/uc/conferences/<confid>/paticipants/<parid>

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

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

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

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

Запрос

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/uc/conferences?offset=0&limit=2 HTTP/1.1
Пример запроса списка видио конференций с помощью curl
curl -vvv -b ~/.curl-cookie http://oktell.studio/rest/v1/uc/conferences\?filter\='\{"conftype":"videoconference"\}'

Ответ

Возвращает ограниченное количество полей: 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> или "<sip:vconf-ROOMNUMBER@DOMAIN>.

conftype

Строковый. Тип конференции. Может быть "videoconference" или "conference".

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.okteller.ru>",
    "site": "SITE1",
    "startts": 1572033454296
  },
  {
    "confid": "rCF-005-Sglne4",
    "confnumber": "Sglne4",
    "confroomnum": "99652",
    "confuri": "<sip:conf-99652@test.okteller.ru>",
    "site": "SITE1",
    "startts": 1572036671705
  }
]

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

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

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

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

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

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/uc/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",
  "rCF-005-Sglne4"
]
Пример неуспешного ответа
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

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

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

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

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

Запрос

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

confid

str

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

Передается как часть Endpoint URI. В качестве параметра может использоваться при отправке команды из сценария.

mask

str

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

flat

bool

Преобразование в плоский вид составных полей.
Пример запроса
GET /rest/v1/uc/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.okteller.ru>",
  "site": "SITE1",
  "startts": 1572033454296
}

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

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

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

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

Запрос

Table 6. Параметры запроса (только для вызова из сценариев)
Имя Тип Описание

confid

str

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

Передается как часть Endpoint URI. В качестве параметра может использоваться при отправке команды из сценария.
Пример запроса
DELETE /rest/v1/uc/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 7. Параметры запроса
Имя Тип Описание

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/uc/conferences/rCF-005-PhKjyX/participants?offset=0&limit=2 HTTP/1.1

Ответ

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

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.okteller.ru>",
    "ltag": "rCF-005-9aGAQr",
    "ruri": "<sip:13@test.okteller.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.okteller.ru>",
    "ltag": "rCF-005-AHoiiQ",
    "ruri": "<sip:11@test.okteller.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.okteller.ru>",
    "ltag": "rCF-005-CZ0Jjl",
    "ruri": "<sip:12@test.okteller.ru>",
    "rtag": "rB2-002-aoMh"
  }
]

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

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

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

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

Запрос

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

confid

str

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

Передается как часть Endpoint URI. В качестве параметра может использоваться при отправке команды из сценария.

to

str

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

{
  "to":"2216"
}

Ответ

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

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

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

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

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

Запрос

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

confid

str

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

Передается как часть Endpoint URI. В качестве параметра может использоваться при отправке команды из сценария.

participantid

str

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

Передается как часть Endpoint URI. В качестве параметра может использоваться при отправке команды из сценария.

mask

str

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

flat

bool

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

Ответ

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

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

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.okteller.ru>",
  "ltag": "rCF-005-9aGAQr",
  "ruri": "<sip:13@test.okteller.ru>",
  "rtag": "rB2-002-ARuy"
}

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

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

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

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

Запрос

Table 13. Параметры запроса (только для вызова из сценариев)
Имя Тип Описание

confid

str

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

Передается как часть Endpoint URI. В качестве параметра может использоваться при отправке команды из сценария.
Пример запроса
DELETE /rest/v1/uc/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"
}

При запросе из сценария

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

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

  • Через указание диалога, одной из сторон которого является целевая конференция:

    • dialogid – по идентификатору диалога.

    • inviteid – по идентификатор вызова, приводящего к диалогу.

    • callid – по идентификатору Call-Id одного из плечей диалога.

    • uri – по URI одного из участников диалога: "<sip:username@domain>".

    • from – по номеру телефона или логину SIP-пользователя. Используется дополнительный параметр mode: "number" или "sipuser".

    • sipuserid – по идентификатору учетной записи SIP-пользователя.

    • sipuserlogin – по логину учетной записи SIP-пользователя.

    • sipuserphonenumber – по номеру телефона учетной записи SIP-пользователя.

    • userid – по идентификатор учетной записи пользователя системы.

  • Через непосредственное указание конференции:

    • confid – по идентификатору конференции.

    • confroomnum – по номеру конференц-комнаты.

    • confnumber – по телефонному номеру доступа в конференцию, содержащему префикс featurecode.

См. также

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

  • API /rest/v1/uc/calls для управления произвольными звонками домена.

  • Компонент сценариев Операция.

  • Функциональная роль conf.

  • Функциональная роль mware.

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