Call management (calls)

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

GET

/rest/v1/uc/calls

Getting the call list (GET)

POST

/rest/v1/uc/calls

Initiating a new call (POST)

INVITE

/rest/v1/uc/calls

Initiating a new call (INVITE)

INVITEBYIVR

/rest/v1/uc/calls

Initiating a new call with IVR servicing (INVITEBYIVR)

LOOKUP

/rest/v1/uc/calls

Searching for a call identifier (LOOKUP)

TRANSCRIBE

/rest/v1/uc/calls

Searching for a call identifier (LOOKUP)

GET

/rest/v1/uc/calls/<id>

Getting call information (GET)

REFER

/rest/v1/uc/calls/<id>

Transferring a call to a number (REFER)

REFERREPLACES

/rest/v1/uc/calls/<id>

Transferring a call with replacement (REFERREPLACES)

SWITCHCONF

/rest/v1/uc/calls/<id>

Converting a call into a conference (SWITCHCONF)

REFERCONF

/rest/v1/uc/calls/<id>

Transferring a call to a conference (REFERCONF)

NOTIFY

/rest/v1/uc/calls/<id>

Sending a device control event (NOTIFY)

SEND_DTMF

/rest/v1/uc/calls/<id>

Sending a DTMF signal to a leg (SEND_DTMF)

SETUP_ASR

/rest/v1/uc/calls/<id>

Starting/stopping speech transcription of one party (SETUP_ASR)

SETUP_RECORD

/rest/v1/uc/calls/<id>

Enabling/disabling (adding/removing) the dialog recording channel, and controlling the main recording pause (SETUP_RECORD)

SETUP_PLAYER

/rest/v1/uc/calls/<id>

Enabling/disabling (adding/removing) the dialog playback channel (SETUP_PLAYER)

SETUP_BINDINGS

/rest/v1/uc/calls/<id>

Managing dialog labels (SETUP_BINDINGS)

STOP_HOLD_MELODY

/rest/v1/uc/calls/<id>

Stopping the hold melody (STOP_HOLD_MELODY)

SETUP_HOLD_MELODY

/rest/v1/uc/calls/<id>

Setting a custom hold melody (SETUP_HOLD_MELODY)

DELETE

/rest/v1/uc/calls/<id>

Terminating a call (DELETE)


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

Table 1. Request parameters
Name Type Description

filter

object

Filter by field values.

mask

str

List of fields to output. Available fields for output: acallid, callids, dialogid, esgdlg, esgcallid, inviteid, status, legs, localuri, remoteuri, site, startts, uris, opts.

offset

int

Offset in the list of resources to output.

limit

int

Maximum number of resources in the list.

order

array<object|str>

Resource sorting order in the list.

flat

bool

Conversion of composite fields to flat form.

countonly

bool

Return only the number of elements.

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

Table 2. Dialog fields:
Field Description

acallid

Call-Id of the dialog initiating side. Contained in the corresponding header of the initiating INVITE SIP request.

callids

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.

dialogid

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.

esgdlgid

Dialog identifier of the esg role. Has a non-empty value only if the dialog was created based on an external incoming call from a provider account.

Can be used as the service session identifier of the external subscriber, since the esg dialog does not change during call transfer.

esgcallid

CallId of the external subscriber hidden behind the esg role. Has a non-empty value only if the dialog was created based on an external incoming call from a provider account.

inviteid

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.

status

General dialog state. Value variants:

  • "forking" – call state. From initiation to the final 2xx response from the called side.

  • "dialog" – dialog state. After the final 2xx response from the called side until the dialog ends.

In fact the dialog state machine has many more states, but all fit into the general states.

legs

List of dialog legs. Every dialog always has exactly one initiator (calling side A) and an arbitrary number of called legs (side B) due to forking. In the general state status=forking:

  • the dialog may contain more than one called leg B;

  • called legs may be added and removed depending on the call routing process and its implementation for the specific dialog.

In the general state status=dialog the side B leg:

  • is present in a single instance;

  • represents the answering subscriber;

  • does not change until the dialog completes.

Each list element is an object.

localuri

String representation of the URI from the To header of the initiating INVITE SIP request (local URI of side A).

Format: "<sip:USERNAME@DOMAIN>", where USERNAME and DOMAIN strictly match the header values.

remoteuri

String representation of the URI from the From header of the initiating INVITE SIP request (remote URI of side A).

Format: "<sip:USERNAME@DOMAIN>", where USERNAME and DOMAIN strictly match the header values.

site

Name of the site whose servers serve the dialog.

startts

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

uris

List of all URIs participating in the call.

Each SIP user that is a dialog subscriber has two URIs, one specified via login and the other via phonenumber.

opts

Object with additional dialog parameters. Contains:

  • referred-by – Referred-By header value from the initiating INVITE SIP request.

  • replaces – Replaces header value from the initiating INVITE SIP request.

Table 3. Dialog leg fields in the legs field value:
Field Description

callid

Leg Call-Id. Contained in the corresponding header of the INVITE SIP request (received or sent).

expirets

Subscriber call time limit in milliseconds. Meaningful only for the side B leg.

localuri

String representation of the local URI.

For the side A leg – from the To header of the initiating INVITE SIP request; for the side B leg – from the From header of the sent INVITE SIP request.

Format: "<sip:USERNAME@DOMAIN>", where USERNAME and DOMAIN strictly match the header values.

remoteuri

String representation of the remote URI.

For the side A leg – from the From header of the initiating INVITE SIP request; for the side B leg – from the To header of the sent INVITE SIP request.

