User conference management (conferences)

Table of Contents

Overview
Requests
When querying from a script
See also

Overview

Manages existing active conferences through API commands (without using initiatives from SIP devices).

Management is available to any conference, including conference calls, which are also managed independently through the /rest/v1/api/selectors.

Servicing of requests is performed by the role mware.

The service is also available from scripts via the component Operation.

Requests

HTTP verb Endpoint Description

HTTP verb	Endpoint	Description
`GET`	`/rest/v1/uc/conferences`	Retrieving the list of conferences
`LOOKUP`	`/rest/v1/uc/conferences`	Search for a conference by key
`GET`	`/rest/v1/uc/conferences/<confid>`	Retrieving conference data
`DELETE`	`/rest/v1/uc/conferences/<confid>`	Wrapping up the conference
`GET`	`/rest/v1/uc/conferences/<confid>/paticipants`	Obtaining the list of conference participants
`POST`	`/rest/v1/uc/conferences/<confid>/paticipants`	Adding a participant to a conference
`GET`	`/rest/v1/uc/conferences/<confid>/paticipants/<parid>`	Obtaining participant data
`DELETE`	`/rest/v1/uc/conferences/<confid>/paticipants/<parid>`	Removal of a conference participant
`GET`	`/rest/v1/uc/conferences/<confid>/topology`	Getting the current topology
`POST`	`/rest/v1/uc/conferences/<confid>/topology`	Changing the current topology

GET

/rest/v1/uc/conferences

Retrieving the list of conferences

LOOKUP

/rest/v1/uc/conferences

Search for a conference by key

GET

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

Retrieving conference data

DELETE

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

Wrapping up the conference

GET

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

Obtaining the list of conference participants

POST

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

Adding a participant to a conference

GET

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

Obtaining participant data

DELETE

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

Removal of a conference participant

GET

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

Getting the current topology

POST

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

Changing the current topology

Retrieving the list of conferences

Returns a list of active conferences within the current domain.

A conference belongs to a domain if routing to it passes through the CAF of that domain (an entity featurecode with type conference).

Request

Table 1. Request parameters (optional)
Name	Type	Description
`filter`	`object`	Filter by field values.
`mask`	`str`	List of fields to output. Available fields for output: `confid, confroomnum, confnumber, uri, site, startts, uris`
`offset`	`int`	Offset in the list of resources to be issued.
`limit`	`int`	The maximum number of resources in the list.
`order`	`array<object\|str>`	The sort order of the resources in the list.
`flat`	`bool`	Conversion to flat form of composite fields.
`countonly`	`bool`	Returns only the number of elements.

Details about the format of GET request parameters

Request example

GET /rest/v1/uc/conferences?offset=0&limit=2 HTTP/1.1

Response

Returns a limited number of fields: confid, confroomnum, confnumber, uri, site, startts, uris. If you specify other fields in the mask, they will be ignored.

Returns a list of objects, each of which represents a separate dialog. The composition of returned fields is limited: confid, confroomnum, confnumber, uri, site, startts, uris. If you specify other fields in the mask parameter, they will be ignored.

Table 2. Conference Fields:
Field	Description
`confid`	The active conference identifier used in the formation of the endpoint. Unique in rantime, but is not globally unique and may be repeated after some time within the same system.
`confroomnum`	Conference room number. String representation of a number in decimal form. Used in conjunction with the featurecode prefix in the conference access phone number.
`confnumber`	Conference Number. String representation of a number in hexadecimal form. Used in the conference identifier `confid`.
`confuri`	String representation of the conference room URI. Format: `"<sip:conf-ROOMNUMBER@DOMAIN>"`.
`site`	The name of the site whose servers serve the conference.
`startts`	The time stamp of when the INVITE initiating SIP request arrives at the conference server. Is a representation of a point in time and can be converted to a specific date in any time zone. For example, `1571743463336`.

Response example

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

Search for a conference by key

Searches for a resource (active conference) using the specified key.

A list with identifiers of detected conferences matching the search conditions is returned.

A conference is searched for either directly or through a dialog, with one participant being the conference and the other any other participant SIP-UA.

