Managing your calls (calls_by_participation)
- Overview
- Requests
- Retrieving a list of calls (GET)
- Initiating a new call (POST)
- Initiating a new call (INVITE)
- Searching for call ID (LOOKUP)
- Receiving information about the call (GET)
- Transferring a call to a number (REFER)
- Transferring a spoofed call (REFERREPLACES)
- Converting a call to a conference (SWITCHCONF)
- Transferring a call to a conference (REFERCONF)
- Sending a device control event to one of the parties (NOTIFY)
- Sending a DTMF character to one of the parties (SEND_DTMF)
- Start/stop stenography of a party’s speech (SETUP_ASR)
- Start/stop (add/remove) a dialog recording channel (SETUP_RECORD)
- Managing dialog labels (SETUP_BINDINGS)
- Ending a call (DELETE)
- See also
Overview
Manages existing active calls (B2B dialogs) through API commands (without using initiatives from SIP devices).
Any calls are available for management: initiated both via API and from SIP devices and services SIP-UA. Unlike the /rest/v1/uc/calls API, the current endpoint grants access only to conversations 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.
The role is required for the job callstore.
Requests
| HTTP verb | Endpoint | Description |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Sending a device control event to one of the parties (NOTIFY) |
|
|
|
|
|
|
|
|
Start/stop (add/remove) a dialog recording channel (SETUP_RECORD) |
|
|
|
|
|
Retrieving a list of calls (GET)
Returns a list of active dialogs within the current domain.
Any dialog has two parties: the calling party (A) and the called party (B). There may be one or more subscribers representing the `B' side, depending on the state of the dialog.
A dialog belongs to a domain if at least one of its subscribers (dialog arms) belongs to the domain (is a provider account, a SIP user, a conference, or a script) IVR).
The result of the query execution undergoes additional filtering. Only those dialogs, one of the participants of which is an authorized user (through any of the accounts belonging to him/her) 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/uc/calls_by_participation?offset=0&limit=1 HTTP/1.1Response
Returns a list of objects, each of which represents a separate dialog. The composition of returned fields is limited: acallid, callids, dialogid, esgdlg, esgcallid, inviteid, status, legs, localuri, remoteuri, site, startts, uris, opts.
If you specify other fields in the mask parameter, they will be ignored.
| Field | Description |
|---|---|
|
Call-Id of the initiating side of the dialog. Contained in the corresponding header of the initiating SIP request INVITE. |
|
A list of all Call-Id’s of active dialog participants. Each side of the dialog has its own Call-Id, each called fork has a unique Call-Id. |
|
Active dialog 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. |
|
Role dialog identifier esg. Has a non-empty value only if the dialog is created based on an external incoming call from the provider’s account. Can be used as an external caller service session identifier, since the esg dialog is not changed during call transfer. |
|
CallId an external caller hidden behind the role esg. Has a non-empty value only if the dialog is created based on an external incoming call from the provider’s account. |
|
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. |
|
The general state of the dialog. Value options:
In fact, the dialog state machine has many more states, but they all fit into the general states. |
|
List of dialog shoulders.
Each dialog always has exactly one initiator (calling party
In the general state
Each element of the list is object. |
|
String representation of the URI from the The format is |
|
String representation of the URI from the The format is |
|
The name of the site whose servers serve the dialog. |
|
Timestamp of the time the initiating SIP request INVITE arrives in the system. Is a representation of a point in time and can be converted to a specific date in any time zone. For example, |
|
A list of all URIs involved in the call. Each SIP user that is a subscriber to a dialog has two URIs, one specified via |
|
An object with additional dialog parameters. Contains:
|
| Field | Description |
|---|---|
|
Call-Id shoulder. Contained in the corresponding header of the INVITE SIP request (received or sent). |
|
Limits the call time of the caller in milliseconds. Valid only for the shoulder side |
|
String representation local URI. For the shoulder of side The format is |
|
String representation remote URI. For arm side The format is |
|
Code side of the dialog:
|
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[
{
"acallid": "3113017065@192.168.0.149",
"callids": [
"rB2-002-484FD3-01-3113017065@192.168.0.149",
"3113017065@192.168.0.149"
],
"dialogid": "rDlg-002-484FD3",
"esgdlg": "",
"esgcallid": "",
"inviteid": "357924f1-0623-b685-c105-b80000000002",
"legs": [
{
"callid": "3113017065@192.168.0.149",
"expirets": "undefined",
"localuri": "<sip:sip3@test.rootdomain.ru>",
"remoteuri": "<sip:sip2@test.rootdomain.ru>",
"side": "a"
},
{
"callid": "rB2-002-484FD3-01-3113017065@192.168.0.149",
"expirets": 30000,
"localuri": "<sip:12@test.rootdomain.ru>",
"remoteuri": "<sip:sip3@test.rootdomain.ru>",
"side": "b"
}
],
"localuri": "<sip:sip3@test.rootdomain.ru>",
"opts": {
"referred-by": "<sip:sip1@test.rootdomain.ru>"
},
"remoteuri": "<sip:sip2@test.rootdomain.ru>",
"site": "SITE1",
"startts": 1571747612067,
"status": "forking",
"uris": [
"<sip:12@test.rootdomain.ru>",
"<sip:sip3@test.rootdomain.ru>",
"<sip:sip3@test.rootdomain.ru>",
"<sip:sip2@test.rootdomain.ru>"
]
}
]Initiating a new call (POST)
Initiates an intercom call to subscriber X (number in the from field), after answering it transfers it (SIP REFER request) to subscriber Y (number in the from field) to).
To initiate intercom-call mode, a featurecode of the appropriate type must exist in the system and be available in the routing for at least the subscribers towards themselves as well as the subscriber 100 (callmanager).
The operation is carried out by running a hidden service script that performs a prepared call to the initiator
(script component Outgoing call)
with transfer of control to a specially prepared hidden IVR script with the component Transfer to number.
The specified number is substituted as the number to be transferred to.
Process Flowchart: IVR→X, IVR REFER Y, X→Y.
The request is executed asynchronously. The response to the request is returned at the moment defined by the parameter response_mode.
The context of the call initiation process is gradually populated with call data as the call progresses.
The data content of the response corresponds to when it is returned - the later point in the process is selected, the more data and the more accurate the result.
CDR events of the target call can be retrieved from the system’s event subscription interface.
The subscriber, on whose behalf an outgoing call is ordered, after picking up the handset hears all the KPV signals of the organized outgoing call.
The request is pre-filtered. An authorized user must be the initiator of the new call to be allowed to execute. That is, the specified value of the "from" parameter referred to an authorized user (via any of the accounts owned by the user) sipuser).
Request
| Name | Type | Description | ||
|---|---|---|---|---|
|
|
The mode of specifying the X side of the initiator of the call to be created. Possible options:
|
||
|
|
Depending on the mode ( |
||
|
|
Called party number Y. Allows the characters “'” and “,” to be specified. The first such character allocates the remaining sequence as a DTMF pre-dial after the response is received, and each subsequent such character provides a 1-second pause in the set DTMF. |
||
|
|
The number of the initiator of the first call. Displayed to subscriber X. The default value of the |
||
|
|
The name of the initiator of the first call. Default |
||
|
|
Timeout of the first call in seconds. This is a limitation of the default call time. The default is 30 sec. |
||
|
|
A label attached to the call. Not assigned by default. |
||
|
|
Response return mode. The larger the value, the later the response is sent, and the more contextual information the response contains. Possible options:
Default |
||
|
|
Switches the intercom mode for calling a subscriber. The default setting is off.
|
POST /rest/v1/uc/calls_by_participation HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"from": "14",
"to": "16",
"mode": "number",
"callerid": "100",
"callername": "callmanager",
"calltimeout": 30,
"use_intercom": true,
"binding": "sample_binding",
"response_mode": 5
}Response
| Field | Description |
|---|---|
|
The final result of the operation. Value options. |
|
Call-Id initiating automatic IVR→X call (different from the CallId of the target dialog shoulders). Present in any case. |
|
Call-Id call received in the system from subscriber X to subscriber Y after processing SIP REFER request. This is the Call-Id of the |
|
Response-Line the last received response from subscriber Y, based on the results of which a response to the request is generated. In case of some unsuccessful results of the operation, it may be absent. |
|
The identifier of the target X→Y dialog. It may be absent in case of some unsuccessful results of the operation. It may also be absent if the dialog duration is 0 seconds. |
| Significance | Description |
|---|---|
|
The response is generated at a stage where no problems are identified to successfully create an X→Y dialog. For example, for
|
|
The IVR→X call failed ( In case an unsuccessful response is received from subscriber X, the result does not contain information about the dialog X→Y, the fields |
|
An IVR→X call ended with a SIP-UA ( The value is hypothetical, since |
|
The IVR→X call after the pre-reply has timed out. The value is hypothetical because if there is no final response, the server (role b2b), terminates the call by automatically emulating the response |
|
No response from subscriber X, or other unexpected situation. Fields may be missing from the response |
|
Subscriber X successfully answered the IVR→X call, call status X→Y is unknown due to missing or unknown content of NOTIFY SIP requests in the dialog served by the REFER. |
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"result": "ok",
"ivrcallid": "rIV-006-J8zgklJrGuVxZSlo1ZUWOjjJyl1",
"acallid": "3099649154@192.168.0.149",
"dialogid": "rDlg-002-6FpTv2",
"last_response": "SIP/2.0 100 Trying"
}Searching for call ID (LOOKUP)
Searches for a resource (active dialog) by the specified key.
A list of identifiers of detected dialogs matching the search conditions is returned.
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.
The result of the query execution undergoes additional filtering. Only those dialogs where one of the participants is an authorized user (through any of the accounts belonging to him/her) are detected sipuser).
Request
| Parameter | Type | Description |
|---|---|---|
|
|
Search Value. Dialog identifier used during dialog formation endpoint. Unique in rantime, but is not globally unique and may be repeated after some time within the same system. For example, |
|
|
Search Value. 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 |
|
|
Search Value. Call Identifier For example, |
|
|
Search Value. SIP URI: |
|
|
Search Value. 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 |
|
|
Search Value. Account Identifier SIP-user. |
|
|
Search Value. Account login SIP-user. |
|
|
Search Value. Phone number of the account SIP user. |
|
|
LOOKUP /rest/v1/uc/calls_by_participation HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"callid": "rB2-002-XPhrjh-01-3587482024@192.168.0.146"
}Receiving information about the call (GET)
Returns information about the dialog.
The request is pre-filtered. To be allowed to execute, the specified dialog must have as one of its participants an authorized user (through any of the accounts belonging to the user) sipuser).
Request
| Name | Type | Description |
|---|---|---|
|
|
Identifier of the dialog to be translated (master). Passed on as part of Endpoint URI. |
|
|
A list of fields to output. |
|
|
Conversion to flat form of composite fields. |
GET /rest/v1/uc/calls_by_participation/rDlg-002-484FD3 HTTP/1.1Response
Returns an object with a dialog representation.
| Field | Description |
|---|---|
|
Call-Id of the initiating side of the dialog. Contained in the corresponding header of the initiating SIP request INVITE. |
|
A list of all Call-Id’s of active dialog participants. Each side of the dialog has its own Call-Id, each called fork has a unique Call-Id. |
|
Active dialog 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. |
|
Role dialog identifier esg. Has a non-empty value only if the dialog is created based on an external incoming call from the provider’s account. Can be used as an external caller service session identifier, since the esg dialog is not changed during call transfer. |
|
CallId an external caller hidden behind the role esg. Has a non-empty value only if the dialog is created based on an external incoming call from the provider’s account. |
|
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. |
|
The general state of the dialog. Value options:
In fact, the dialog state machine has many more states, but they all fit into the general states. |
|
List of dialog shoulders.
Each dialog always has exactly one initiator (calling party
In the general state
Each element of the list is object. |
|
String representation of the URI from the The format is |
|
String representation of the URI from the The format is |
|
The name of the site whose servers serve the dialog. |
|
Timestamp of the time the initiating SIP request INVITE arrives in the system. Is a representation of a point in time and can be converted to a specific date in any time zone. For example, |
|
A list of all URIs involved in the call. Each SIP user that is a subscriber to a dialog has two URIs, one specified via |
|
An object with additional dialog parameters. Contains:
|
| Field | Description |
|---|---|
|
Call-Id shoulder. Contained in the corresponding header of the INVITE SIP request (received or sent). |
|
Limits the call time of the caller in milliseconds. Valid only for the shoulder side |
|
String representation local URI. For the shoulder of side The format is |
|
String representation remote URI. For arm side The format is |
|
Code side of the dialog:
|
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"acallid": "3113017065@192.168.0.149",
"callids": [
"rB2-002-484FD3-01-3113017065@192.168.0.149",
"3113017065@192.168.0.149"
],
"dialogid": "rDlg-002-484FD3",
"esgdlg": "",
"esgcallid": "",
"inviteid": "357924f1-0623-b685-c105-b80000000002",
"legs": [
{
"callid": "3113017065@192.168.0.149",
"expirets": "undefined",
"localuri": "<sip:sip3@test.rootdomain.ru>",
"remoteuri": "<sip:sip2@test.rootdomain.ru>",
"side": "a"
},
{
"callid": "rB2-002-484FD3-01-3113017065@192.168.0.149",
"expirets": 30000,
"localuri": "<sip:12@test.rootdomain.ru>",
"remoteuri": "<sip:sip3@test.rootdomain.ru>",
"side": "b"
}
],
"localuri": "<sip:sip3@test.rootdomain.ru>",
"opts": {
"referred-by": "<sip:sip1@test.rootdomain.ru>"
},
"remoteuri": "<sip:sip2@test.rootdomain.ru>",
"site": "SITE1",
"startts": 1571747612067,
"status": "forking",
"uris": [
"<sip:12@test.rootdomain.ru>",
"<sip:sip3@test.rootdomain.ru>",
"<sip:sip3@test.rootdomain.ru>",
"<sip:sip2@test.rootdomain.ru>"
]
}Transferring a call to a number (REFER)
Performs call transfer - dialog subscriber (opponent) - to the specified number.
Valid for any active dialog in the current domain.
There are standard limitations when translating dialog that is in a state of status=forking.
Process Flowchart: X-Y | IVR→Y, IVR REFER Z, Y→Z.
The operation is carried out through the launch of a hidden service script that performs a prepared call to a specified subscriber with substitution of a specific specified dialog box
(Dialer script component with Replaces and Referred-By headers installed),
and then transferring control to a specially prepared hidden IVR script with the Dial-up component].
The specified number is substituted as the number to be transferred referto.
If the transfer fails, the next script component transfers the call back to the transfer initiator’s number.
The request is pre-filtered. To be allowed to execute, the specified dialog must have as one of its participants an authorized user (through any of the accounts belonging to the user) sipuser).
Request
| Name | Type | Description |
|---|---|---|
|
|
Identifier of the dialog to be translated. Passed on as part of Endpoint URI. |
|
|
The side of the dialog initiating the call transfer. Based on the value, the oppositional party to be translated is calculated. It is to this party that the INVITE SIP request with Replaces from the IVR and the subsequent SIP request are sent REFER. |
|
|
The number to which the subscriber is being transferred. Allows the characters “'” and “,” to be specified. The first such character allocates the remaining sequence as a DTMF pre-dial after the response is received, and each subsequent such character provides a 1-second pause in the set DTMF. |
|
|
Response return mode. The larger the value, the later the response is sent, and the more contextual information the response contains. Possible options:
Default |
|
|
Label bound to the swap call and trace to the transfer call. Not assigned by default. |
REFER /rest/v1/uc/calls_by_participation/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"referto": "13",
"by": "<sip:11@test.rootdomain.ru>",
"response_mode": 3
}Response
| Field | Description |
|---|---|
|
The identifier of the dialog to be translated. Matches the identifier in the endpoint or is transferred unchanged from the request parameters. |
|
The final result of the operation. Value options. |
|
Call-Id initiating automatic IVR→Y call (different from CallId of the target dialog shoulders). Present in any case. |
|
Call-Id call received in the system from subscriber Y to subscriber Z after processing SIP REFER request. This is the Call-Id of the |
|
Response-Line the last received response from subscriber Z, based on the results of which a response to the request is generated. In case of some unsuccessful results of the operation may be absent. |
|
The identifier of the target Y→Z dialog. May be absent in some unsuccessful results of the operation. It may also be absent if the dialog duration is 0 seconds. |
| Significance | Description |
|---|---|
|
The response is formed at a stage where no problems are identified to successfully create a Y→Z dialog. For example, for
|
|
IVR→Y call failed ( In case an unsuccessful response is received from subscriber Y, the result does not contain information about dialog Y→Z, fields |
|
IVR→Y call ended with SIP-UA ( The value is hypothetical, since |
|
The IVR→Y call after the pre-reply has timed out. The value is hypothetical because if there is no final response, the server (role b2b), terminates the call by automatically emulating the response |
|
No response from subscriber Y, or other unexpected situation. Fields may be missing from the response |
|
Subscriber Y successfully answered the IVR→Y call, the status of the Y→Z call is unknown due to missing or unknown content of NOTIFY SIP requests in the dialog served by the REFER. |
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"dialogid": "rDlg-002-WOabz0",
"result": "ok",
"ivrcallid": "rIV-006-5avZy6B3IC5nivAvVS5B6n4prqT",
"new_acallid": "1920460747@192.168.0.149",
"new_dialogid": "rDlg-002-JKNked",
"new_last_response": "SIP/2.0 180 Ringing"
}Transferring a spoofed call (REFERREPLACES)
Makes a connection between the subscribers of two different active dialogs in the current domain.
The subscriber connects its two opponents in different active dialogs, and releases itself according to the SIP protocol (in particular, a SIP-UA that receives an INVITE from Replaces performs a BYE send towards the opponent in the spoofed dialog).
A schematic of the process in general terms: X-Y, P-Q | IVR→Y, IVR REFER+REPLACES Q, Y→Q.
Cmain case process flowchart: X-Y, X-Z | IVR→Y, IVR REFER+REPLACES Z, Y→Z.
Since two calls are involved, the name of each parameter contains the prefix: "master" or "slave".
The operation is carried out through the launch of a hidden service script that performs a prepared dial-up to the subscriber of one dialog with substitution (script component "Dial-up" with installed headers Replaces and Referred-By), followed by transfer of control to a specially prepared hidden IVR script with the component "Transfer with substitution". The identifier of the second specified dialog is substituted as the target for transfer (slave).
The request is pre-filtered. To be allowed to execute, the specified dialogs must have as one of their participants an authorized user (via any of the accounts belonging to the user) sipuser).
Request
| Name | Type | Description |
|---|---|---|
|
|
Identifier of the dialog to be translated (master). Passed on as part of Endpoint URI. |
|
|
The side of the master dialog initiating the call transfer. Based on the value, the oppositional party to be translated is calculated. It is to this party that the INVITE SIP request with Replaces from the IVR and the subsequent SIP request are sent REFER. |
|
|
Identifier of the dialog to be spoofed (slave). There are other ways of specifying a slave dialog alternative to this.
All the ways to specify a dialog are listed below in descending order of priority with a brief description.
For details, see the parameters of the call lookup operation with the prefix added
|
|
|
The side of the slave dialog to be spoofed. Based on the value, the opposing side is calculated, at which the shoulder should be swapped. The REFER with Replaces is targeted to it and as a consequence it is sent a SIP request INVITE with Replaces from Y. |
|
|
Response return mode. The larger the value, the later the response is sent, and the more contextual information the response contains. Possible options:
Default |
|
|
A label to be bound to the swap call and trace to the transferred swap call. Not assigned by default. |
REFERREPLACES /rest/v1/uc/calls_by_participation/rDlg-002-HKO7cn HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"masterby": "1771996496@192.168.0.147",
"slavedialogid": "rDlg-002-YWR7ts",
"slaveby": "2622745275@192.168.0.149",
"response_mode": 4
}Response
| Field | Description |
|---|---|
|
Identifier of the dialog to be translated (master). Matches the identifier in the endpoint or is transferred unchanged from the request parameters. |
|
Identifier of the dialog to be swapped (slave). Goes unchanged from the request parameters. |
|
The final result of the operation. Value options. |
|
Call-Id initiating automatic IVR→Y call (different from CallId of the target dialog shoulders). Present in any case. |
|
Call-Id call received in the system from subscriber Y to subscriber Z after processing SIP REFER request. This is the Call-Id of the |
|
Response-Line the last received response from subscriber Z, based on the results of which a response to the request is generated. In case of some unsuccessful results of the operation may be absent. |
|
The identifier of the target Y→Z dialog. May be absent in some unsuccessful results of the operation. It may also be absent if the dialog duration is 0 seconds. |
| Significance | Description |
|---|---|
|
The response is formed at a stage where no problems are identified to successfully create a Y→Z dialog. For example, for
|
|
IVR→Y call failed ( In case an unsuccessful response is received from subscriber Y, the result does not contain information about the dialog Y→Q, the fields |
|
IVR→Y call ended with SIP-UA ( The value is hypothetical, since |
|
The IVR→Y call after the pre-reply has timed out. The value is hypothetical because if there is no final response, the server (role b2b), terminates the call by automatically emulating the response |
|
No response from subscriber Y, or other unexpected situation. Fields may be missing from the response |
|
Subscriber Y successfully answered the IVR→Y call, the status of the Y→Q call is unknown due to missing or unknown content of NOTIFY SIP requests in the dialog served by REFER. |
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"masterdialogid": "rDlg-002-HKO7cn",
"slavedialogid": "rDlg-002-YWR7ts",
"result": "ok",
"ivrcallid": "rIV-006-OCXV3CJPkbUUlFx6v8O00kjTm22",
"new_acallid": "3762659316@192.168.0.146",
"new_dialogid": "rDlg-002-RqNtEp",
"new_last_response": "SIP/2.0 200 OK"
}Converting a call to a conference (SWITCHCONF)
Soft switches both callers of the specified dialog to the conference room. Both subscriber devices receive INVITE SIP requests from Replaces, connect to IVRs, which translate them to the conference room using SIP requests REFER. Subscribers can be in different domains. The conference will be created in the domain in which the conversion API request is made (or the script that performs the operation is executed).
The operation is performed by running hidden service scripts - one for each of the subscribers making a prepared call to the corresponding dialog subscriber
with substitution (script component Outgoing call with Replaces and Referred-By headers set),
with subsequent transfer of control to a specially prepared hidden IVR script with the component Transfer to number.
The conference room number along with the CAF is substituted as the target for transfer (featurecode type conf).
The number to be transferred can be specified in the referto request parameter, otherwise it is calculated automatically - routing must be configured.
Process Flowchart: X-Y | IVR1→X, IVR2→Y, IVR1 REFER CONF, IVR2 REFER CONF, X→CONF, Y→CONF.
The by request parameter specifies an arbitrary username or number in the current domain on behalf of which both subscribers of the dialog are transferred to the conference.
Actually should be used if the routing is special and not everyone has access to the featurecode of the conference.
So that when one subscriber receives an INVITE from Replaces, the other subscriber does not fall off by BYE
(the receiving party sends a BYE to the opponent of the spoofed dialog according to the SIP protocol, and the b2b role brushes it through),
the role b2b receives a command to temporarily pause the dialog (effectively blocking the BYE resend - instead, a delayed asynchronous BYE sending operation for 3 seconds is started when the BYE is received).
After receiving 2xx SIP responses from both subscribers to INVITE with Replaces, the dialog is paused.
In a normal situation, he’s out of existence by this time.
In case of failure, the original conversation is not restored. Theoretically, it is possible that one subscriber will be able to reach the conference room and the other will not. In this case, one will get a bounce and the other will be alone in the conference.
A dialog whose subscriber is a conference (username = "conf-…") is not allowed to be converted to a conference
(is not due to implementation complexities, it’s just an external restriction so that empty conferences related to each other don’t hang).
The request is pre-filtered. To be allowed to execute, the specified dialog must have as one of its participants an authorized user (through any of the accounts belonging to the user) sipuser).
Request
| Name | Type | Description |
|---|---|---|
|
|
Identifier of the dialog to be translated (master). Passed on as part of Endpoint URI. |
|
|
The full conference number along with the CAF prefix. The parameter is optional. If it is missing, a random 8-digit conference room number is generated, and the prefix of the first one found in the domain featurecode with type |
|
|
The number or username of the subscriber on whose behalf you want to transfer to the conference room. The parameter is optional. Default value: For the specified subscriber, route to the conference room must be available (routing rules are defined by the entities route and vectorrule). |
|
|
Response return mode. The larger the value, the later the response is sent, and the more contextual information the response contains. Possible options:
Default |
|
|
Label bound to the swap call and trace to the transfer call. Not assigned by default. |
SWITCHCONF /rest/v1/uc/calls_by_participation/rDlg-002-Maw6qN HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"referto":"*99358",
"by":"sip3",
"response_mode": 4
}Response
| Field | Description |
|---|---|
|
The identifier of the dialog to be converted to a conference. Matches the identifier in the endpoint or passes unchanged from the request parameters. |
|
String containing the number used for conference transfer. Indicates the system-generated full number with a prefix, or the number specified in the request in the field |
|
The final result of the operation. Value options. |
|
The identifier of the conference to which subscribers are redirected. |
|
Call-Id initiating automatic call IVR1→X (different from the CallId of the shoulders of the target conference dialog). Present in any case. |
|
Call-Id call received in the system from subscriber Y to subscriber Z after processing SIP REFER request. This is the Call-Id of the |
|
Response-Line the last received response from subscriber Z, based on the results of which a response to the request is generated. In case of some unsuccessful results of the operation may be absent. |
|
The identifier of the target Y→Z dialog. May be absent in some unsuccessful results of the operation. It may also be absent if the dialog duration is 0 seconds. |
|
Call-Id initiating automatic IVR2→Y call (different from the CallId of the shoulders of the target conference dialog). Present in any case. |
|
Call-Id call received in the system from subscriber Y to subscriber Z after processing SIP REFER request. This is the Call-Id of the |
|
Response-Line the last received response from subscriber Z, based on the results of which a response to the request is generated. In case of some unsuccessful results of the operation may be absent. |
|
The identifier of the target Y→Z dialog. May be absent in some unsuccessful results of the operation. It may also be absent if the dialog duration is 0 seconds. |
| Significance | Description |
|---|---|
|
The response is formed at a stage where no problems are identified to successfully create a Y→Z dialog. For example, for
|
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"dialogid": "rDlg-002-Maw6qN",
"referto": "*99358",
"result": "ok",
"confid": "rCF-005-ZIzwBi",
"x_ivrcallid": "rIV-006-D0qaTIsaTzBoWDHiAYgCIOo7odO",
"x_new_acallid": "27142922@192.168.0.149",
"x_new_dialogid": "rDlg-002-UTx2LP",
"x_new_last_response": "SIP/2.0 200 OK",
"y_ivrcallid": "rIV-006-TTBdJOR0ifh8HYiE9sVwqqJ31HW",
"y_new_acallid": "817803971@192.168.0.147",
"y_new_dialogid": "rDlg-002-XVRAsk",
"y_new_last_response": "SIP/2.0 200 OK"
}Transferring a call to a conference (REFERCONF)
Transfers the specified call (opponent in a dialog) to an existing conference. This is analogous to the transfer-to-number operation with automatic conference lookup, calculation and substitution of the conference number for routing.
The operation is carried out through the launch of a hidden service script that performs a prepared dial-up to the specified subscriber with substitution of a specific specified dialog (script component "Dial-up" with Replaces and Referred-By headers set) and subsequent transfer of control to a specially prepared hidden IVR script with the component "Transfer to number". The number of the detected conference is substituted as the number to be translated, as follows featurecode + confroomnum. If the transfer fails, the next component transfers the subscriber back to the number of the transferor.
Process Flowchart: X→CONF (hold), X→Y | IVR→Y, IVR REFER CONF, Y→CONF.
The transfer is done in the conference domain. If the request is suddenly executed in a different domain relative to the conference, an error is returned. This is possible if a subscriber from another domain participates in the conference and the conference is specified by referring to his dialog.
After successful completion of the operation, the transferring subscriber X remains on hold in the conference. In order to return to it, he/she needs to take it off hold using commands from his/her SIP device.
An alternative approach to this operation is to use the "Transfer to Number" method, specifying the number at which a particular conference room is available.
The request is pre-filtered. To be allowed to execute, the specified dialog must have as one of its participants an authorized user (through any of the accounts belonging to the user) sipuser).
Request
| Name | Type | Description |
|---|---|---|
|
|
The identifier of the dialog to be transferred to the conference. Passed on as part of Endpoint URI. |
|
|
The side of the dialog initiating the call transfer to the conference. Based on the value, the oppositional party to be translated is calculated. It is to this party that the INVITE SIP request with Replaces from the IVR and the subsequent SIP request are sent REFER. |
|
|
The identifier of the dialog, one of the participants of which is the conference - transfer destination. This is one possible way of indicating the conference that is the target of the transfer. There are other ways of specifying the conference alternative to this.
All ways of indicating the conference are listed below in descending order of priority with a brief description.
For details, see the parameters of the call lookup operation with the prefix added
|
|
|
Response return mode. The larger the value, the later the response is sent, and the more contextual information the response contains. Possible options:
Default |
|
|
Label bound to the swap call and trace to the transfer call. Not assigned by default. |
REFERCONF /rest/v1/uc/calls_by_participation/rDlg-002-96Ptom HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"by": "2362769183@192.168.0.203",
"referdialogid": "rDlg-002-96Ptom",
"response_mode": 3
}Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"dialogid": "rDlg-002-96Ptom",
"result": "ok",
"ivrcallid": "rIV-006-1pq2q9apUWvHHJRXiImXOlPrOOC",
"new_acallid": "1920460747@192.168.0.149",
"new_dialogid": "rDlg-002-Uf38zV",
"new_last_response": "SIP/2.0 180 Ringing"
}Sending a device control event to one of the parties (NOTIFY)
Realizes server-initiated software control of the subscriber’s device.
Sends a NOTIFY request with an event message to the specified subscriber’s device. In particular, this may be used to control the device in accordance with the extension Cisco Broadsoft (https://pubhub.devnetcloud.com/media/broadsoft-docs/docs/pdf/BW-SIPAccessSideExtensionsInterfaceSpec.pdf) Depending on the type of message, the device can:
-
answer the phone (
talk), -
enter hold mode (
hold), -
exit hold mode (
talk), -
combine held callers in a phone-controlled conference (
conference) -
other
The operation is performed in call mode for the called party (talk), or in dialog mode for either party.
According to RFC3265, supported events are listed by the device in the Allow-Events header in the INVITE request or response 1xx/2xx.
If the device does not support the extension, it does not send the appropriate values in the header, and on that basis the server blocks the NOTIFY request from being sent.
Sending a message is asynchronous, the final result is not reported. A successful response means only that the request was sent.
The server does not apply the extensions itself, but provides the ability to use their functionality externally to the system through APIs and scripts. The composition of supported extensions is determined by the device. The quality of the system’s support for device expansion is not guaranteed. As a recommendation: use the method only in optional mode and when it is known that all devices used support the method and is not foreseen otherwise.
The request is pre-filtered. To be allowed to execute, the specified dialog must have as one of its participants an authorized user (through any of the accounts belonging to the user) sipuser).
Request
| Name | Type | Description |
|---|---|---|
|
|
The identifier of the dialog to be transferred to the conference. Passed on as part of Endpoint URI. |
|
|
The side of the dialog whose device is being controlled, |
|
|
Event name for controlling the device ( |
NOTIFY /rest/v1/uc/calls_by_participation/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"callid": "4139247432@192.168.0.149",
"event": "talk"
}Sending a DTMF character to one of the parties (SEND_DTMF)
Implements sending DTMF characters to the specified shoulder of the specified dialog. Sending sequences is supported. The request is answered immediately, but there is a queue for sending individual characters in the shoulder. The same queue is used when multiple requests are received.
Allows you to specify a sequence of DTMF characters including ' and ,. Each such character provides a 1 second pause in the set DTMF.
Depending on the protocol specified (proto):
* sipinfo - sends an INFO request with a DTMF character.
* rfc2833 - sends RTP packets according to the protocol RFC-2833.
Sending a message is asynchronous, the final result of work is not reported. A successful response means only that a request or a series of RTP packets has been sent.
The request is pre-filtered. To be allowed to execute, the specified dialog must have as one of its participants an authorized user (through any of the accounts belonging to the user) sipuser).
Request
| Name | Type | Description |
|---|---|---|
|
|
The identifier of the dialog to be transferred to the conference. Passed on as part of Endpoint URI. |
|
|
The side of the dialog to which the DTMF character is to be sent, |
|
|
Alternate indication of the party to the dialog ( |
|
|
An indication of the taking of another party relative to the specified party. |
|
|
Selects the mode of sending DTMF character ( |
|
|
DTMF-character to send ( |
SEND_DTMF /rest/v1/uc/calls_by_participation/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"dtmf": "2",
"proto": "rfc2833",
"callid": "4139247432@192.168.0.149"
}Start/stop stenography of a party’s speech (SETUP_ASR)
Enables/disables recording and recognition in the text of the specified shoulder of the specified dialog.
A successful response to an enable operation means only that a request or series of RTP packets has been sent.
When the mode is turned off, the response is delayed for a few seconds until the recognition session is complete.
You can use the following to get events about the result as you recognize it websocket api.
The mode works when the speech steno subsystem (master domain) is installed and configured, settings.record_asr_options)
The request is pre-filtered. To be allowed to execute, the specified dialog must have as one of its participants an authorized user (through any of the accounts belonging to the user) sipuser).
Request
| Name | Type | Description |
|---|---|---|
|
|
The identifier of the dialog to be transferred to the conference. Passed on as part of Endpoint URI. |
|
|
Operation: |
|
|
Specifies a unique name for the layer. Multiple layers are supported at the same time, when an existing layer is specified, it is replaced. In order to stop recording and recognition, you also need to specify an existing layer. |
|
|
The side of the dialog that needs to be sent for shorthand, |
|
|
Alternate indication of the party to the dialog ( |
|
|
An indication of the taking of another party relative to the specified party. |
|
|
For the stop operation, sets the wait and return mode of the summary text. In the case of true (default), the response is delayed for 2-3 seconds. |
SETUP_ASR /rest/v1/uc/calls_by_participation/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"layer": "default",
"side": "b"
}Start/stop (add/remove) a dialog recording channel (SETUP_RECORD)
Enables/disables the recording channel of the specified dialog.
The request is pre-filtered. To be allowed to execute, the specified dialog must have as one of its participants an authorized user (through any of the accounts belonging to the user) sipuser).
Request
| Name | Type | Description |
|---|---|---|
|
|
The identifier of the dialog to be transferred to the conference. Passed on as part of Endpoint URI. |
|
|
Operation: |
|
|
Specifies a unique name for the layer. Multiple layers are supported at the same time, when an existing layer is specified, it is replaced. In order to stop recording and recognition, you also need to specify an existing layer. |
|
|
The side of the dialog to be put on the record, |
|
|
Alternate indication of the party to the dialog ( |
SETUP_RECORD /rest/v1/uc/calls_by_participation/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"layer": "default"
}Managing dialog labels (SETUP_BINDINGS)
Manages the labels of the specified dialog.
Dialog labels are string values tied to specific conversations/dialogs, set via API or scripts. Tags are available at any point in the lifecycle of a conversation right up to the end of the conversation. The tags are saved when the call is transferred and transferred to the newly transferred conversation.
Tags are based on the binding to service sessions in the CC (name "seance_…"), as well as the post call survey mechanism (name "post call survey") "PCS:…").
In the Operation script component, label management is available through a separate command group (labels).
The request is pre-filtered. To be allowed to execute, the specified dialog must have as one of its participants an authorized user (through any of the accounts belonging to the user) sipuser).
Request
| Name | Type | Description |
|---|---|---|
|
|
The identifier of the dialog to be transferred to the conference. Passed on as part of Endpoint URI. |
|
|
Operation:
|
|
|
Specifies a label or a list of labels. |
SETUP_BINDINGS /rest/v1/uc/calls_by_participation/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"command": "add",
"label": ["aaa", "bbb"]
}Ending a call (DELETE)
Concludes the dialog. The server acts as a break initiator for both subscribers (sends a BYE SIP request to both subscribers). If the dialog is in a call state, a SIP request is sent to all called subscribers CANCEL.
In the current version, the completion is external without indicating in the events of the callevents class a sign of binding to the actions of party A or the party B.
The request is pre-filtered. To be allowed to execute, the specified dialog must have as one of its participants an authorized user (through any of the accounts belonging to the user) sipuser).
Response
HTTP/1.1 200 Ok
Content-Type: application/json; charset=utf-8
{
"dialogid": "rDlg-002-9dEcfh"
}HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
{
"error_code": 1413,
"error_message": "Dialog not found"
}See also
-
API /rest/v1/uc/calls with access to arbitrary domain calls with no user restrictions.
-
API /rest/v1/uc/conferences_by_participation to manage domain conferences involving an authorized user.
-
role b2b.
-
role mware.
-
role callstore.