Format: "<sip:USERNAME@DOMAIN>", where USERNAME and DOMAIN strictly match the header values.

side

Dialog side code:

  • "a" – calling side;

  • "b" – called side.

Example response
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

Table 4. Request parameters
Name Type Description

mode

str

Mode for specifying the X side initiator of the created call.

Possible variants:

  • "number" – Call to a number (the from field contains a number). Used by default.

  • "sipuser" – Call to a user (the from field contains a login).

from

str

Depending on the mode (mode) - the calling subscriber X number or the SIP user account login.

to

str

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.

callerid

str

First call initiator number. Displayed to subscriber X. By default the from field value is used (call from oneself).

callername

str

First call initiator name. Default "callmanager".

calltimeout

int

First call timeout in seconds. Limits the standard call time. Default 30 sec.

binding

str

Label bound to the call. Not assigned by default.

response_mode

int

Response return mode. The larger the value, the later the response is sent and the more context information it contains.

Possible variants:

  • 0 – send the response immediately after initiating the IVR→X call. Sent almost instantly without waiting for responses from subscribers X and Y. The response contains only the CallId of the initiating IVR→X call.

  • 1 – send the response after receiving a preliminary response from X (100-199, IVR→X).

  • 2 – send the response after receiving the final response from X (200-699, IVR→X).

  • 3 – send the response after receiving a preliminary response from Y (101-199, X→Y). Response 100 is excluded since it is sent by the server, not the subscriber. Starting with this mode the call context contains target dialog information.

  • 4 – send the response after receiving the final response from Y (200-699, X→Y). Starting with this mode the response contains reliable information about X→Y connection success.

  • 5 - send the response after complete completion of the operation and all its processes (excluding the X→Y dialog itself, which may continue for several hours).

Default 3.

use_intercom

bool

Intercom mode switch for calling the subscriber. Disabled by default.

An intercom-type featurecode and a routing rule allowing its use must exist.
Example request
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

Table 5. Field description
Field Description

result

Final operation result. Value variants.

ivrcallid

Call-Id of the initiating automatic IVR→X call (differs from target dialog leg CallIds). Always present.

acallid

Call-Id of the call received by the system from subscriber X to subscriber Y after processing the REFER SIP request. This is the A leg Call-Id of the target X→Y dialog. May be absent for some unsuccessful operation results.

last_response

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.

dialogid

Target X→Y dialog identifier. May be absent for some unsuccessful operation results. May also be absent if dialog duration is 0 seconds.

Table 6. result field value variants
Value Description

"ok"

The response is formed at a stage where no problems were found for successful X→Y dialog creation. For example, for

  • response_mode=0 – the IVR script was successfully initialized for the IVR→X call.

  • response_mode=1 – a preliminary response was received from subscriber X (IVR→X).

  • response_mode=2 – the final 2xx response was received from subscriber X (IVR→X).

  • response_mode=3 – the final 2xx response was received from subscriber X (IVR→X), the X→Y call was initialized, and a preliminary 18x or final 2xx response was received from subscriber Y.

  • response_mode=4 – the final 2xx response was received from subscriber X (IVR→X), the X→Y call was initialized, and the final 2xx response was received from subscriber Y.

  • response_mode=5 – the X→Y dialog is established; after a small timeout the initiating processes are completed.

"rejected"

The IVR→X call failed (4xx-6xx), or the X→Y call failed (4xx-6xx). The failure response could be sent by either the server or the subscriber device.

If the failure response was received from subscriber X, the result contains no X→Y dialog information; the acallid, dialogid, last_response fields are absent. If the failure response was received from subscriber Y, the result contains acallid and last_response about the X→Y dialog and does not contain dialogid.

"redirected"

The IVR→X call ended with SIP-UA redirection (3xx), or the X→Y call ended with SIP-UA redirection (3xx).

The value is hypothetical since the server itself (the b2b role) handles 3xx redirections by automatically initiating alternative forks.

"timeout"

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 408 Timeout response.

"error"

No response was received from subscriber X, or another unexpected situation occurred.

The acallid, dialogid, last_response fields may be absent from the response.

"undefined"

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.

Example response
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 (INVITE)

The method is synonymous with POST.


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

Table 7. Request parameters
Name Type Description

to

str

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.

callerid

str

First call initiator number. Displayed to subscriber X. By default the from field value is used (call from oneself).

callername

str

First call initiator name. Default "callmanager".

calltimeout

int

First call timeout in seconds. Limits the standard call time. Default 30 sec.

use_intercom

bool

Intercom mode switch for calling the subscriber. Disabled by default.

An intercom-type featurecode and a routing rule allowing its use must exist.

binding

str

Label bound to the call. Not assigned by default. Inherited by all subsequent transferred calls.

headers

str

List of additional headers for the INVITE request as a string separated by line feed (CLCR).

response_mode

int

Response return mode. The larger the value, the later the response is sent and the more context information it contains.

Possible variants:

  • 0 – send the response immediately after initiating the IVR→X call. Sent almost instantly without waiting for responses from subscribers X and Y. The response contains only the CallId of the initiating IVR→X call.

  • 1 – send the response after receiving a preliminary response from X (100-199, IVR→X).

  • 2 – send the response after receiving the final response from X (200-699, IVR→X).

Default 2.

dtmf_proto

str

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:

  • rfc2833

  • sipinfo

scriptcode

str

IVR script code that should serve the subscriber.

key

str

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.

param

str

String placed in start parameter 2 of the IVR script.

Example request
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

Table 8. Field description
Field Description

result

Final operation result. Value variants.

ivrcallid

