Managing your conferences (conferences)
- Overview
- Requests
- Retrieving the list of conferences
- Search for a conference by key
- Retrieving conference data
- Wrapping up the conference
- Obtaining the list of conference participants
- Adding a participant to a conference
- Obtaining participant data
- Removal of a conference participant
- Getting the current topology
- Changing the current topology
- See also
Overview
Manages existing active conferences through API commands (without using initiatives from SIP devices).
Management is available to any conference except for conference calls, which are managed by the /rest/v1/api/selectors. Unlike the /rest/v1/uc/conferences API, the current endpoint only provides access to conferences where one of the participants is the SIP-user account, belonging to the user who is making the API request.
Servicing of requests is performed by the role mware.
Requests
| HTTP verb | Endpoint | Description |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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).
The result of the query execution undergoes additional filtering. Only conferences in which one of the participants is an authorized user (through any of the accounts belonging to the user) are returned sipuser).
Request
| Name | Type | Description |
|---|---|---|
|
|
Filter by field values. |
|
|
List of fields to output. Available fields for output: |
|
|
Offset in the list of resources to be issued. |
|
|
The maximum number of resources in the list. |
|
|
The sort order of the resources in the list. |
|
|
Conversion to flat form of composite fields. |
|
|
Returns only the number of elements. |
GET /rest/v1/user/sip/conferences?offset=0&limit=2 HTTP/1.1Response
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.
| Field | Description |
|---|---|
|
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. |
|
Conference room number. String representation of a number in decimal form. Used in conjunction with the featurecode prefix in the conference access phone number. |
|
Conference Number. String representation of a number in hexadecimal form.
Used in the conference identifier |
|
String representation of the conference room URI. Format: |
|
The name of the site whose servers serve the conference. |
|
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, |
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
}
]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.
The result of the query execution undergoes additional filtering. Only conferences where one of the participants is an authorized user (through any of the user accounts belonging to the user) are detected sipuser).
| Parameter | Type | Description |
|---|---|---|
|
|
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, |
|
|
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 |
|
|
The value to search for a conference dialog. Call Identifier For example, |
|
|
The value to search for a conference dialog. SIP URI: |
|
|
The value to search for a conference dialog. Phone number or login SIP user used as the Can use an additional parameter
Default Dialogs are detected where one of the parties is a specified subscriber of the current domain.
The search is performed similarly to |
|
|
The value to search for a conference dialog. Account Identifier SIP-user. |
|
|
The value to search for a conference dialog. Account login SIP-user. |
|
|
The value to search for a conference dialog. Phone number of the account SIP user. |
|
|
|
|
|
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, |
|
|
Value for conference search. SIP URI conference rooms For example, |
|
|
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, |
|
|
Value for conference search. Conference Number. String representation of a number in hexadecimal form.
Used in the conference identifier For example, |
Retrieving conference data
Returns information about the active conference.
The request is pre-filtered. To be allowed to execute, the specified conference must have an authorized user as one of its participants (through any of the accounts belonging to the user) sipuser).
Request
| Name | Type | Description |
|---|---|---|
|
|
Conference ID. Passed on as part of Endpoint URI. |
|
|
A list of fields to output. |
|
|
Conversion to flat form of composite fields. |
GET /rest/v1/user/sip/conferences/rCF-005-PhKjyX HTTP/1.1Response
Returns an object with a conference representation.
| Field | Description |
|---|---|
|
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. |
|
Conference room number. String representation of a number in decimal form. Used in conjunction with the featurecode prefix in the conference access phone number. |
|
Conference Number. String representation of a number in hexadecimal form.
Used in the conference identifier |
|
String representation of the conference room URI. Format: |
|
The name of the site whose servers serve the conference. |
|
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, |
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.
Response
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"
}Obtaining the list of conference participants
Request
| Name | Type | Description |
|---|---|---|
|
|
Conference ID. Passed on as part of Endpoint URI. |
|
|
Filter by field values. |
|
|
List of fields to output. Available fields for output: |
|
|
Offset in the list of resources to be issued. |
|
|
The maximum number of resources in the list. |
|
|
The sort order of the resources in the list. |
|
|
Conversion to flat form of composite fields. |
|
|
Returns only the number of elements. |
GET /rest/v1/user/sip/conferences/rCF-005-PhKjyX/participants?offset=0&limit=2 HTTP/1.1Response
| Field | Description |
|---|---|
|
Conference participant identifier. Used in endpoint. |
|
Participant state. Value options: |
|
Call-Id shoulder between b2b and conf. Contained in the corresponding header of the INVITE SIP request (received or sent). In the diagram: |
|
String representation of the conference URI (all participants have the same value, matching the value of the In the diagram: |
|
Local tag in the URI of a conference in a dialog with a participant on the shoulder with the conference. In the diagram: |
|
A string representation of the participant’s URI. The format is In the diagram: |
|
Tag in the URI of a subscriber in a dialog with a participant on the shoulder with a conference. In the diagram: |
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.
Request
| Name | Type | Description |
|---|---|---|
|
|
Conference ID. Passed on as part of Endpoint URI. |
|
|
Called party number. |
POST /rest/v1/user/sip/conferences/rCF-005-PhKjyX/participants HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"to":"2216"
}Response
| Field | Description |
|---|---|
|
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. |
|
Call-Id initiating automatic IVR→X call (different from the CallId of the target dialog shoulders). Present in any case. |
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.
The request is pre-filtered. To be allowed to execute, the specified conference must have an authorized user as one of its participants (through any of the accounts belonging to the user) sipuser).
Request
| Name | Type | Description |
|---|---|---|
|
|
Conference ID. Passed on as part of Endpoint URI. |
|
|
Conference Attendee ID. Passed on as part of Endpoint URI. |
|
|
A list of fields to output. |
|
|
Conversion to flat form of composite fields. |
GET /rest/v1/user/sip/conferences/rCF-005-PhKjyX/participants/139cfa11-016e-04e2-7efe-02004c4f4f50 HTTP/1.1Response
Returns an object with a representation of the conference attendee.
| Field | Description |
|---|---|
|
Conference participant identifier. Used in endpoint. |
|
Participant state. Value options: |
|
Call-Id shoulder between b2b and conf. Contained in the corresponding header of the INVITE SIP request (received or sent). In the diagram: |
|
String representation of the conference URI (all participants have the same value, matching the value of the In the diagram: |
|
Local tag in the URI of a conference in a dialog with a participant on the shoulder with the conference. In the diagram: |
|
A string representation of the participant’s URI. The format is In the diagram: |
|
Tag in the URI of a subscriber in a dialog with a participant on the shoulder with a conference. In the diagram: |
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.
Request
DELETE /rest/v1/user/sip/conferences/rCF-005-PhKjyX/participants/139cfa11-016e-04e2-7efe-02004c4f4f50 HTTP/1.1Response
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"
}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.
The request is pre-filtered. To be allowed to execute, the specified conference must have an authorized user as one of its participants (through any of the accounts belonging to the user) sipuser).
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.
The request is pre-filtered. To be allowed to execute, the specified conference must have an authorized user as one of its participants (through any of the accounts belonging to the user) sipuser).
See also
-
API /rest/v1/uc/conferences with access to arbitrary conferences in the domain without user restrictions.
-
API /rest/v1/uc/calls_by_participation to manage a limited set of domain calls involving an authorized user.
-
role conf.
-
role mware.