The search fields are applied one by one in descending order of priority in the table below. Search fields contain in the description "Search value". Multiple returns are possible, for example, in the case of a search by SIP user login, if the user participates in several dialogs, each of which is connected to the conference.

Table 3. Request parameters
Parameter	Type	Description
`dialogid`	`str`	The value to search for a conference dialog. Dialog Identifier. Unique in rantime, but is not globally unique and may be repeated after some time within the same system. For example, `"rDlg-002-6FpTv2"`.
`inviteid`	`str`	The value to search for a conference dialog. Globally unique identifier of the call leading to the dialog. It is formed when an INVITE SIP request is received in the system and exists until the dialog is terminated. Present in all CDR class events callevents. For example `"660df330-0623-b465-6927-c00000000002"`.
`callid`	`str`	The value to search for a conference dialog. Call Identifier `Call-Id`. An arbitrary string value from the corresponding SIP message header of either side of the dialog. For example, `"3099649154@192.168.0.149"`.
`uri`	`str`	The value to search for a conference dialog. SIP URI: `"<sip:username@domain>"`. The value is formed on the basis of `From` or `To` headers. The search is performed only by Remote-URI of the dialog shoulders.
`from`	`str`	The value to search for a conference dialog. Phone number or login SIP user used as the `username`. Can use an additional parameter `mode`: `"number"` – search by phone number. That is, direct search by value in `username`, and also if sipuser is detected by the specified number, then search by its login in `username` `username`. `"sipuser"` – search by SIP-user name only. SIP-user with the specified login must exist, in this case search by its login in the `username`. Default `mode=number`. Dialogs are detected where one of the parties is a specified subscriber of the current domain. The search is performed similarly to `uri`, with username generated automatically. For a SIP user account, however specified, the search is performed for both the number and the login.
`sipuserid`	`str`	The value to search for a conference dialog. Account Identifier SIP-user.
`sipuserlogin`	`str`	The value to search for a conference dialog. Account login SIP-user.
`sipuserphonenumber`	`str`	The value to search for a conference dialog. Phone number of the account SIP user.
`userid`	`str`	The value to search for a conference dialog. The account ID of the user of the system. If there is a binding of SIP-user accounts to a system user, dialogs are detected, where one of these SIP users is one of the subscribers.
`confid`	`str`	Value for conference search. The conference identifier used in the formation of the endpoint. Unique in rantime, but is not globally unique and may be repeated after some time within the same system. For example, `"rDlg-002-6FpTv2"`.
`confuri`	`str`	Value for conference search. SIP URI conference rooms `"<sip:conf-ROOMNUMBER@domain>"`. The value is contained in the SIP messages of the dialog on the side associated with the conference. For example, `"<sip:conf-387@sample.domain>"`
`confroomnum`	`str`	Value for conference search. Conference room number. String representation of a number in decimal form. Used in conjunction with the featurecode prefix in the conference access phone number. For example, `"387"`
`confnumber`	`str`	Value for conference search. Conference Number. String representation of a number in hexadecimal form. Used in the conference identifier `confid`. For example, `"6FpTv2"`.

Request

Request example

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

{
  "sipuserphonenumber":"12"
}

Response

Example of a successful response

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

[
  "rCF-005-PhKjyX",
  "rCF-005-Sglne4"
]

Example of an unsuccessful response

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

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

Retrieving conference data

Returns information about the active conference.

When executing from a script and multiple matching conferences are found, the operation is applied only to the first one.

Request

Table 4. Request parameters
Name	Type	Description
`confid`	`str`	Conference ID. Passed on as part of Endpoint URI. when sending a command from a script, can be used as a parameter.
`mask`	`str`	A list of fields to output.
`flat`	`bool`	Conversion to flat form of composite fields.

Request example

GET /rest/v1/uc/conferences/rCF-005-PhKjyX HTTP/1.1

Response

Returns an object with a conference representation.