Call-Id of the initiating automatic IVR→X call (differs from target dialog leg CallIds). Always present.

sipcode

Code of the last response received from subscriber X on which the request response is based. May be absent for some unsuccessful operation results.

dialogid

Target IVR→X dialog identifier. May be absent for some unsuccessful operation results. May also be absent if dialog duration is 0 seconds.

Table 9. result field value variants
Value Description

"answered"

The response is formed at a stage where no problems were found for successful X→Y dialog creation. For example, for

  • response_mode=0 – the IVR script was successfully initialized for the IVR→X call.

  • response_mode=1 – a preliminary response was received from subscriber X (IVR→X).

  • response_mode=2 – the final 2xx response was received from subscriber X (IVR→X).

  • response_mode=3 – the final 2xx response was received from subscriber X (IVR→X), the X→Y call was initialized, and a preliminary 18x or final 2xx response was received from subscriber Y.

  • response_mode=4 – the final 2xx response was received from subscriber X (IVR→X), the X→Y call was initialized, and the final 2xx response was received from subscriber Y.

  • response_mode=5 – the X→Y dialog is established; after a small timeout the initiating processes are completed.

"rejected"

The IVR→X call failed (4xx-6xx), or the X→Y call failed (4xx-6xx). The failure response could be sent by either the server or the subscriber device.

If the failure response was received from subscriber X, the result contains no X→Y dialog information; the acallid, dialogid, last_response fields are absent. If the failure response was received from subscriber Y, the result contains acallid and last_response about the X→Y dialog and does not contain dialogid.

"redirected"

The IVR→X call ended with SIP-UA redirection (3xx), or the X→Y call ended with SIP-UA redirection (3xx).

The value is hypothetical since the server itself (the b2b role) handles 3xx redirections by automatically initiating alternative forks.

"timeout"

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 408 Timeout response.

"error"

No response was received from subscriber X, or another unexpected situation occurred.

The acallid, dialogid, last_response fields may be absent from the response.

"undefined"

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.

Example response
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

Table 10. Request parameters
Parameter Type Description

dialogid

str

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, "rDlg-002-6FpTv2".

inviteid

str

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 "660df330-0623-b465-6927-c00000000002".

callid

str

Search value.

Call Call-Id identifier. Arbitrary string value from the corresponding SIP message header of either dialog side.

For example, "3099649154@192.168.0.149".

uri

str

Search value.

SIP URI: "<sip:username@domain>". The value is formed based on From or To headers. Search is performed only by the Remote-URI of dialog legs.

from

str

Search value.

Phone number or SIP user login used as username.

May use the additional mode parameter:

  • "number" – search by phone number. That is, direct search by value in username, and also if a sipuser is found by the specified number, search by its login in username.

  • "sipuser" – search only by SIP user name. The SIP user with the specified login must exist; in this case search is by its login in username.

Default mode=number.

Dialogs are discovered where the specified subscriber of the current domain acts as one side. Search is performed similarly to uri, with username formed automatically. For a SIP user account, however it is specified, search is performed for both the number and the login.

sipuserid

str

Search value.

SIP user account identifier.

sipuserlogin

str

Search value.

SIP user account login.

sipuserphonenumber

str

Search value.

SIP user account phone number.

userid

str

Search value.

System user account identifier. If SIP user accounts are linked to a system user, dialogs are discovered where one of these SIP users is one of the subscribers.

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

Response

Example successful response
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8

[
  "rDlg-002-XPhrjh"
]
Example unsuccessful response
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "error_code": 1413,
  "error_message": "Dialog not found"
}

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

Table 11. Request parameters
Parameter Type Description

idconn

str

Macro identifier of the completed call. It can be discovered:

  • the 'connectionid' field from most cdr events callevents;

  • the 'id' field from ccs events ccsevents for connection;

  • the 'nativeID' field from the callcenter/connections/ArchiveConnections product layer collection.

reclink

str

String with the conversation recording location. Can be discovered:

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

Response

Example response
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8

{
  "result": "ok"
}

Getting call information (GET)

Returns dialog information.

Request

Table 12. Request parameters
Name Type Description

dialogid

str

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.

* dialogid – by dialog identifier. * inviteid – by the identifier of the call leading to the dialog. * callid – by the Call-Id of one of the dialog legs. * uri – by the URI of one of the dialog participants: "<sip:username@domain>". * from – by phone number or SIP user login. The additional mode parameter is used: "number" or "sipuser". * sipuserid – by SIP user account identifier. * sipuserlogin – by SIP user account login. * sipuserphonenumber – by SIP user account phone number. * userid – by system user account identifier.

mask

str

List of fields to output.

flat

bool

Conversion of composite fields to flat form.

Example request
GET /rest/v1/uc/calls/rDlg-002-484FD3 HTTP/1.1

Response

Returns an object with the dialog representation.

Table 13. Dialog fields:
Field Description

acallid

Call-Id of the dialog initiating side. Contained in the corresponding header of the initiating INVITE SIP request.

callids

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.

dialogid

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.

esgdlgid

Dialog identifier of the esg role. Has a non-empty value only if the dialog was created based on an external incoming call from a provider account.

Can be used as the service session identifier of the external subscriber, since the esg dialog does not change during call transfer.

esgcallid

CallId of the external subscriber hidden behind the esg role. Has a non-empty value only if the dialog was created based on an external incoming call from a provider account.

inviteid

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.

status

General dialog state. Value variants:

  • "forking" – call state. From initiation to the final 2xx response from the called side.

  • "dialog" – dialog state. After the final 2xx response from the called side until the dialog ends.

In fact the dialog state machine has many more states, but all fit into the general states.

