Managing your conferences (conferences_by_participation)

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

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).

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

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.

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).

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.

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

Table 4. Request parameters
Name Type Description

confid

str

Conference ID.

Passed on as part of Endpoint URI.

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.

Request

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.

Request

Table 6. Request parameters
Name Type Description

confid

str

Conference ID.

Passed on as part of Endpoint URI.

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 7. 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.

Request

Table 8. Request parameters
Name Type Description

confid

str

Conference ID.

Passed on as part of Endpoint URI.

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 9. 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.

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

Table 10. Request parameters
Name Type Description

confid

str

Conference ID.

Passed on as part of Endpoint URI.

participantid

str

Conference Attendee ID.

Passed on as part of Endpoint URI.

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 11. 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.

Request

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.

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

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.

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

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

See also

  • Personalization
  • Increase font size
  • Decrease font size