Managing own conferences (conferences)
- Overview
- Requests
- Getting the list of conferences
- Searching for a conference by key
- Getting conference data
- Terminating the conference
- Getting the list of conference participants
- Adding a participant to the conference
- Getting participant data
- Removing a conference participant
- Getting the current topology
- Modifying the current topology
- See also
Overview
Manages existing active conferences via API commands (without initiatives from SIP devices).
Any conferences are available for management except selector meetings, which are managed via /rest/v1/api/selectors. Unlike the /rest/v1/uc/conferences API, the current endpoint provides access only to conferences where one participant is an SIP user account belonging to the user who executes the API request.
Requests are serviced by the mware role.
Requests
| HTTP verb | Endpoint | Description |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Getting the list of conferences
Returns the list of active conferences within the current domain.
A conference belongs to a domain if routing to it passes through a feature code of this domain (the featurecode entity with type conference).
The request result undergoes additional filtering. Only conferences where the authorized user is one of the participants (through any of their sipuser accounts) are returned.
Request
| Name | Type | Description |
|---|---|---|
|
|
Filter by field values. |
|
|
List of fields to output. Available fields for output: |
|
|
Offset in the list of resources to output. |
|
|
Maximum number of resources in the list. |
|
|
Sorting order of resources in the list. |
|
|
Transformation of composite fields to flat form. |
|
|
Return only the number of elements. |
GET /rest/v1/user/sip/conferences?offset=0&limit=2 HTTP/1.1
Response
Returns a limited number of fields: confid, confroomnum, confnumber, uri, site, startts, uris. If other fields are specified in mask, they are ignored.
Returns a list of objects, each representing a separate dialog. The returned field composition is limited: confid, confroomnum, confnumber, uri, site, startts, uris.
If other fields are specified in the mask parameter, they are ignored.
| Field | Description |
|---|---|
|
Active conference identifier used when forming the endpoint. Unique at runtime, but not globally unique and may repeat after some time within the same system. |
|
Conference room number. String representation of the number in decimal form. Used together with the featurecode prefix in the telephone number for conference access. |
|
Conference number. String representation of the number in hexadecimal form.
Used in the conference identifier |
|
String representation of the conference room URI. Format: |
|
Name of the site whose servers serve the conference. |
|
Timestamp of when the initiating SIP INVITE request arrived at the conference server. It 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
}
]
Searching for a conference by key
Searches for a resource (active conference) by the specified key.
Returns a list with identifiers of discovered conferences matching the search conditions.
A conference is searched either directly or through a dialog in which one party is the conference and the other is any other SIP-UA.
Search fields are applied one at a time in descending priority order in the table below. Search fields contain a "Value for search" description. Multiple results are possible, for example when searching by SIP user login if the user participates in several dialogs, each connected to a conference.
The request result undergoes additional filtering. Only conferences where the authorized user is one of the participants (through any of their sipuser accounts) are discovered.
| Parameter | Type | Description |
|---|---|---|
|
|
Value for searching a dialog with a conference. Dialog identifier. Unique at runtime, but not globally unique and may repeat after some time within the same system. For example, |
|
|
Value for searching a dialog with a conference. Globally unique identifier of the call leading to the dialog. Formed when a SIP INVITE request arrives at the system and exists until the dialog ends. Present in all CDR events of the callevents class. For example |
|
|
Value for searching a dialog with a conference. Call identifier For example, |
|
|
Value for searching a dialog with a conference. SIP URI: |
|
|
Value for searching a dialog with a conference. Telephone number or SIP user login used as An additional
Default Dialogs are discovered where one party is the specified subscriber of the current domain.
Search is performed similarly to |
|
|
Value for searching a dialog with a conference. SIP user account identifier. |
|
|
Value for searching a dialog with a conference. SIP user account login. |
|
|
Value for searching a dialog with a conference. SIP user account telephone number. |
|
|
|
|
|
Value for searching a conference. Conference identifier used when forming the endpoint. Unique at runtime, but not globally unique and may repeat after some time within the same system. For example, |
|
|
Value for searching a conference. Conference room SIP URI For example, |
|
|
Value for searching a conference. Conference room number. String representation of the number in decimal form. Used together with the featurecode prefix in the telephone number for conference access. For example, |
|
|
Value for searching a conference. Conference number. String representation of the number in hexadecimal form.
Used in the conference identifier For example, |
Getting conference data
Returns information about the active conference.
The request undergoes preliminary filtering. To be allowed, the specified conference must have the authorized user as one of the participants (through any of their sipuser accounts).
Request
| Name | Type | Description |
|---|---|---|
|
|
Conference identifier. Passed as part of the Endpoint URI. |
|
|
List of fields to output. |
|
|
Transformation of composite fields to flat form. |
GET /rest/v1/user/sip/conferences/rCF-005-PhKjyX HTTP/1.1
Response
Returns an object with the conference representation.
| Field | Description |
|---|---|
|
Active conference identifier used when forming the endpoint. Unique at runtime, but not globally unique and may repeat after some time within the same system. |
|
Conference room number. String representation of the number in decimal form. Used together with the featurecode prefix in the telephone number for conference access. |
|
Conference number. String representation of the number in hexadecimal form.
Used in the conference identifier |
|
String representation of the conference room URI. Format: |
|
Name of the site whose servers serve the conference. |
|
Timestamp of when the initiating SIP INVITE request arrived at the conference server. It 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
}
Terminating the conference
Terminates the active conference.
The server initiates the disconnect for all conference participants (sends a SIP BYE request to each).
If the conference has outgoing calls not completed by a final 2xx-6xx response, a SIP CANCEL request is sent to all called subscribers.
The result is returned immediately after the request is placed in the conference server queue — without waiting for conference termination and responses from all subscriber devices.
Getting the list of conference participants
Request
| Name | Type | Description |
|---|---|---|
|
|
Conference identifier. Passed as part of the Endpoint URI. |
|
|
Filter by field values. |
|
|
List of fields to output. Available fields for output: |
|
|
Offset in the list of resources to output. |
|
|
Maximum number of resources in the list. |
|
|
Sorting order of resources in the list. |
|
|
Transformation of composite fields to flat form. |
|
|
Return only the number of elements. |
GET /rest/v1/user/sip/conferences/rCF-005-PhKjyX/participants?offset=0&limit=2 HTTP/1.1
Response
| Field | Description |
|---|---|
|
Conference participant identifier. Used in the endpoint. |
|
Participant state. Value variants: |
|
Call-Id of the leg between b2b and conf. Contained in the corresponding SIP INVITE request header (received or sent). In the diagram: |
|
String representation of the conference URI (the same value for all participants, matching the conference In the diagram: |
|
Local tag in the conference URI in the dialog with the participant on the conference leg. In the diagram: |
|
String representation of the participant URI. Format: In the diagram: |
|
Tag in the subscriber URI in the dialog with the participant on the conference leg. 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 the conference
Initiates a new call from the conference to the specified number.
The result is returned without waiting for the subscriber’s answer, immediately after adding the participant to the conference.
Request
| Name | Type | Description |
|---|---|---|
|
|
Conference identifier. Passed as part of the Endpoint URI. |
|
|
Called subscriber 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 identifier. Duplicates the identifier from the endpoint. Can be used when executing a command from a script and specifying the conference in a way other than the identifier. |
|
Call-Id of the initiating automatic IVR→X call (differs from the CallId of the target dialog legs). 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"
}
Getting participant data
Returns information about a conference participant.
The request undergoes preliminary filtering. To be allowed, the specified conference must have the authorized user as one of the participants (through any of their sipuser accounts).
Request
| Name | Type | Description |
|---|---|---|
|
|
Conference identifier. Passed as part of the Endpoint URI. |
|
|
Conference participant identifier. Passed as part of the Endpoint URI. |
|
|
List of fields to output. |
|
|
Transformation of composite fields to flat form. |
GET /rest/v1/user/sip/conferences/rCF-005-PhKjyX/participants/139cfa11-016e-04e2-7efe-02004c4f4f50 HTTP/1.1
Response
Returns an object with the conference participant representation.
| Field | Description |
|---|---|
|
Conference participant identifier. Used in the endpoint. |
|
Participant state. Value variants: |
|
Call-Id of the leg between b2b and conf. Contained in the corresponding SIP INVITE request header (received or sent). In the diagram: |
|
String representation of the conference URI (the same value for all participants, matching the conference In the diagram: |
|
Local tag in the conference URI in the dialog with the participant on the conference leg. In the diagram: |
|
String representation of the participant URI. Format: In the diagram: |
|
Tag in the subscriber URI in the dialog with the participant on the conference leg. 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"
}
Removing a conference participant
Removes the participant from the conference, as a result of which a SIP BYE request is sent to the subscriber.
The result is returned immediately after the request is placed in the conference server queue — without waiting for a response from the subscriber device.
Request
DELETE /rest/v1/user/sip/conferences/rCF-005-PhKjyX/participants/139cfa11-016e-04e2-7efe-02004c4f4f50 HTTP/1.1
Response
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 hears whom). Initially, in a conference all subscribers (conference participants) hear each other.
The request undergoes preliminary filtering. To be allowed, the specified conference must have the authorized user as one of the participants (through any of their sipuser accounts).
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
}
]
Modifying the current topology
Applies a modifier to the current conference topology. The topology is the configuration of voice streams between participants — who hears whom.
Initially, in a conference all subscribers (conference participants) hear each other. This rule is immutable and always present first in the output.
At any moment a block can be set from any participant to any other participant. To do this, post a topology change command. Several commands can be applied at once in one request as a list. All commands are applied sequentially.
Participants are specified by identifiers. Identifiers are generated automatically when a call from a subscriber arrives at the conference and do not change during transfers; they can also be generated by the selector meeting service. Identifiers can be obtained with the GET request '/rest/v1/uc/conferences/:id/participants', field 'participantid'.
The subscriber identifier "*" may be specified, in which case at the time of request execution it is expanded to the list of all subscribers, including called ones. However, after the next new subscriber connects, they hear everyone and everyone hears them.
When polling the current topology, asterisks are returned only in the first element (it is always present) — everyone hears everyone.
Each application of new rules changes the current topology by merging. However, the first and main rule "everyone hears everyone" is always immutable.
Topology management of managed selector meetings is inconsistent with selector meeting logic and is a lower-level mechanism capable of causing incorrect data in the selector meeting management application.
The request undergoes preliminary filtering. To be allowed, the specified conference must have the authorized user as one of the participants (through any of their sipuser accounts).
See also
-
API /rest/v1/uc/conferences with access to arbitrary domain conferences without user restrictions.
-
API /rest/v1/uc/calls_by_participation for managing a limited set of domain calls involving the authorized user.
-
conf role.
-
mware role.