legs

List of dialog legs. Every dialog always has exactly one initiator (calling side A) and an arbitrary number of called legs (side B) due to forking. In the general state status=forking:

  • the dialog may contain more than one called leg B;

  • called legs may be added and removed depending on the call routing process and its implementation for the specific dialog.

In the general state status=dialog the side B leg:

  • is present in a single instance;

  • represents the answering subscriber;

  • does not change until the dialog completes.

Each list element is an object.

localuri

String representation of the URI from the To header of the initiating INVITE SIP request (local URI of side A).

Format: "<sip:USERNAME@DOMAIN>", where USERNAME and DOMAIN strictly match the header values.

remoteuri

String representation of the URI from the From header of the initiating INVITE SIP request (remote URI of side A).

Format: "<sip:USERNAME@DOMAIN>", where USERNAME and DOMAIN strictly match the header values.

site

Name of the site whose servers serve the dialog.

startts

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

uris

List of all URIs participating in the call.

Each SIP user that is a dialog subscriber has two URIs, one specified via login and the other via phonenumber.

opts

Object with additional dialog parameters. Contains:

  • referred-by – Referred-By header value from the initiating INVITE SIP request.

  • replaces – Replaces header value from the initiating INVITE SIP request.

Table 14. Dialog leg fields in the legs field value:
Field Description

callid

Leg Call-Id. Contained in the corresponding header of the INVITE SIP request (received or sent).

expirets

Subscriber call time limit in milliseconds. Meaningful only for the side B leg.

localuri

String representation of the local URI.

For the side A leg – from the To header of the initiating INVITE SIP request; for the side B leg – from the From header of the sent INVITE SIP request.

Format: "<sip:USERNAME@DOMAIN>", where USERNAME and DOMAIN strictly match the header values.

remoteuri

String representation of the remote URI.

For the side A leg – from the From header of the initiating INVITE SIP request; for the side B leg – from the To header of the sent INVITE SIP request.

Format: "<sip:USERNAME@DOMAIN>", where USERNAME and DOMAIN strictly match the header values.

side

Dialog side code:

  • "a" – calling side;

  • "b" – called side.

Example response
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

Table 15. Request parameters
Name Type Description

dialogid

str

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.

  • dialogid – by dialog identifier.

  • inviteid – by the identifier of the call leading to the dialog.

  • callid – by the Call-Id of one of the dialog legs.

  • uri – by the URI of one of the dialog participants: "<sip:username@domain>".

  • from – by phone number or SIP user login. The additional mode parameter is used: "number" or "sipuser".

  • sipuserid – by SIP user account identifier.

  • sipuserlogin – by SIP user account login.

  • sipuserphonenumber – by SIP user account phone number.

  • userid – by system user account identifier.

by

str

Dialog side initiating the call transfer. SIP URI or Call-Id.

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.

referto

str

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_mode

int

Response return mode. The larger the value, the later the response is sent and the more context information it contains.

Possible variants:

  • 0 – send the response immediately after initiating the IVR→Y call. Sent almost instantly without waiting for responses from subscribers Y and Z. The response contains only the CallId of the initiating IVR→Y call.

  • 1 – send the response after receiving a preliminary response from Y (100-199, IVR→Y).

  • 2 – send the response after receiving the final response from Y (200-699, IVR→Y).

  • 3 – send the response after receiving a preliminary response from Z (101-199, Y→Z). Response 100 is excluded since it is sent by the server, not the subscriber. Starting with this mode the call context contains target dialog information.

  • 4 – send the response after receiving the final response from Z (200-699, Y→Z). Starting with this mode the response contains reliable information about Y→Z connection success.

  • 5 - send the response after complete completion of the operation and all its processes (excluding the Y→Z dialog itself, which may continue for several hours).

Default 3.

binding

str

Label bound to the replacing call and then to the transferred call. Not assigned by default.

Example request
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

Table 16. Field description
Field Description

dialogid

Identifier of the dialog to be transferred. Matches the endpoint identifier or is passed unchanged from the request parameters.

result

Final operation result. Value variants.

ivrcallid

Call-Id of the initiating automatic IVR→Y call (differs from target dialog leg CallIds). Always present.

new_acallid

Call-Id of the call received by the system from subscriber Y to subscriber Z after processing the REFER SIP request. This is the A leg Call-Id of the target Y→Z dialog. May be absent for some unsuccessful operation results.

new_last_response

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.

new_dialogid

Target Y→Z dialog identifier. May be absent for some unsuccessful operation results. May also be absent if dialog duration is 0 seconds.

Table 17. result field value variants
Value Description

"ok"

The response is formed at a stage where no problems were found for successful Y→Z dialog creation. For example, for

  • response_mode=0 – the IVR script was successfully initialized for the IVR→Y call.

  • response_mode=1 – a preliminary response was received from subscriber Y (IVR→Y).

  • response_mode=2 – the final 2xx response was received from subscriber Y (IVR→Y).

  • response_mode=3 – the final 2xx response was received from subscriber Y (IVR→Y), the Y→Z call was initialized, and a preliminary 18x or final 2xx response was received from subscriber Z.

  • response_mode=4 – the final 2xx response was received from subscriber Y (IVR→Y), the Y→Z call was initialized, and the final 2xx response was received from subscriber Z.

  • response_mode=5 – the Y→Z dialog is established; after a small timeout the initiating processes are completed.

"rejected"

The IVR→Y call failed (4xx-6xx), or the Y→Z call failed (4xx-6xx). The failure response could be sent by either the server or the subscriber device.