Table 5. The fields of the returned object:
Field	Description
`confid`	The active conference identifier used in the formation of the endpoint. Unique in rantime, but is not globally unique and may be repeated after some time within the same system.
`confroomnum`	Conference room number. String representation of a number in decimal form. Used in conjunction with the featurecode prefix in the conference access phone number.
`confnumber`	Conference Number. String representation of a number in hexadecimal form. Used in the conference identifier `confid`.
`confuri`	String representation of the conference room URI. Format: `"<sip:conf-ROOMNUMBER@DOMAIN>"`.
`site`	The name of the site whose servers serve the conference.
`startts`	The time stamp of when the INVITE initiating SIP request arrives at the conference server. Is a representation of a point in time and can be converted to a specific date in any time zone. For example, `1571743463336`.

Response example

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
}

Wrapping up the conference

Wraps up an active conference. The server initiates the break for all conference participants (sends a SIP request to each participant) BYE). If the conference has outgoing calls that are not completed with a 2xx-6xx final answer, a SIP request is sent to all called parties CANCEL.

The result is returned as soon as the request is placed in the conference server queue - without waiting for the conference to complete and all subscriber devices to respond.

When executing from a script and multiple matching conferences are found, the operation is applied only to the first one.

Request

Table 6. Query parameters (only for calling from scripts)
Name	Type	Description
`confid`	`str`	Conference ID. Passed on as part of Endpoint URI. when sending a command from a script, can be used as a parameter.

Request example

DELETE /rest/v1/uc/conferences/rCF-005-PhKjyX HTTP/1.1

Response

Example of a successful response

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

{
  "confid": "rCF-005-PhKjyX"
}

Example of an unsuccessful response

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

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

Obtaining the list of conference participants

Features

Returns a list of active conference participants.

When executing from a script and multiple matching conferences are found, the operation is applied only to the first one.

Request

Table 7. Request parameters
Name	Type	Description
`confid`	`str`	Conference ID. Passed on as part of Endpoint URI. when sending a command from a script, can be used as a parameter.
`filter`	`object`	Filter by field values.
`mask`	`str`	List of fields to output. Available fields for output: `confid, confroomnum, confnumber, uri, site, startts, uris`
`offset`	`int`	Offset in the list of resources to be issued.
`limit`	`int`	The maximum number of resources in the list.
`order`	`array<object\|str>`	The sort order of the resources in the list.
`flat`	`bool`	Conversion to flat form of composite fields.
`countonly`	`bool`	Returns only the number of elements.

Details about the format of GET request parameters

Request example

GET /rest/v1/uc/conferences/rCF-005-PhKjyX/participants?offset=0&limit=2 HTTP/1.1

Response

Table 8. Participant Fields:
Field	Description
`participantid`	Conference participant identifier. Used in endpoint.
`state`	Participant state. Value options: `"active"` and `"calling"`.
`callid`	Call-Id shoulder between b2b and conf. Contained in the corresponding header of the INVITE SIP request (received or sent). In the diagram: `Abonent-UA - B2BUA - CONF-UA` - Call-Id of the shoulder between the B2BUA and the CONF-UA.
`luri`	String representation of the conference URI (all participants have the same value, matching the value of the `confuri` field of the conference. In the diagram: `Abonent-UA(URI1,Tag1) - (URI2,Tag2)B2BUA(URI3,Tag3) - (URI4,Tag4)CONF-UA` is `URI4`.
`ltag`	Local tag in the URI of a conference in a dialog with a participant on the shoulder with the conference. In the diagram: `Abonent-UA(URI1,Tag1) - (URI2,Tag2)B2BUA(URI3,Tag3) - (URI4,Tag4)CONF-UA` is `Tag4`.
`ruri`	A string representation of the participant’s URI. The format is `"<sip:USERNAME@DOMAIN>"`, where `USERNAME` and `DOMAIN` strictly correspond to the values in the header. In the diagram: `Abonent-UA(URI1,Tag1) - (URI2,Tag2)B2BUA(URI3,Tag3) - (URI4,Tag4)CONF-UA` is `URI3`.
`rtag`	Tag in the URI of a subscriber in a dialog with a participant on the shoulder with a conference. In the diagram: `Abonent-UA(URI1,Tag1) - (URI2,Tag2)B2BUA(URI3,Tag3) - (URI4,Tag4)CONF-UA` is `Tag3`.

Response example

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

Adding a participant to a conference

Initiates a new call from the conference to the specified number.

The result is returned without waiting for the subscriber to respond immediately after the participant is added to the conference.

When executing from a script and multiple matching conferences are found, the operation is applied only to the first one.

Request

Table 9. Request parameters
Name	Type	Description
`confid`	`str`	Conference ID. Passed on as part of Endpoint URI. when sending a command from a script, can be used as a parameter.
`to`	`str`	Called party number.

Request example

POST /rest/v1/uc/conferences/rCF-005-PhKjyX/participants HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "to":"2216"
}

