Call management (calls)
- Overview
- Requests
- Getting the call list (GET)
- Initiating a new call (POST)
- Initiating a new call (INVITE)
- Initiating a new call with IVR servicing (INVITEBYIVR)
- Searching for a call identifier (LOOKUP)
- Searching for a call identifier (LOOKUP)
- Getting call information (GET)
- Transferring a call to a number (REFER)
- Transferring a call with replacement (REFERREPLACES)
- Converting a call into a conference (SWITCHCONF)
- Transferring a call to a conference (REFERCONF)
- Sending a device control event (NOTIFY)
- Sending a DTMF signal to a leg (SEND_DTMF)
- Starting/stopping speech transcription of one party (SETUP_ASR)
- Enabling/disabling (adding/removing) the dialog recording channel, and controlling the main recording pause (SETUP_RECORD)
- Enabling/disabling (adding/removing) the dialog playback channel (SETUP_PLAYER)
- Managing dialog labels (SETUP_BINDINGS)
- Stopping the hold melody (STOP_HOLD_MELODY)
- Setting a custom hold melody (SETUP_HOLD_MELODY)
- Terminating a call (DELETE)
- See also
Overview
Manages existing active calls (B2B dialogs) via API commands (without initiatives from SIP devices).
Any calls initiated in the system both via the API and from SIP devices and SIP-UA services are available for management.
Request servicing is performed by the mware role.
The callstore role is required for operation.
The service is also available from scripts through the Operation component.
Requests
| HTTP verb | Endpoint | Description |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Starting/stopping speech transcription of one party (SETUP_ASR) |
|
|
|
|
|
Enabling/disabling (adding/removing) the dialog playback channel (SETUP_PLAYER) |
|
|
|
|
|
|
|
|
|
|
|
Getting the call list (GET)
Returns the list of active dialogs within the current domain.
Any dialog has two sides: calling (A) and called (B). There may be one or several subscribers representing side B depending on the dialog state.
A dialog belongs to a domain if at least one of its subscribers (dialog legs) belongs to the domain (is a provider account, SIP user, conference, or IVR script).
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. |
|
|
Resource sorting order in the list. |
|
|
Conversion of composite fields to flat form. |
|
|
Return only the number of elements. |
GET /rest/v1/uc/calls?offset=0&limit=1 HTTP/1.1
Response
Returns a list of objects, each representing a separate dialog. The set of returned fields is limited: acallid, callids, dialogid, esgdlg, esgcallid, inviteid, status, legs, localuri, remoteuri, site, startts, uris, opts.
Other fields specified in the mask parameter are ignored.
| Field | Description |
|---|---|
|
Call-Id of the dialog initiating side. Contained in the corresponding header of the initiating INVITE SIP request. |
|
List of all Call-Ids of active dialog participants. Each dialog side has its own Call-Id; each called fork has a unique Call-Id. |
|
Active dialog identifier used when forming the endpoint. Unique at runtime, but not globally unique and may repeat after some time within the same system. |
|
|
|
|
|
Globally unique identifier of the call leading to the dialog. Formed when an INVITE SIP request arrives in the system and exists until the dialog completes. Present in all CDR events of the callevents class. |
|
General dialog state. Value variants:
In fact the dialog state machine has many more states, but all fit into the general states. |
|
List of dialog legs.
Every dialog always has exactly one initiator (calling side
In the general state
Each list element is an object. |
|
String representation of the URI from the Format: |
|
String representation of the URI from the Format: |
|
Name of the site whose servers serve the dialog. |
|
Timestamp of the initiating INVITE SIP request arrival in the system. It is a representation of a point in time and can be converted to a specific date in any time zone. For example, |
|
List of all URIs participating in the call. Each SIP user that is a dialog subscriber has two URIs, one specified via |
|
Object with additional dialog parameters. Contains:
|
| Field | Description |
|---|---|
|
Leg Call-Id. Contained in the corresponding header of the INVITE SIP request (received or sent). |
|
Subscriber call time limit in milliseconds. Meaningful only for the side |
|
String representation of the local URI. For the side Format: |
|
String representation of the remote URI. For the side Format: |
|
Dialog side code:
|
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 a call to subscriber X (number in the from field) in intercom mode, and after the answer transfers it (REFER SIP request) to subscriber Y (number in the to field).
To initiate intercom call mode, a featurecode of the corresponding type must exist in the system and be available in routing at least for subscribers toward themselves and for subscriber 100 (callmanager).
The operation is performed by launching a hidden service script that makes a prepared call to the initiator
(the Outgoing call script component)
with control transferred to a specially prepared hidden IVR script with the Transfer to number component.
The specified to number is substituted as the transfer number.
Process scheme: IVR→X, IVR REFER Y, X→Y.
The request executes asynchronously. The response is returned at the moment determined by the response_mode parameter.
The call initiation process context is gradually filled with call data as it executes.
The data content in the response corresponds to the moment of its return – the later the selected process point, the more data and the more accurate the result.
CDR events of the target call can be obtained from the system event subscription interface.
The subscriber on whose behalf the outgoing call is ordered hears all call progress signals of the organized outgoing call after lifting the handset.
Request
| Name | Type | Description | ||
|---|---|---|---|---|
|
|
Mode for specifying the X side initiator of the created call. Possible variants:
|
||
|
|
Depending on the mode ( |
||
|
|
Called subscriber Y number. Allows specifying the characters “'” and “,”. The first such character marks the remaining sequence as DTMF post-dialing after the answer, and each subsequent such character provides a 1-second pause in DTMF dialing. |
||
|
|
First call initiator number. Displayed to subscriber X. By default the |
||
|
|
First call initiator name. Default |
||
|
|
First call timeout in seconds. Limits the standard call time. Default 30 sec. |
||
|
|
Label bound to the call. Not assigned by default. |
||
|
|
Response return mode. The larger the value, the later the response is sent and the more context information it contains. Possible variants:
Default |
||
|
|
Intercom mode switch for calling the subscriber. Disabled by default.
|
POST /rest/v1/uc/calls 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 |
|---|---|
|
Final operation result. Value variants. |
|
Call-Id of the initiating automatic IVR→X call (differs from target dialog leg CallIds). Always present. |
|
Call-Id of the call received by the system from subscriber X to subscriber Y after processing the REFER SIP request. This is the |
|
Response-Line of the last response received from subscriber Y on which the request response is based. May be absent for some unsuccessful operation results. |
|
Target X→Y dialog identifier. May be absent for some unsuccessful operation results. May also be absent if dialog duration is 0 seconds. |
| Value | Description |
|---|---|
|
The response is formed at a stage where no problems were found for successful X→Y dialog creation. For example, for
|
|
The IVR→X call failed ( If the failure response was received from subscriber X, the result contains no X→Y dialog information; the |
|
The IVR→X call ended with SIP-UA redirection ( The value is hypothetical since the server itself (the b2b role) handles |
|
The IVR→X call timed out after a preliminary response. The value is hypothetical since, in the absence of a final response, the server (the b2b role) ends the call by automatically emulating a |
|
No response was received from subscriber X, or another unexpected situation occurred. The |
|
Subscriber X successfully answered the IVR→X call; the X→Y call state is unknown due to missing or unknown NOTIFY SIP request content in the dialog that served 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"
}
Initiating a new call with IVR servicing (INVITEBYIVR)
Initiates a call to subscriber Y and starts the specified script for servicing it.
DTMF post-dialing after the subscriber answer with controlled pauses is supported.
The operation is performed by launching a hidden service script that makes a prepared call to the initiator (the Outgoing call script component) with control transferred to a specially prepared hidden IVR script with the DTMF generation and Nested script launch components.
Process scheme: IVR→X.
The request executes asynchronously. The response is returned at the moment determined by the response_mode parameter.
The call initiation process context is gradually filled with call data as it executes.
The data content in the response corresponds to the moment of its return – the later the selected process point, the more data and the more accurate the result.
CDR events of the target call can be obtained from the system event subscription interface.
Request
| Name | Type | Description | ||
|---|---|---|---|---|
|
|
Called subscriber Y number. Allows specifying the characters “'” and “,”. The first such character marks the remaining sequence as DTMF post-dialing after the answer, and each subsequent such character provides a 1-second pause in DTMF dialing. |
||
|
|
First call initiator number. Displayed to subscriber X. By default the |
||
|
|
First call initiator name. Default |
||
|
|
First call timeout in seconds. Limits the standard call time. Default 30 sec. |
||
|
|
Intercom mode switch for calling the subscriber. Disabled by default.
|
||
|
|
Label bound to the call. Not assigned by default. Inherited by all subsequent transferred calls. |
||
|
|
List of additional headers for the INVITE request as a string separated by line feed (CLCR). |
||
|
|
Response return mode. The larger the value, the later the response is sent and the more context information it contains. Possible variants:
Default |
||
|
|
Protocol for sending post-dial DTMF characters. All characters passed in the number after a comma are sent after the subscriber answer. Each comma is a one-second pause. Possible variants:
|
||
|
|
IVR script code that should serve the subscriber. |
||
|
|
String sent as the first parameter to the script; if its value is a JSON object, it sets initial values for variables whose names are the object keys. |
||
|
|
String placed in start parameter 2 of the IVR script. |
INVITEBYIVR /rest/v1/uc/calls HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"to": "22",
"scriptcode": "test_play",
"response_mode": 2,
"callerid": "100",
"callername": "callmanager",
"calltimeout": 30,
"use_intercom": false,
"binding": "sample_label",
"headers": "X-Header-Sample-1: 123\r\nX-Header-Sample-2: a; b; c"
}
Response
| Field | Description |
|---|---|
|
Final operation result. Value variants. |
|
Call-Id of the initiating automatic IVR→X call (differs from target dialog leg CallIds). Always present. |
|
Code of the last response received from subscriber X on which the request response is based. May be absent for some unsuccessful operation results. |
|
Target IVR→X dialog identifier. May be absent for some unsuccessful operation results. May also be absent if dialog duration is 0 seconds. |
| Value | Description |
|---|---|
|
The response is formed at a stage where no problems were found for successful X→Y dialog creation. For example, for
|
|
The IVR→X call failed ( If the failure response was received from subscriber X, the result contains no X→Y dialog information; the |
|
The IVR→X call ended with SIP-UA redirection ( The value is hypothetical since the server itself (the b2b role) handles |
|
The IVR→X call timed out after a preliminary response. The value is hypothetical since, in the absence of a final response, the server (the b2b role) ends the call by automatically emulating a |
|
No response was received from subscriber X, or another unexpected situation occurred. The |
|
Subscriber X successfully answered the IVR→X call; the X→Y call state is unknown due to missing or unknown NOTIFY SIP request content in the dialog that served 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 a call identifier (LOOKUP)
Searches for a resource (active dialog) by the specified key.
Returns the list of identifiers of discovered dialogs matching the search conditions.
Search fields are applied one at a time in descending priority order in the table below. Search fields contain a "Search value" in their description. Multiple returns are possible, for example when searching by SIP user login if that user participates in several dialogs.
Request
| Parameter | Type | Description |
|---|---|---|
|
|
Search value. Dialog 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, |
|
|
Search value. Globally unique identifier of the call leading to the dialog. Formed when an INVITE SIP request arrives in the system and exists until the dialog completes. Present in all CDR events of the callevents class. For example |
|
|
Search value. Call For example, |
|
|
Search value. SIP URI: |
|
|
Search value. Phone number or SIP user login used as May use the additional
Default Dialogs are discovered where the specified subscriber of the current domain acts as one side.
Search is performed similarly to |
|
|
Search value. SIP user account identifier. |
|
|
Search value. SIP user account login. |
|
|
Search value. SIP user account phone number. |
|
|
LOOKUP /rest/v1/uc/calls HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"callid": "rB2-002-XPhrjh-01-3587482024@192.168.0.146"
}
Searching for a call identifier (LOOKUP)
Initiates the conversation recording transcription process for an archived dialog (connection) for which a recording was made. Used to transcribe a previously recorded conversation for which automatic transcription of completed conversations is not configured.
The same service used for automatic transcription is used. Moreover, the same queue and the same rules are used. Configuration of access to transcription servers, service activity time, and the number of parallel streams is set in the master domain, field record_asr_options.
The on-request conversation transcription process is asynchronous; the result is the timely sending of the ccsevents.connection_set_asr event.
Request
| Parameter | Type | Description |
|---|---|---|
|
|
Macro identifier of the completed call. It can be discovered:
|
|
|
String with the conversation recording location. Can be discovered:
|
TRANSCRIBE /rest/v1/uc/calls HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"idconn":"d5fbb9b5-06d0-3425-fcad-8400000003ee.1744213599830",
"reclink": "sk:test_s3_records:2025-04-09/15:46/mg12_1883946680-1744213599840.mp3"
}
Getting call information (GET)
Returns dialog information.
Request
| Name | Type | Description |
|---|---|---|
|
|
Identifier of the dialog to be transferred (master). Passed as part of the Endpoint URI. Used as a parameter when sending a command from a script by the Operation component. When sending a command from a script there are other ways to specify the dialog alternative to this one. All dialog specification methods are listed below in descending priority order with a brief description. For details see the call search operation parameters. * |
|
|
List of fields to output. |
|
|
Conversion of composite fields to flat form. |
GET /rest/v1/uc/calls/rDlg-002-484FD3 HTTP/1.1
Response
Returns an object with the dialog representation.
| Field | Description |
|---|---|
|
Call-Id of the dialog initiating side. Contained in the corresponding header of the initiating INVITE SIP request. |
|
List of all Call-Ids of active dialog participants. Each dialog side has its own Call-Id; each called fork has a unique Call-Id. |
|
Active dialog identifier used when forming the endpoint. Unique at runtime, but not globally unique and may repeat after some time within the same system. |
|
|
|
|
|
Globally unique identifier of the call leading to the dialog. Formed when an INVITE SIP request arrives in the system and exists until the dialog completes. Present in all CDR events of the callevents class. |
|
General dialog state. Value variants:
In fact the dialog state machine has many more states, but all fit into the general states. |
|
List of dialog legs.
Every dialog always has exactly one initiator (calling side
In the general state
Each list element is an object. |
|
String representation of the URI from the Format: |
|
String representation of the URI from the Format: |
|
Name of the site whose servers serve the dialog. |
|
Timestamp of the initiating INVITE SIP request arrival in the system. It is a representation of a point in time and can be converted to a specific date in any time zone. For example, |
|
List of all URIs participating in the call. Each SIP user that is a dialog subscriber has two URIs, one specified via |
|
Object with additional dialog parameters. Contains:
|
| Field | Description |
|---|---|
|
Leg Call-Id. Contained in the corresponding header of the INVITE SIP request (received or sent). |
|
Subscriber call time limit in milliseconds. Meaningful only for the side |
|
String representation of the local URI. For the side Format: |
|
String representation of the remote URI. For the side Format: |
|
Dialog side code:
|
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)
Transfers the call – the dialog subscriber (counterpart) – to the specified number.
Applies to any active dialog in the current domain.
Standard restrictions apply when transferring a dialog in the status=forking state.
Process scheme: X-Y | IVR→Y, IVR REFER Z, Y→Z.
The operation is performed by launching a hidden service script that makes a prepared call to the specified subscriber with replacement of the specific specified dialog
(the Call script component with Replaces and Referred-By headers set),
and then transferring control to a specially prepared hidden IVR script with the Transfer to number component.
The specified referto number is substituted as the transfer number.
If the transfer fails, the next script component transfers the call back to the transfer initiator number.
Request
| Name | Type | Description |
|---|---|---|
|
|
Identifier of the dialog to be transferred. Passed as part of the Endpoint URI. Used as a parameter when sending a command from a script by the Operation component. When sending a command from a script there are other ways to specify the dialog alternative to this one. All dialog specification methods are listed below in descending priority order with a brief description. For details see the call search operation parameters.
|
|
|
Dialog side initiating the call transfer. Based on the value, the opposite side to be transferred is computed. It is sent the INVITE SIP request with Replaces from IVR and the subsequent REFER SIP request. |
|
|
Number to which the subscriber is transferred. Allows specifying the characters “'” and “,”. The first such character marks the remaining sequence as DTMF post-dialing after the answer, and each subsequent such character provides a 1-second pause in DTMF dialing. |
|
|
Response return mode. The larger the value, the later the response is sent and the more context information it contains. Possible variants:
Default |
|
|
Label bound to the replacing call and then to the transferred call. Not assigned by default. |
REFER /rest/v1/uc/calls/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 |
|---|---|
|
Identifier of the dialog to be transferred. Matches the endpoint identifier or is passed unchanged from the request parameters. |
|
Final operation result. Value variants. |
|
Call-Id of the initiating automatic IVR→Y call (differs from target dialog leg CallIds). Always present. |
|
Call-Id of the call received by the system from subscriber Y to subscriber Z after processing the REFER SIP request. This is the |
|
Response-Line of the last response received from subscriber Z on which the request response is based. May be absent for some unsuccessful operation results. |
|
Target Y→Z dialog identifier. May be absent for some unsuccessful operation results. May also be absent if dialog duration is 0 seconds. |
| Value | Description |
|---|---|
|
The response is formed at a stage where no problems were found for successful Y→Z dialog creation. For example, for
|
|
The IVR→Y call failed ( If the failure response was received from subscriber Y, the result contains no Y→Z dialog information; the |
|
The IVR→Y call ended with SIP-UA redirection ( The value is hypothetical since the server itself (the b2b role) handles |
|
The IVR→Y call timed out after a preliminary response. The value is hypothetical since, in the absence of a final response, the server (the b2b role) ends the call by automatically emulating a |
|
No response was received from subscriber Y, or another unexpected situation occurred. The |
|
Subscriber Y successfully answered the IVR→Y call; the Y→Z call state is unknown due to missing or unknown NOTIFY SIP request content in the dialog that served 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 call with replacement (REFERREPLACES)
Connects subscribers of two different active dialogs of the current domain.
A subscriber of one dialog is connected to a subscriber of another dialog, and the counterparts are hung up according to the SIP protocol (in particular, the SIP-UA that received the INVITE with Replaces sends BYE toward the counterpart in the replaced dialog).
General process scheme: X-Y, P-Q | IVR→Y, IVR REFER+REPLACES Q, Y→Q.
Standard case: a subscriber connects two of their counterparts in different active dialogs and frees themselves. Then the process scheme is: X-Y, X-Z | IVR→Y, IVR REFER+REPLACES Z, Y→Z.
But this is not mandatory; completely arbitrary dialogs across the cluster can be selected.
Since two calls are involved, each parameter name contains a prefix: "master" or "slave".
The operation is performed by launching a hidden service script that makes a prepared call to a subscriber of one dialog with replacement (the "Call" script component with Replaces and Referred-By headers set), then transferring control to a specially prepared hidden IVR script with the "Transfer with replacement" component. The identifier of the second specified dialog (slave) is substituted as the transfer target.
Request
| Name | Type | Description |
|---|---|---|
|
|
Identifier of the dialog to be transferred (master). Passed as part of the Endpoint URI. Used as a parameter when sending a command from a script by the Operation component. When sending a command from a script there are other ways to specify the master dialog alternative to this one.
All dialog specification methods are listed below in descending priority order with a brief description.
For details see the call search operation parameters with the
|
|
|
Master dialog side initiating the call transfer. Based on the value, the opposite side to be transferred is computed. It is sent the INVITE SIP request with Replaces from IVR and the subsequent REFER SIP request. |
|
|
Identifier of the dialog to be replaced (slave). There are other ways to specify the slave dialog alternative to this one.
All dialog specification methods are listed below in descending priority order with a brief description.
For details see the call search operation parameters with the
|
|
|
Slave dialog side to be replaced. Based on the value, the opposite side whose leg should be replaced is computed. It is targeted by the REFER with Replaces and consequently receives the INVITE SIP request with Replaces from Y. |
|
|
Response return mode. The larger the value, the later the response is sent and the more context information it contains. Possible variants:
Default |
|
|
Label bound to the replacing call and then to the transferred replacing call. Not assigned by default. |
REFERREPLACES /rest/v1/uc/calls/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 transferred (master). Matches the endpoint identifier or is passed unchanged from the request parameters. |
|
Identifier of the dialog to be replaced (slave). Passed unchanged from the request parameters. |
|
Final operation result. Value variants. |
|
Call-Id of the initiating automatic IVR→Y call (differs from target dialog leg CallIds). Always present. |
|
Call-Id of the call received by the system from subscriber Y to subscriber Z after processing the REFER SIP request. This is the |
|
Response-Line of the last response received from subscriber Z on which the request response is based. May be absent for some unsuccessful operation results. |
|
Target Y→Z dialog identifier. May be absent for some unsuccessful operation results. May also be absent if dialog duration is 0 seconds. |
| Value | Description |
|---|---|
|
The response is formed at a stage where no problems were found for successful Y→Z dialog creation. For example, for
|
|
The IVR→Y call failed ( If the failure response was received from subscriber Y, the result contains no Y→Q dialog information; the |
|
The IVR→Y call ended with SIP-UA redirection ( The value is hypothetical since the server itself (the b2b role) handles |
|
The IVR→Y call timed out after a preliminary response. The value is hypothetical since, in the absence of a final response, the server (the b2b role) ends the call by automatically emulating a |
|
No response was received from subscriber Y, or another unexpected situation occurred. The |
|
Subscriber Y successfully answered the IVR→Y call; the Y→Q call state is unknown due to missing or unknown NOTIFY SIP request content in the dialog that served the 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 into a conference (SWITCHCONF)
Softly switches both subscribers of the specified dialog into a conference room. Both subscriber devices receive INVITE SIP requests with Replaces, connect to IVRs, which transfer them to the conference room using REFER SIP requests. Subscribers may be in different domains. The conference is created in the domain where the conversion API request is made (or the script performing the operation runs).
The operation is performed by launching hidden service scripts – one for each subscriber – that make a prepared call to the corresponding dialog subscriber
with replacement (the Outgoing call script component with Replaces and Referred-By headers set),
then transferring control to a specially prepared hidden IVR script with the Transfer to number component.
The conference room number together with the feature code (an featurecode of type conf) is substituted as the transfer target.
The transfer number can be specified in the referto request parameter; otherwise it is computed automatically – routing must be configured.
Process scheme: 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 whose behalf both dialog subscribers are transferred to the conference.
It is effectively necessary if routing is special and conference featurecode access is not open to everyone.
So that when one subscriber receives the INVITE with Replaces the other subscriber does not drop via BYE
(the receiving side sends BYE to the counterpart of the replaced dialog according to the SIP protocol, and the b2b role passes it through),
the b2b role receives a command for a temporary dialog pause (effectively blocking BYE forwarding – instead, on BYE receipt a delayed asynchronous BYE sending operation is started for 3 seconds).
After receiving 2xx SIP responses from both subscribers to the INVITE with Replaces, the dialog is taken out of pause.
In a normal situation it no longer exists by then.
On failure the original conversation is not restored. Theoretically a situation is possible where one subscriber reaches the conference room and the other does not. In this case one gets a hangup, and the other ends up alone in the conference.
A dialog whose subscriber is a conference (username = "conf-…") is not allowed to be converted into a conference
(not due to implementation complexity; it is simply an external restriction so that empty conferences linked to each other do not hang).
Request
| Name | Type | Description |
|---|---|---|
|
|
Identifier of the dialog to be transferred (master). Passed as part of the Endpoint URI. Used as a parameter when sending a command from a script by the Operation component. When sending a command from a script there are other ways to specify the dialog alternative to this one. All dialog specification methods are listed below in descending priority order with a brief description. For details see the call search operation parameters.
|
|
|
Target conference room number. Specified without the feature code prefix. Optional parameter. If absent, a conference room number is generated. Other subscriber participants, knowing the room number, can enter it via routing if the 'referto' parameter is set and consists of digits, and if routing rules and feature code rules make this number reachable through the conference feature code. Does not require an featurecode of type |
|
|
Number or username of the subscriber on whose behalf the transfer to the conference room should be performed. Optional parameter. Default value: If the 'by' parameter is passed and 'referto' is not, an ad-hoc conference is created with a room number allowing the owner participant to end the conference or participant sessions using an featurecode of type |
|
|
Response return mode. The larger the value, the later the response is sent and the more context information it contains. Possible variants:
Default |
|
|
Label bound to the replacing call and then to the transferred call. Not assigned by default. |
SWITCHCONF /rest/v1/uc/calls/rDlg-002-Maw6qN HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"referto":"*99358",
"by":"sip3",
"response_mode": 4
}
Response
| Field | Description |
|---|---|
|
Identifier of the dialog to be converted into a conference. Matches the endpoint identifier or is passed unchanged from the request parameters. |
|
String with the number used for transfer to the conference. Indicates the system-generated full number with prefix, or the one specified in the request |
|
Final operation result. Value variants. |
|
Identifier of the conference to which subscribers were redirected. |
|
Call-Id of the initiating automatic IVR1→X call (differs from target dialog leg CallIds with the conference). Always present. |
|
Call-Id of the call received by the system from subscriber Y to subscriber Z after processing the REFER SIP request. This is the |
|
Response-Line of the last response received from subscriber Z on which the request response is based. May be absent for some unsuccessful operation results. |
|
Target Y→Z dialog identifier. May be absent for some unsuccessful operation results. May also be absent if dialog duration is 0 seconds. |
|
Call-Id of the initiating automatic IVR2→Y call (differs from target dialog leg CallIds with the conference). Always present. |
|
Call-Id of the call received by the system from subscriber Y to subscriber Z after processing the REFER SIP request. This is the |
|
Response-Line of the last response received from subscriber Z on which the request response is based. May be absent for some unsuccessful operation results. |
|
Target Y→Z dialog identifier. May be absent for some unsuccessful operation results. May also be absent if dialog duration is 0 seconds. |
| Value | Description |
|---|---|
|
The response is formed at a stage where no problems were found for successful Y→Z dialog creation. 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 (the counterpart in the dialog) to an existing conference. This is an analog of the transfer to number operation with automatic conference search, computation, and substitution of the conference number for routing.
The operation is performed by launching a hidden service script that makes a prepared call to the specified subscriber with replacement of the specific specified dialog (the "Call" script component with Replaces and Referred-By headers set) and then transferring control to a specially prepared hidden IVR script with the "Transfer to number" component. The number of the discovered conference is substituted as the transfer number, as featurecode + confroomnum. If the transfer fails, the next component transfers the subscriber back to the transfer initiator number.
Process scheme: X→CONF (hold), X→Y | IVR→Y, IVR REFER CONF, Y→CONF.
The transfer is performed in the conference domain. If the request is executed in a domain other than the conference domain, an error is returned. This is possible if a subscriber from another domain participates in the conference and the conference is specified by reference to their dialog.
After successful completion the transferring subscriber X remains in conference hold mode. To return, they must take it off hold using their SIP device commands.
An alternative approach is to use the "Transfer to number" method, specifying the number by which a specific conference room is reachable.
Request
| Name | Type | Description |
|---|---|---|
|
|
Identifier of the dialog to be transferred to the conference. Passed as part of the Endpoint URI. Used as a parameter when sending a command from a script by the Operation component. When sending a command from a script there are other ways to specify the dialog alternative to this one. All dialog specification methods are listed below in descending priority order with a brief description. For details see the call search operation parameters.
|
|
|
Dialog side initiating the call transfer to the conference. Based on the value, the opposite side to be transferred is computed. It is sent the INVITE SIP request with Replaces from IVR and the subsequent REFER SIP request. |
|
|
Identifier of the dialog one of whose participants is the conference – the transfer destination. This is one of the possible ways to specify the conference that is the transfer target. There are other ways to specify the conference alternative to this one.
All conference specification methods are listed below in descending priority order with a brief description.
For details see the call search operation parameters with the
|
|
|
Response return mode. The larger the value, the later the response is sent and the more context information it contains. Possible variants:
Default |
|
|
Label bound to the replacing call and then to the transferred call. Not assigned by default. |
REFERCONF /rest/v1/uc/calls/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 (NOTIFY)
Implements software control of the subscriber device at the server initiative.
Sends a NOTIFY request with an event message to the specified subscriber device. In particular, it can be used to control the device according to the Cisco Broadsoft extension (https://pubhub.devnetcloud.com/media/broadsoft-docs/docs/pdf/BW-SIPAccessSideExtensionsInterfaceSpec.pdf) Depending on the message type the device may:
-
answer the call (
talk), -
switch to hold mode (
hold), -
leave hold mode (
talk), -
merge held subscribers into a phone-controlled conference (
conference) -
etc.
The operation is performed in call state for the called side (talk), or in dialog state for either side.
According to RFC3265, supported events are listed by the device in the Allow-Events header in the INVITE request or in the 1xx/2xx response.
If the device does not support the extension, it does not send the corresponding values in the header, and on this basis the server blocks sending the NOTIFY request.
Message sending 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 through the API and scripts. The set of supported extensions is determined by the device. The quality of extension support by devices is not guaranteed by the system. As a recommendation: use the method only optionally and when it is reliably known that all used devices support it and no other situation is expected.
Request
| Name | Type | Description |
|---|---|---|
|
|
Target dialog identifier. Passed as part of the Endpoint URI. Used as a parameter when sending a command from a script by the Operation component. When sending a command from a script there are other ways to specify the dialog alternative to this one. All dialog specification methods are listed below in descending priority order with a brief description. For details see the call search operation parameters.
|
|
|
Dialog side whose device is controlled, |
|
|
Event name for device control ( |
NOTIFY /rest/v1/uc/calls/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"callid": "4139247432@192.168.0.149",
"event": "talk"
}
Sending a DTMF signal to a leg (SEND_DTMF)
Sends DTMF characters to the specified leg of the specified dialog. Sequence sending is supported. The response arrives immediately, but a queue of individual character sending appears in the leg. The same queue is used when several requests arrive.
Allows specifying a DTMF character sequence including ' and ,. Each such character provides a 1-second pause in DTMF dialing.
Depending on the specified protocol (proto):
* sipinfo - sends an INFO request transmitting the DTMF character.
* rfc2833 - sends RTP packets according to RFC-2833.
Message sending is asynchronous; the final result is not reported. A successful response means only that the request or series of RTP packets was sent.
Request
| Name | Type | Description |
|---|---|---|
|
|
Target dialog identifier. Passed as part of the Endpoint URI. Used as a parameter when sending a command from a script by the Operation component. When sending a command from a script there are other ways to specify the dialog alternative to this one. All dialog specification methods are listed below in descending priority order with a brief description. For details see the call search operation parameters.
|
|
|
Dialog side to which the DTMF character should be sent, |
|
|
Alternative dialog side specification ( |
|
|
Flag for taking the other side relative to the specified one. |
|
|
DTMF character sending mode selection ( |
|
|
DTMF character to send ( |
SEND_DTMF /rest/v1/uc/calls/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"dtmf": "2",
"proto": "rfc2833",
"callid": "4139247432@192.168.0.149"
}
Starting/stopping speech transcription of one party (SETUP_ASR)
Enables/disables recording and speech-to-text recognition for the specified leg of the specified dialog.
A successful response to the enable operation means only that the request or series of RTP packets was sent.
When disabling the mode, the response is delayed for several seconds until the recognition session completes.
To receive result events as recognition proceeds, use the WebSocket API.
The mode works when the speech transcription subsystem is installed and configured (master domain, settings.record_asr_options)
Request
| Name | Type | Description |
|---|---|---|
|
|
Target dialog identifier. Passed as part of the Endpoint URI. Used as a parameter when sending a command from a script by the Operation component. When sending a command from a script there are other ways to specify the dialog alternative to this one. All dialog specification methods are listed below in descending priority order with a brief description. For details see the call search operation parameters.
|
|
|
Operation: |
|
|
Unique layer name specification. Several layers are supported simultaneously; specifying an existing layer replaces it. To stop recording and recognition, an existing layer must also be specified. |
|
|
Dialog side to be sent for transcription, |
|
|
Alternative dialog side specification ( |
|
|
Flag for taking the other side relative to the specified one. |
|
|
For the stop operation sets the mode of waiting for and returning the final text. If true (default), the response is delayed by 2-3 seconds. |
SETUP_ASR /rest/v1/uc/calls/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"layer": "default",
"side": "b"
}
Enabling/disabling (adding/removing) the dialog recording channel, and controlling the main recording pause (SETUP_RECORD)
Enables/disables the recording channel of the specified dialog. Also controls the main recording pause (for example, for receiving confidential information).
Request
| Name | Type | Description |
|---|---|---|
|
|
Target dialog identifier. Passed as part of the Endpoint URI. Used as a parameter when sending a command from a script by the Operation component. When sending a command from a script there are other ways to specify the dialog alternative to this one. All dialog specification methods are listed below in descending priority order with a brief description. For details see the call search operation parameters.
|
|
|
Operation:
|
|
|
Unique layer name specification. Applies only to 'add' and 'remove' operations. Default value - 'default'. Several layers are supported simultaneously; specifying an existing layer replaces it. To stop recording and recognition, an existing layer must also be specified. |
|
|
Dialog side to be recorded, |
|
|
Alternative dialog side specification ( |
|
|
Additional channel recording time. Applies only to the 'add' operation. Default value - 7200000 - exceeds the remaining conversation duration. After the time expires the additional recording channel is deleted automatically. |
SETUP_RECORD /rest/v1/uc/calls/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"layer": "default"
}
Enabling/disabling (adding/removing) the dialog playback channel (SETUP_PLAYER)
Adds/removes audio file playback to/from the dialog context. The file is played once from start to finish unless interrupted earlier by a stop command.
The played file does not enter the dialog recording, like a hold melody, since the dialog recording is built by mixing recordings of incoming RTP traffic from participant subscriber channels, to which playback channels do not belong.
Request
| Name | Type | Description |
|---|---|---|
|
|
Target dialog identifier. Passed as part of the Endpoint URI. Used as a parameter when sending a command from a script by the Operation component. When sending a command from a script there are other ways to specify the dialog alternative to this one. All dialog specification methods are listed below in descending priority order with a brief description. For details see the call search operation parameters.
|
|
|
Operation:
|
|
|
Unique layer name specification. Applies only to 'add' and 'remove' operations. Default value - 'default'. Several layers are supported simultaneously; specifying an existing layer replaces it. To stop the player, an existing layer must also be specified. |
|
|
Dialog side to be recorded, |
SETUP_PLAYER /rest/v1/uc/calls/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"layer": "recnotify",
"file": ":SYNC_COMMON/recnotify/default.wav"
}
Managing dialog labels (SETUP_BINDINGS)
Manages labels of the specified dialog.
Dialog labels are string values bound to specific conversations/dialogs, set via the API or scripts. Labels are available at any point in the conversation lifecycle until its completion. Labels are preserved on call transfer and passed to the new transferred conversation.
Service session binding in the contact center (name "seance_…") and the post call survey mechanism (name "PCS:…") are based on labels.
In the Operation script component, label management is available through a separate command group (labels).
Request
| Name | Type | Description |
|---|---|---|
|
|
Target dialog identifier. Passed as part of the Endpoint URI. Used as a parameter when sending a command from a script by the Operation component. When sending a command from a script there are other ways to specify the dialog alternative to this one. All dialog specification methods are listed below in descending priority order with a brief description. For details see the call search operation parameters.
|
|
|
Operation:
|
|
|
Label or label list specification. |
SETUP_BINDINGS /rest/v1/uc/calls/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"command": "add",
"label": ["aaa", "bbb"]
}
Stopping the hold melody (STOP_HOLD_MELODY)
Stops hold melody playback for the specified dialog.
Playback can be stopped once or for the entire dialog.
Request
| Name | Type | Description |
|---|---|---|
|
|
Identifier of the dialog being configured. Passed as part of the Endpoint URI. Used as a parameter when sending a command from a script by the Operation component. When sending a command from a script there are other ways to specify the dialog alternative to this one. All dialog specification methods are listed below in descending priority order with a brief description. For details see the call search operation parameters.
|
|
|
Operation:
|
STOP_HOLD_MELODY /rest/v1/uc/calls/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"mode": "once"
}
Setting a custom hold melody (SETUP_HOLD_MELODY)
Sets a custom hold melody for the specified dialog.
The melody is set by specifying a key code defined in the domain melody_on_hold settings with a reference to files or directories. The custom melody key set for the dialog can be reset by setting an empty value again. Reset restores the default hold melodies for the current session.
Until reset, the setting is preserved in all dialogs linked by transfers. It is the key that is preserved, not the melody. Moreover, if the call is transferred to another domain, the key is resolved to specific files on disk based on the settings of the domain of the subscriber who put the call on hold.
Request
| Name | Type | Description |
|---|---|---|
|
|
Identifier of the dialog being configured Passed as part of the Endpoint URI. Used as a parameter when sending a command from a script by the Operation component. When sending a command from a script there are other ways to specify the dialog alternative to this one. All dialog specification methods are listed below in descending priority order with a brief description. For details see the call search operation parameters.
|
|
|
Custom hold melody key (or directory or audio file list). For the melody to apply, the key must exist in the domain melody_on_hold settings of the subscriber who put the call on hold. |
SETUP_HOLD_MELODY /rest/v1/uc/calls/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8
{
"key": "insurance"
}
Terminating a call (DELETE)
Terminates the dialog. The server acts as the disconnect initiator for both subscribers (sends a BYE SIP request to both subscribers). If the dialog is in call state, a CANCEL SIP request is sent to all called subscribers.
In the current version termination is external in nature without indicating in callevents class events whether it is bound to party A or party B actions.
When the request is executed from a script and several dialogs are discovered, all of them are terminated.
See also
-
API /rest/v1/uc/calls_by_participation for managing a limited set of domain calls involving the authorized user.
-
API /rest/v1/uc/conferences for managing arbitrary domain conferences.
-
Script component Operation.
-
b2b role.
-
mware role.
-
callstore role.