If the failure response was received from subscriber Y, the result contains no Y→Z dialog information; the acallid, dialogid, last_response fields are absent. If the failure response was received from subscriber Z, the result contains acallid and last_response about the Y→Z dialog and does not contain dialogid.

"redirected"

The IVR→Y call ended with SIP-UA redirection (3xx), or the Y→Z call ended with SIP-UA redirection (3xx).

The value is hypothetical since the server itself (the b2b role) handles 3xx redirections by automatically initiating alternative forks.

"timeout"

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 408 Timeout response.

"error"

No response was received from subscriber Y, or another unexpected situation occurred.

The acallid, dialogid, last_response fields may be absent from the response.

"undefined"

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.

Example response
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

Table 18. Call transfer parameters by dialogid.
Name Type Description

masterdialogid

str

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" prefix added.

  • masterdialogid – by dialog identifier.

  • masterinviteid – by the identifier of the call leading to the dialog.

  • mastercallid – by the Call-Id of one of the dialog legs.

  • masteruri – by the URI of one of the dialog participants: "<sip:username@domain>".

  • masterfrom – by phone number or SIP user login. The additional mode parameter is used: "number" or "sipuser".

  • mastersipuserid – by SIP user account identifier.

  • mastersipuserlogin – by SIP user account login.

  • mastersipuserphonenumber – by SIP user account phone number.

  • masteruserid – by system user account identifier.

masterby

str

Master dialog side initiating the call transfer. SIP URI or Call-Id.

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.

slavedialogid

str

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" prefix added.

  • slavedialogid – by dialog identifier.

  • slaveinviteid – by the identifier of the call leading to the dialog.

  • slavecallid – by the Call-Id of one of the dialog legs.

  • slaveuri – by the URI of one of the dialog participants: "<sip:username@domain>".

  • slavefrom – by phone number or SIP user login. The additional mode parameter is used: "number" or "sipuser".

  • slavesipuserid – by SIP user account identifier.

  • slavesipuserlogin – by SIP user account login.

  • slavesipuserphonenumber – by SIP user account phone number.

  • slaveuserid – by system user account identifier.

slaveby

str

Slave dialog side to be replaced. SIP URI or Call-Id.

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_mode

int

Response return mode. The larger the value, the later the response is sent and the more context information it contains.

Possible variants:

  • 0 – send the response immediately after initiating the IVR→Y call. Sent almost instantly without waiting for responses from subscribers Y and Q. The response contains only the CallId of the initiating IVR→Y call.

  • 1 – send the response after receiving a preliminary response from Y (100-199, IVR→Y).

  • 2 – send the response after receiving the final response from Y (200-699, IVR→Y).

  • 3 – send the response after receiving a preliminary response from Q (101-199, Y→Q). Response 100 is excluded since it is sent by the server, not the subscriber. Starting with this mode the call context contains target dialog information.

  • 4 – send the response after receiving the final response from Q (200-699, Y→Q). Starting with this mode the response contains reliable information about Y→Q connection success.

  • 5 - send the response after complete completion of the operation and all its processes (excluding the Y→Q dialog itself, which may continue for several hours).

Default 4.

binding

str

Label bound to the replacing call and then to the transferred replacing call. Not assigned by default.

Example request
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

Table 19. Field description
Field Description

masterdialogid

Identifier of the dialog to be transferred (master). Matches the endpoint identifier or is passed unchanged from the request parameters.

slavedialogid

Identifier of the dialog to be replaced (slave). Passed unchanged from the request parameters.

result

Final operation result. Value variants.

ivrcallid

Call-Id of the initiating automatic IVR→Y call (differs from target dialog leg CallIds). Always present.

new_acallid

Call-Id of the call received by the system from subscriber Y to subscriber Z after processing the REFER SIP request. This is the A leg Call-Id of the target Y→Z dialog. May be absent for some unsuccessful operation results.

new_last_response

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.

new_dialogid

Target Y→Z dialog identifier. May be absent for some unsuccessful operation results. May also be absent if dialog duration is 0 seconds.

Table 20. result field value variants
Value Description

"ok"

The response is formed at a stage where no problems were found for successful Y→Z dialog creation. For example, for

  • response_mode=0 – the IVR script was successfully initialized for the IVR→Y call.

  • response_mode=1 – a preliminary response was received from subscriber Y (IVR→Y).

  • response_mode=2 – the final 2xx response was received from subscriber Y (IVR→Y).

  • response_mode=3 – the final 2xx response was received from subscriber Y (IVR→Y), the Y→Q call was initialized, and a preliminary 18x or final 2xx response was received from subscriber Q.

  • response_mode=4 – the final 2xx response was received from subscriber Y (IVR→Y), the Y→Q call was initialized, and the final 2xx response was received from subscriber Q.

  • response_mode=5 – the Y→Q dialog is established; after a small timeout the initiating processes are completed.

"rejected"

The IVR→Y call failed (4xx-6xx), or the Y→Z call failed (4xx-6xx). The failure response could be sent by either the server or the subscriber device.

If the failure response was received from subscriber Y, the result contains no Y→Q dialog information; the acallid, dialogid, last_response fields are absent. If the failure response was received from subscriber Q, the result contains acallid and last_response about the Y→Q dialog and does not contain dialogid.

"redirected"

The IVR→Y call ended with SIP-UA redirection (3xx), or the Y→Q call ended with SIP-UA redirection (3xx).

The value is hypothetical since the server itself (the b2b role) handles 3xx redirections by automatically initiating alternative forks.

"timeout"

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 408 Timeout response.

"error"

No response was received from subscriber Y, or another unexpected situation occurred.