Response

Table 10. Field Description
Field	Description
`confid`	Conference ID. Duplicates the identifier from endpoint. Can be applied when executing a command from a script and specifying the conference in a different way than the identifier.
`participantid`	Call-Id initiating automatic IVR→X call (different from the CallId of the target dialog shoulders). Present in any case.

Response example

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

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

Obtaining participant data

Returns information about the conference participant.

When executing from a script and multiple matching conferences are found, the operation is applied only to the first one.

Request

Table 11. Request parameters
Name	Type	Description
`confid`	`str`	Conference ID. Passed on as part of Endpoint URI. when sending a command from a script, can be used as a parameter.
`participantid`	`str`	Conference Attendee ID. Passed on as part of Endpoint URI. when sending a command from a script, can be used as a parameter.
`mask`	`str`	A list of fields to output.
`flat`	`bool`	Conversion to flat form of composite fields.

Request example

GET /rest/v1/uc/conferences/rCF-005-PhKjyX/participants/139cfa11-016e-04e2-7efe-02004c4f4f50 HTTP/1.1

Response

Returns an object with a representation of the conference attendee.

Table 12. Participant Fields:
Field	Description
`participantid`	Conference participant identifier. Used in endpoint.
`state`	Participant state. Value options: `"active"` and `"calling"`.
`callid`	Call-Id shoulder between b2b and conf. Contained in the corresponding header of the INVITE SIP request (received or sent). In the diagram: `Abonent-UA - B2BUA - CONF-UA` - Call-Id of the shoulder between the B2BUA and the CONF-UA.
`luri`	String representation of the conference URI (all participants have the same value, matching the value of the `confuri` field of the conference. In the diagram: `Abonent-UA(URI1,Tag1) - (URI2,Tag2)B2BUA(URI3,Tag3) - (URI4,Tag4)CONF-UA` is `URI4`.
`ltag`	Local tag in the URI of a conference in a dialog with a participant on the shoulder with the conference. In the diagram: `Abonent-UA(URI1,Tag1) - (URI2,Tag2)B2BUA(URI3,Tag3) - (URI4,Tag4)CONF-UA` is `Tag4`.
`ruri`	A string representation of the participant’s URI. The format is `"<sip:USERNAME@DOMAIN>"`, where `USERNAME` and `DOMAIN` strictly correspond to the values in the header. In the diagram: `Abonent-UA(URI1,Tag1) - (URI2,Tag2)B2BUA(URI3,Tag3) - (URI4,Tag4)CONF-UA` is `URI3`.
`rtag`	Tag in the URI of a subscriber in a dialog with a participant on the shoulder with a conference. In the diagram: `Abonent-UA(URI1,Tag1) - (URI2,Tag2)B2BUA(URI3,Tag3) - (URI4,Tag4)CONF-UA` is `Tag3`.

Response example

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

Removal of a conference participant

Excludes the participant from the conference, as a result of which a SIP-request is sent to the subscriber BYE.

The result is returned immediately after the request is placed in the conference server queue - without waiting for the subscriber device to respond.

When executing from a script and multiple matching conferences are found, the operation is applied only to the first one.

Request

Table 13. Query parameters (only for calling from scripts)
Name	Type	Description
`confid`	`str`	Conference ID. Passed on as part of Endpoint URI. when sending a command from a script, can be used as a parameter.

Request example

DELETE /rest/v1/uc/conferences/rCF-005-PhKjyX/participants/139cfa11-016e-04e2-7efe-02004c4f4f50 HTTP/1.1

Response

Example of a successful response

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

{
  "confid": "rCF-005-PhKjyX",
  "participantid": "139cfa11-016e-04e2-7efe-02004c4f4f50"
}

Example of an unsuccessful response

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

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

Getting the current topology

Returns the current conference topology (who can hear who). Initially in a conference, all subscribers (conference participants) can hear each other.

When executing from a script and multiple matching conferences are found, the operation is applied only to the first one.

Request

Table 14. Query parameters (only for calling from scripts)
Name	Type	Description
`confid`	`str`	Conference ID. Passed on as part of Endpoint URI. when sending a command from a script, can be used as a parameter.

Request example

GET /rest/v1/uc/conferences/rCF-005-PhKjyX/topology HTTP/1.1

Response

Example of a successful response

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

Changing the current topology

Applies the modifier to the current conference topology. Topology is the configuration of voice streams between participants - who can hear whom.

Initially in a conference, all subscribers (conference participants) can hear each other. This rule is invariable and always present in the output first.

A block can be set from any participant to any other participant at any time. To do this, you must post a command to change the topology. Several commands in a list can be applied in one request. All commands are applied sequentially.

Participants are specified through identifiers. Identifiers are generated automatically when a call is received from a subscriber to the conference and do not change during transfers, and can also be generated by the conference call service. Identifiers can be retrieved by GET request '/rest/v1/uc/conferences/:id/participants', field 'participantid'.

"*" can be specified as subscriber IDs, then it will be expanded to a list of all subscribers, including called subscribers, at the time the request is executed. However, after another new subscriber joins, he hears everyone, and everyone hears him.

When polling the current topology, asterisks are returned only in the first element (it is always present) - everyone hears everyone.

Whenever new rules are applied, the current topology is modified by merging. However, the first and basic rule "everybody hears everybody" is always the same.

Controlled selector meeting topology management is inconsistent with selector meeting logic, and is a lower-level mechanism that can entail incorrect data in the selector meeting management application.

When executing from a script and multiple matching conferences are found, the operation is applied only to the first one.

Request

Table 15. Query parameters (only for calling from scripts)
Name	Type	Description
`confid`	`str`	Conference ID. Passed on as part of Endpoint URI. when sending a command from a script, can be used as a parameter.
`setup`	`array<object>`	Topology modification commands { from::string(), to::string(), enabled::boolean() }

Request example

POST /rest/v1/uc/conferences/rCF-005-PhKjyX/topology HTTP/1.1

Response

Example of a successful response

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

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

When querying from a script

When executing commands from a script by component Operation, the target conference identifier should be passed among the request parameters.

When executing a request from a script, you can point to the target conference in a number of ways - listed below in descending order of priority with a brief description. For details, see the parameters of the conference lookup operation.

Through specifying a dialog, one side of which is the target conference:
- dialogid – by dialog identifier.
- inviteid – by the identifier of the call leading to the dialog.
- callid – by the Call-Id identifier of one of the dialog’s arms.
- uri – by the URI of one of the participants in the dialog: "<sip:username@domain>".
- from – by phone number or SIP-user login. The optional parameter mode is used: "number" or "sipuser".
- sipuserid – by SIP user account ID.
- sipuserlogin – by SIP user account login.
- sipuserphonenumber – by the phone number of the SIP user account.
- userid – by the system user account ID.
Through the direct instruction of the conference:
- confid – by conference ID.
- confroomnum – by conference room number.
- confnumber – by conference access telephone number containing the prefix featurecode.

User conference management (conferences)

Overview

Requests

Retrieving the list of conferences

Request

Response

Search for a conference by key

Request

Response

Retrieving conference data

Request

Response

Wrapping up the conference

Request

Response

Obtaining the list of conference participants

Features

Request

Response

Adding a participant to a conference

Request

Response

Obtaining participant data

Request

Response

Removal of a conference participant

Request

Response

Getting the current topology

Request

Response

Changing the current topology

Request

Response

When querying from a script

See also