The acallid, dialogid, last_response fields may be absent from the response.

"undefined"

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.

Example response
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

Table 21. Request parameters
Name Type Description

dialogid

str

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.

  • dialogid – by dialog identifier.

  • inviteid – by the identifier of the call leading to the dialog.

  • callid – by the Call-Id of one of the dialog legs.

  • uri – by the URI of one of the dialog participants: "<sip:username@domain>".

  • from – by phone number or SIP user login. The additional mode parameter is used: "number" or "sipuser".

  • sipuserid – by SIP user account identifier.

  • sipuserlogin – by SIP user account login.

  • sipuserphonenumber – by SIP user account phone number.

  • userid – by system user account identifier.

referto

str

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

by

str

Number or username of the subscriber on whose behalf the transfer to the conference room should be performed.

Optional parameter. Default value: "callmanager".

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 stopconf. Otherwise the transfer is made to a regular conference room with the room number specified in the 'referto' field or a generated room number.

response_mode

int

Response return mode. The larger the value, the later the response is sent and the more context information it contains.

Possible variants:

  • 0 – send the response immediately after initiating the IVR1→X and IVR2→Y calls. Sent almost instantly without waiting for responses from subscribers X and Y. The response contains only the CallIds of the initiating IVR1→X and IVR2→Y calls.

  • 1 – send the response after receiving preliminary responses from X and Y (100-199, IVR1→X, IVR2→Y).

  • 2 – send the response after receiving final responses from X and Y (200-699, IVR1→X, IVR2→Y).

  • 3 – send the response after receiving preliminary responses from CONF (101-199, X→CONF, Y→CONF). Response 100 is excluded since it is sent by an edge server, not the conference. Starting with this mode the operation context contains information about target dialogs with the conference.

  • 4 – send the response after receiving final responses from CONF (200-699, X→CONF, Y→CONF). Starting with this mode the response contains reliable information about X→CONF and Y→CONF connection success.

  • 5 - send the response after complete completion of the operation and all its processes (excluding the X→CONF and Y→CONF dialogs themselves, which may continue for several hours).

Default 4.

binding

str

Label bound to the replacing call and then to the transferred call. Not assigned by default.

Example request
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

Table 22. Field description
Field Description

dialogid

Identifier of the dialog to be converted into a conference. Matches the endpoint identifier or is passed unchanged from the request parameters.

referto

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

result

Final operation result. Value variants.

confid

Identifier of the conference to which subscribers were redirected.

x_ivrcallid

Call-Id of the initiating automatic IVR1→X call (differs from target dialog leg CallIds with the conference). Always present.

x_new_acallid

Call-Id of the call received by the system from subscriber Y to subscriber Z after processing the REFER SIP request. This is the A leg Call-Id of the target Y→Z dialog. May be absent for some unsuccessful operation results.

x_new_last_response

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.

x_new_dialogid

Target Y→Z dialog identifier. May be absent for some unsuccessful operation results. May also be absent if dialog duration is 0 seconds.

y_ivrcallid

Call-Id of the initiating automatic IVR2→Y call (differs from target dialog leg CallIds with the conference). Always present.

y_new_acallid

Call-Id of the call received by the system from subscriber Y to subscriber Z after processing the REFER SIP request. This is the A leg Call-Id of the target Y→Z dialog. May be absent for some unsuccessful operation results.

y_new_last_response

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.

y_new_dialogid

Target Y→Z dialog identifier. May be absent for some unsuccessful operation results. May also be absent if dialog duration is 0 seconds.

Table 23. result field value variants
Value Description

"ok"

The response is formed at a stage where no problems were found for successful Y→Z dialog creation. For example, for

  • response_mode=0 – IVR scripts were successfully initialized for the IVR1→X and IVR2→Y calls.

  • response_mode=1 – preliminary responses were received from subscribers X and Y (IVR1→X, IVR2→Y).

  • response_mode=2 – final 2xx responses were received from subscribers X and Y (IVR1→X, IVR2→Y).

  • response_mode=3 – final 2xx responses were received from subscribers X and Y (IVR1→X, IVR2→Y), then X→CONF and Y→CONF calls were initialized, and preliminary 18x or final 2xx responses were received from CONF in both dialogs.

  • response_mode=4 – final 2xx responses were received from subscribers X and Y (IVR1→X, IVR2→Y), then X→CONF and Y→CONF calls were initialized, and final 2xx responses were received from CONF in both dialogs.

  • response_mode=5 – X→CONF and Y→CONF dialogs are established; after a small timeout the initiating processes are completed.

Example response
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

Table 24. Request parameters
Name Type Description

dialogid

str

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.

  • dialogid – by dialog identifier.

  • inviteid – by the identifier of the call leading to the dialog.

  • callid – by the Call-Id of one of the dialog legs.

  • uri – by the URI of one of the dialog participants: "<sip:username@domain>".

  • from – by phone number or SIP user login. The additional mode parameter is used: "number" or "sipuser".

  • sipuserid – by SIP user account identifier.

  • sipuserlogin – by SIP user account login.

  • sipuserphonenumber – by SIP user account phone number.

  • userid – by system user account identifier.

by

str

Dialog side initiating the call transfer to the conference. SIP URI or Call-Id.

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.

referdialogid

str

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 "refer" prefix added.

  • By specifying the dialog one of whose sides is the target conference:

    • referdialogid – by dialog identifier.

    • referinviteid – by the identifier of the call leading to the dialog.

    • refercallid – by the Call-Id of one of the dialog legs.

    • referuri – by the URI of one of the dialog participants: "<sip:username@domain>".

    • referfrom – by phone number or SIP user login. The additional mode parameter is used: "number" or "sipuser".

    • refersipuserid – by SIP user account identifier.

    • refersipuserlogin – by SIP user account login.

    • refersipuserphonenumber – by SIP user account phone number.

    • referuserid – by system user account identifier.

  • By directly specifying the conference:

    • referconfid – by conference identifier.

    • referconfroomnum – by conference room number.

    • referconfnumber – by the conference access phone number containing the featurecode prefix.

response_mode

int

Response return mode. The larger the value, the later the response is sent and the more context information it contains.

Possible variants:

  • 0 – send the response immediately after initiating the IVR→Y call. Sent almost instantly without waiting for responses from subscribers Y and CONF. The response contains only the CallId of the initiating IVR→Y call.

  • 1 – send the response after receiving a preliminary response from Y (100-199, IVR→Y).

  • 2 – send the response after receiving the final response from Y (200-699, IVR→Y).

  • 3 – send the response after receiving a preliminary response from Z (101-199, Y→CONF). Response 100 is excluded since it is sent by the server, not the conference SIP-UA. Starting with this mode the call context contains target dialog information.

  • 4 – send the response after receiving the final response from Z (200-699, Y→CONF). Starting with this mode the response contains reliable information about Y→CONF connection success.

  • 5 - send the response after complete completion of the operation and all its processes (excluding the Y→CONF dialog itself, which may continue for several hours).

Default 3.

binding

str

Label bound to the replacing call and then to the transferred call. Not assigned by default.

Example request
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

Example 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

Table 25. Request parameters
Name Type Description

dialogid

str

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.

  • dialogid – by dialog identifier.

  • inviteid – by the identifier of the call leading to the dialog.

  • callid – by the Call-Id of one of the dialog legs.

  • uri – by the URI of one of the dialog participants: "<sip:username@domain>".

  • from – by phone number or SIP user login. The additional mode parameter is used: "number" or "sipuser".

  • sipuserid – by SIP user account identifier.

  • sipuserlogin – by SIP user account login.

  • sipuserphonenumber – by SIP user account phone number.

  • userid – by system user account identifier.

callid

str

Dialog side whose device is controlled, Call-Id.

event

str

Event name for device control (talk,hold,conference,refer,check-sync,…​)

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

Response

Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "result": "ok",
  "dialogid": "rDlg-002-WOabz0"
}

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

Table 26. Request parameters
Name Type Description

dialogid

str

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.

  • dialogid – by dialog identifier.

  • inviteid – by the identifier of the call leading to the dialog.

  • callid – by the Call-Id of one of the dialog legs.

  • uri – by the URI of one of the dialog participants: "<sip:username@domain>".

  • from – by phone number or SIP user login. The additional mode parameter is used: "number" or "sipuser".

  • sipuserid – by SIP user account identifier.

  • sipuserlogin – by SIP user account login.

  • sipuserphonenumber – by SIP user account phone number.

  • userid – by system user account identifier.

callid

str

Dialog side to which the DTMF character should be sent, Call-Id.

side

str

Alternative dialog side specification (a - call initiator, b - call destination), or Call-Id.

opposite

bool

Flag for taking the other side relative to the specified one.

proto

str

DTMF character sending mode selection (rfc2833, sipinfo). Default sipinfo.

dtmf

str

DTMF character to send (0-9*#). Only character-by-character sending is supported.

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

Response

Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "result": "ok",
  "dialogid": "rDlg-002-WOabz0"
}

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

Table 27. Request parameters
Name Type Description

dialogid

str

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.

  • dialogid – by dialog identifier.

  • inviteid – by the identifier of the call leading to the dialog.

  • callid – by the Call-Id of one of the dialog legs.

  • uri – by the URI of one of the dialog participants: "<sip:username@domain>".

  • from – by phone number or SIP user login. The additional mode parameter is used: "number" or "sipuser".

  • sipuserid – by SIP user account identifier.

  • sipuserlogin – by SIP user account login.

  • sipuserphonenumber – by SIP user account phone number.

  • userid – by system user account identifier.

command

str

Operation: add (enable mode) or remove (disable mode).

layer

str

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.

callid

str

Dialog side to be sent for transcription, Call-Id.

side

str

Alternative dialog side specification (a - call initiator, b - call destination), or Call-Id.

opposite

bool

Flag for taking the other side relative to the specified one.

result_text

bool

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.

Example request
SETUP_ASR /rest/v1/uc/calls/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "layer": "default",
  "side": "b"
}

Response

Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "result": "ok",
  "dialogid": "rDlg-002-WOabz0",
  "layer": "default"
}

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

Table 28. Request parameters
Name Type Description

dialogid

str

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.

  • dialogid – by dialog identifier.

  • inviteid – by the identifier of the call leading to the dialog.

  • callid – by the Call-Id of one of the dialog legs.

  • uri – by the URI of one of the dialog participants: "<sip:username@domain>".

  • from – by phone number or SIP user login. The additional mode parameter is used: "number" or "sipuser".

  • sipuserid – by SIP user account identifier.

  • sipuserlogin – by SIP user account login.

  • sipuserphonenumber – by SIP user account phone number.

  • userid – by system user account identifier.

command

str

Operation:

  • add - enable an additional recording channel.

  • remove - disable the additional recording channel.

  • pause - pause the main conversation recording. Only an active recording can be paused. Initially recording is active if recording rules in at least one of the conversation participant domains activate built-in recording. Silence is placed in the recording file during the pause. The pause command affects only built-in platform recording and does not affect external streaming recording (e.g., SIPREC).

  • resume - resume the main conversation recording from pause. Allowed if the conversation recording was previously paused. Also allowed if none of the participant domains activates conversation recording by rules, provided recording is disabled by an applied recording rule (not because no suitable recording rule exists) and that rule allows resuming and pausing. In the latter case, recording is placed in the storage defined by the recording rule that disabled recording and starts from the moment recording is enabled by the current command. If at the start of a cross-domain call recording is disabled for one domain and enabled for the other by the recording rule, the resume command does not activate recording for the first domain.

layer

str

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.

callid

str

Dialog side to be recorded, Call-Id. Applies only to the 'add' operation.

side

str

Alternative dialog side specification (a - call initiator, b - call destination), or Call-Id. Applies only to the 'add' operation.

timeout

int

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.

Example request
SETUP_RECORD /rest/v1/uc/calls/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "layer": "default"
}

Response

Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "result": "ok",
  "dialogid": "rDlg-002-WOabz0",
  "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

Table 29. Request parameters
Name Type Description

dialogid

str

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.

  • dialogid – by dialog identifier.

  • inviteid – by the identifier of the call leading to the dialog.

  • callid – by the Call-Id of one of the dialog legs.

  • uri – by the URI of one of the dialog participants: "<sip:username@domain>".

  • from – by phone number or SIP user login. The additional mode parameter is used: "number" or "sipuser".

  • sipuserid – by SIP user account identifier.

  • sipuserlogin – by SIP user account login.

  • sipuserphonenumber – by SIP user account phone number.

  • userid – by system user account identifier.

command

str

Operation:

  • add - Adds an additional player.

  • remove - Removes the specified player.

layer

str

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.

callid

str

Dialog side to be recorded, Call-Id. Applies only to the 'add' operation.

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

Response

Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "result": "ok",
  "dialogid": "rDlg-002-WOabz0",
  "layer": "recnotify"
}

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

Table 30. Request parameters
Name Type Description

dialogid

str

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.

  • dialogid – by dialog identifier.

  • inviteid – by the identifier of the call leading to the dialog.

  • callid – by the Call-Id of one of the dialog legs.

  • uri – by the URI of one of the dialog participants: "<sip:username@domain>".

  • from – by phone number or SIP user login. The additional mode parameter is used: "number" or "sipuser".

  • sipuserid – by SIP user account identifier.

  • sipuserlogin – by SIP user account login.

  • sipuserphonenumber – by SIP user account phone number.

  • userid – by system user account identifier.

command

str

Operation:

  • get - returns all dialog labels as an array in the 'labels' field.

  • set - replaces the existing label set with the specified ones. Requires the 'label' parameter - a string or list of strings.

  • add - adds the specified labels. Requires the 'label' parameter - a string or list of strings.

  • remove - removes the specified labels. Requires the 'label' parameter - a string or list of strings.

  • clean - clears all dialog labels.

  • contains - checks for the specified label in the dialog. Requires the 'label' parameter - a string. Returns true or false in the 'contains' field.

label

str or array<str>

Label or label list specification.

Example request
SETUP_BINDINGS /rest/v1/uc/calls/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "command": "add",
  "label": ["aaa", "bbb"]
}

Response

Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "result": "ok",
  "dialogid": "rDlg-002-WOabz0"
}

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

Table 31. Request parameters
Name Type Description

dialogid

str

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.

  • dialogid – by dialog identifier.

  • inviteid – by the identifier of the call leading to the dialog.

  • callid – by the Call-Id of one of the dialog legs.

  • uri – by the URI of one of the dialog participants: "<sip:username@domain>".

  • from – by phone number or SIP user login. The additional mode parameter is used: "number" or "sipuser".

  • sipuserid – by SIP user account identifier.

  • sipuserlogin – by SIP user account login.

  • sipuserphonenumber – by SIP user account phone number.

  • userid – by system user account identifier.

mode

str

Operation:

  • temporary - stops the current hold melody if the call is on hold, otherwise returns an error. Used by default.

  • once - stops the current hold melody if the call is on hold, or otherwise prevents hold melody playback for the upcoming hold.

  • permanent - stops the current hold melody and prevents hold melody playback for all future holds of the current dialog.

Example request
STOP_HOLD_MELODY /rest/v1/uc/calls/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "mode": "once"
}

Response

Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "result": "ok",
  "dialogid": "rDlg-002-WOabz0"
}

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

Table 32. Request parameters
Name Type Description

dialogid

str

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.

  • dialogid – by dialog identifier.

  • inviteid – by the identifier of the call leading to the dialog.

  • callid – by the Call-Id of one of the dialog legs.

  • uri – by the URI of one of the dialog participants: "<sip:username@domain>".

  • from – by phone number or SIP user login. The additional mode parameter is used: "number" or "sipuser".

  • sipuserid – by SIP user account identifier.

  • sipuserlogin – by SIP user account login.

  • sipuserphonenumber – by SIP user account phone number.

  • userid – by system user account identifier.

key

str

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.

Example request
SETUP_HOLD_MELODY /rest/v1/uc/calls/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "key": "insurance"
}

Response

Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "result": "ok",
  "dialogid": "rDlg-002-WOabz0"
}

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.

Request

Example request
DELETE /rest/v1/uc/calls/rDlg-002-9dEcfh HTTP/1.1

Response

Example successful response
HTTP/1.1 200 Ok
Content-Type: application/json; charset=utf-8

{
  "dialogid": "rDlg-002-9dEcfh"
}
Example unsuccessful response
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "error_code": 1413,
  "error_message": "Dialog not found"
}

See also