Managing your calls (calls)

Overview

Manages existing active calls (B2B dialogs) through API commands (without using initiatives from SIP devices).

Any calls are available for management: initiated both via API and from SIP devices and services SIP-UA. Unlike the /rest/v1/uc/calls API, the current endpoint grants access only to conversations where one of the participants is the SIP-user account, belonging to the user who is making the API request.

Servicing of requests is performed by the role mware.

The role is required for the job callstore.

Requests

HTTP verb Endpoint Description

GET

/rest/v1/user/sip/calls

Retrieving a list of calls (GET)

POST

/rest/v1/user/sip/calls

Initiating a new call (POST)

INVITE

/rest/v1/user/sip/calls

Initiating a new call (INVITE)

INVITEBYIVR

/rest/v1/user/sip/calls

[invitebyivr]

LOOKUP

/rest/v1/user/sip/calls

Searching for call ID (LOOKUP)

GET

/rest/v1/user/sip/calls/<id>

Receiving information about the call (GET)

REFER

/rest/v1/user/sip/calls/<id>

Transferring a call to a number (REFER)

REFERREPLACES

/rest/v1/user/sip/calls/<id>

Transferring a spoofed call (REFERREPLACES)

SWITCHCONF

/rest/v1/user/sip/calls/<id>

Converting a call to a conference (SWITCHCONF)

REFERCONF

/rest/v1/user/sip/calls/<id>

Transferring a call to a conference (REFERCONF)

NOTIFY

/rest/v1/user/sip/calls/<id>

Sending a device control event to one of the parties (NOTIFY)

SEND_DTMF

/rest/v1/user/sip/calls/<id>

Sending a DTMF character to one of the parties (SEND_DTMF)

SETUP_ASR

/rest/v1/user/sip/calls/<id>

Start/stop stenography by one of the parties (SETUP_ASR)

SETUP_RECORD

/rest/v1/user/sip/calls/<id>

Start/stop (add/remove) a dialog recording channel (SETUP_RECORD)

SETUP_BINDINGS

/rest/v1/user/sip/calls/<id>

Managing dialog labels (SETUP_BINDINGS)

DELETE

/rest/v1/user/sip/calls/<id>

Ending a call (DELETE)

Retrieving a list of calls (GET)

Returns a list of active dialogs within the current domain.

Any dialog has two parties: the calling party (A) and the called party (B). There may be one or more subscribers representing the `B' side, depending on the state of the dialog.

A dialog belongs to a domain if at least one of its subscribers (dialog arms) belongs to the domain (is a provider account, a SIP user, a conference, or a script) IVR).

The result of the query execution undergoes additional filtering. Only those dialogs, one of the participants of which is an authorized user (through any of the accounts belonging to him/her) are returned sipuser).

Request

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

limit

int

The maximum number of resources in the list.

order

array<object|str>

The sort order of the resources in the list.

flat

bool

Conversion to flat form of composite fields.

countonly

bool

Returns only the number of elements.

Details about the format of GET request parameters

Request example
GET /rest/v1/user/sip/calls?offset=0&limit=1 HTTP/1.1

Response

Returns a list of objects, each of which represents a separate dialog. The composition of returned fields is limited: acallid, callids, dialogid, esgdlg, esgcallid, inviteid, status, legs, localuri, remoteuri, site, startts, uris, opts. If you specify other fields in the mask parameter, they will be ignored.

Table 2. Dialog Fields:
Field Description

acallid

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

callids

A list of all Call-Id’s of active dialog participants. Each side of the dialog has its own Call-Id, each called fork has a unique Call-Id.

dialogid

Active dialog identifier used in the formation of the endpoint. Unique in rantime, but is not globally unique and may be repeated after some time within the same system.

esgdlgid

Role dialog identifier esg. Has a non-empty value only if the dialog is created based on an external incoming call from the provider’s account.

Can be used as an external caller service session identifier, since the esg dialog is not changed during call transfer.

esgcallid

CallId an external caller hidden behind the role esg. Has a non-empty value only if the dialog is created based on an external incoming call from the provider’s account.

inviteid

Globally unique identifier of the call leading to the dialog. It is formed when an INVITE SIP request is received in the system and exists until the dialog is terminated. Present in all CDR class events callevents.

status

The general state of the dialog. Value options:

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

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

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

legs

List of dialog shoulders. Each dialog always has exactly one initiator (calling party A) and an arbitrary number of called arms (party B) due to forking. In a general state of status=forking:

  • a dialog can contain more than one called arm B;

  • called shoulders can be added and removed depending on the call routing process and its implementation for a particular dialog.

In the general state status=dialog the shoulder of the side B:

  • singular;

  • represents the subscriber who answered;

  • does not change until the dialog is terminated.

Each element of the list is object.

localuri

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

The format is "<sip:USERNAME@DOMAIN>", where USERNAME and DOMAIN strictly correspond to the values in the header.

remoteuri

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

The format is "<sip:USERNAME@DOMAIN>", where USERNAME and DOMAIN strictly correspond to the values in the header.

site

The name of the site whose servers serve the dialog.

startts

Timestamp of the time the initiating SIP request INVITE arrives in the system. Is a representation of a point in time and can be converted to a specific date in any time zone.

For example, 1571743463336.

uris

A list of all URIs involved in the call.

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

opts

An object with additional dialog parameters. Contains:

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

  • replaces – Replaces header value from the initiating SIP request INVITE.
Table 3. Dialog shoulder fields in the field value legs:
Field Description

callid

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

expirets

Limits the call time of the caller in milliseconds. Valid only for the shoulder side B.

localuri

String representation local URI.

For the shoulder of side A - from the To header of the initiating SIP request INVITE, for the shoulder of side B - from the From header of the sending SIP request INVITE.

The format is "<sip:USERNAME@DOMAIN>", where USERNAME and DOMAIN strictly correspond to the values in the header.

remoteuri

String representation remote URI.

For arm side A - from the From header of the initiating SIP request INVITE, for arm side B - from the To header of the sending SIP request INVITE.

The format is "<sip:USERNAME@DOMAIN>", where USERNAME and DOMAIN strictly correspond to the values in the header.

side

Code side of the dialog:

  • "a" – caller;

  • "b" – called party.
Response example
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "acallid": "3113017065@192.168.0.149",
    "callids": [
      "rB2-002-484FD3-01-3113017065@192.168.0.149",
      "3113017065@192.168.0.149"
    ],
    "dialogid": "rDlg-002-484FD3",
    "esgdlg": "",
    "esgcallid": "",
    "inviteid": "357924f1-0623-b685-c105-b80000000002",
    "legs": [
      {
        "callid": "3113017065@192.168.0.149",
        "expirets": "undefined",
        "localuri": "<sip:sip3@test.rootdomain.ru>",
        "remoteuri": "<sip:sip2@test.rootdomain.ru>",
        "side": "a"
      },
      {
        "callid": "rB2-002-484FD3-01-3113017065@192.168.0.149",
        "expirets": 30000,
        "localuri": "<sip:12@test.rootdomain.ru>",
        "remoteuri": "<sip:sip3@test.rootdomain.ru>",
        "side": "b"
      }
    ],
    "localuri": "<sip:sip3@test.rootdomain.ru>",
    "opts": {
      "referred-by": "<sip:sip1@test.rootdomain.ru>"
    },
    "remoteuri": "<sip:sip2@test.rootdomain.ru>",
    "site": "SITE1",
    "startts": 1571747612067,
    "status": "forking",
    "uris": [
      "<sip:12@test.rootdomain.ru>",
      "<sip:sip3@test.rootdomain.ru>",
      "<sip:sip3@test.rootdomain.ru>",
      "<sip:sip2@test.rootdomain.ru>"
    ]
  }
]

Initiating a new call (POST)

Initiates an intercom call to subscriber X (number in the from field), after answering it transfers it (SIP REFER request) to subscriber Y (number in the from field) to). To initiate intercom-call mode, a featurecode of the appropriate type must exist in the system and be available in the routing for at least the subscribers towards themselves as well as the subscriber 100 (callmanager).

The operation is carried out by running a hidden service script that performs a prepared call to the initiator (script component Outgoing call) with transfer of control to a specially prepared hidden IVR script with the component Transfer to number. The specified number is substituted as the number to be transferred to.

Process Flowchart: IVR→X, IVR REFER Y, X→Y.

The request is executed asynchronously. The response to the request is returned at the moment defined by the parameter response_mode. The context of the call initiation process is gradually populated with call data as the call progresses. The data content of the response corresponds to when it is returned - the later point in the process is selected, the more data and the more accurate the result.

CDR events of the target call can be retrieved from the system’s event subscription interface.

The subscriber, on whose behalf an outgoing call is ordered, after picking up the handset hears all the KPV signals of the organized outgoing call.

The request is pre-filtered. An authorized user must be the initiator of the new call to be allowed to execute. That is, the specified value of the "from" parameter referred to an authorized user (via any of the accounts owned by the user) sipuser).

Request

Table 4. Request parameters
Name Type Description

mode

str

The mode of specifying the X side of the initiator of the call to be created.

Possible options:

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

  • "sipuser" – A call to the user (the from field contains the login).

from

str

Depending on the mode (mode), the caller number X, or the account login SIP-user.

to

str

Called party number Y. Allows the characters “'” and “,” to be specified. The first such character allocates the remaining sequence as a DTMF pre-dial after the response is received, and each subsequent such character provides a 1-second pause in the set DTMF.

callerid

str

The number of the initiator of the first call. Displayed to subscriber X. The default value of the from field is used (call from yourself).

callername

str

The name of the initiator of the first call. Default "callmanager".

calltimeout

int

Timeout of the first call in seconds. This is a limitation of the default call time. The default is 30 sec.

binding

str

A label attached 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 contextual information the response contains.

Possible options:

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

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

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

  • 3 – send a response after receiving a preliminary response from Y (101-199, X→Y). The 100 response is excluded because it is sent by the server and not by the caller. Starting from this mode, the context of the call contains information about the target dialog.

  • 4 – send a response after receiving a final response from Y (200-699, X→Y). From this mode onwards, the response contains valid information about the success of the connection X→Y.

  • 5 - send a response after the operation and all its processes are complete (excluding the X→Y dialog itself, which may last several hours).

Default 3.

use_intercom

bool

Switches the intercom mode for calling a subscriber. The default setting is off.

There must be an ficacode with type intercom and an routing rule allowing it.
Request example
POST /rest/v1/user/sip/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

The final result of the operation. Value options.

ivrcallid

Call-Id initiating automatic IVR→X call (different from the CallId of the target dialog shoulders). Present in any case.

acallid

Call-Id call received in the system from subscriber X to subscriber Y after processing SIP REFER request. This is the Call-Id of the A arm of the target X→Y dialog. It may not be present for some unsuccessful operation results.

last_response

Response-Line the last received response from subscriber Y, based on the results of which a response to the request is generated. In case of some unsuccessful results of the operation, it may be absent.

dialogid

The identifier of the target X→Y dialog. It may be absent in case of some unsuccessful results of the operation. It may also be absent if the dialog duration is 0 seconds.
Table 6. Field value options result
Significance Description

"ok"

The response is generated at a stage where no problems are identified to successfully create an X→Y dialog. For example, for

  • response_mode=0 – IVR script is successfully initialized for calling IVR→X.

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

  • response_mode=2 – received a final response of `2xx' from the subscriber X (IVR→X).

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

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

  • response_mode=5 – X→Y dialog is set, after some small timeout initializing processes are completed.

"rejected"

The IVR→X call failed (4xx-6xx), or the X→Y call failed (4xx-6xx). Both the server and the subscriber device could have sent the failed response.

In case an unsuccessful response is received from subscriber X, the result does not contain information about the dialog X→Y, the fields acallid, dialogid, last_response are missing. In case an unsuccessful response is received from subscriber Y, the result contains the acallid and last_response fields about the X→Y dialog and does not contain the dialogid.

"redirected"

An IVR→X call ended with a SIP-UA (3xx) forwarding, or an X→Y call ended with a SIP-UA (3xx) forwarding SIP-UA (3xx).

The value is hypothetical, since 3xx redirects are handled by the server itself (role b2b), automatically initiating alternate forks.

"timeout"

The IVR→X call after the pre-reply has timed out.

The value is hypothetical because if there is no final response, the server (role b2b), terminates the call by automatically emulating the response 408 Timeout.

"error"

No response from subscriber X, or other unexpected situation.

Fields may be missing from the response acallid, dialogid, last_response.

"undefined"

Subscriber X successfully answered the IVR→X call, call status X→Y is unknown due to missing or unknown content of NOTIFY SIP requests in the dialog served by the REFER.
Response example
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.

Searching for call ID (LOOKUP)

Searches for a resource (active dialog) by the specified key.

A list of identifiers of detected dialogs matching the search conditions is returned.

The search fields are applied one by one in descending order of priority in the table below. Search fields contain in the description "Search value". Multiple returns are possible, for example, in the case of a search by SIP-user login, if the user participates in several dialogs.

The result of the query execution undergoes additional filtering. Only those dialogs where one of the participants is an authorized user (through any of the accounts belonging to him/her) are detected sipuser).

Request

Table 7. Request parameters
Parameter Type Description

dialogid

str

Search Value.

Dialog identifier used during dialog formation endpoint. Unique in rantime, but is not globally unique and may be repeated after some time within the same system.

For example, "rDlg-002-6FpTv2".

inviteid

str

Search Value.

Globally unique identifier of the call leading to the dialog. It is formed when an INVITE SIP request is received in the system and exists until the dialog is terminated. Present in all CDR class events callevents.

For example "660df330-0623-b465-6927-c00000000002".

callid

str

Search Value.

Call Identifier Call-Id. An arbitrary string value from the corresponding SIP message header of either side of the dialog.

For example, "3099649154@192.168.0.149".

uri

str

Search Value.

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

from

str

Search Value.

Phone number or login SIP user used as the username.

Can use an additional parameter mode:

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

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

Default mode=number.

Dialogs are detected where one of the parties is a specified subscriber of the current domain. The search is performed similarly to uri, with username generated automatically. For a SIP user account, however specified, the search is performed for both the number and the login.

sipuserid

str

Search Value.

Account Identifier SIP-user.

sipuserlogin

str

Search Value.

Account login SIP-user.

sipuserphonenumber

str

Search Value.

Phone number of the account SIP user.

userid

str

Search Value.

The account ID of the user of the system. If there is a binding of SIP-user accounts to a system user, dialogs are detected, where one of these SIP users is one of the subscribers.
Request example
LOOKUP /rest/v1/user/sip/calls HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "callid": "rB2-002-XPhrjh-01-3587482024@192.168.0.146"
}

Response

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

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

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

Receiving information about the call (GET)

Returns information about the dialog.

The request is pre-filtered. To be allowed to execute, the specified dialog must have as one of its participants an authorized user (through any of the accounts belonging to the user) sipuser).

Request

Table 8. Request parameters
Name Type Description

dialogid

str

Identifier of the dialog to be translated (master).

Passed on as part of Endpoint URI.

mask

str

A list of fields to output.

flat

bool

Conversion to flat form of composite fields.
Request example
GET /rest/v1/user/sip/calls/rDlg-002-484FD3 HTTP/1.1

Response

Returns an object with a dialog representation.

Table 9. Dialog Fields:
Field Description

acallid

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

callids

A list of all Call-Id’s of active dialog participants. Each side of the dialog has its own Call-Id, each called fork has a unique Call-Id.

dialogid

Active dialog identifier used in the formation of the endpoint. Unique in rantime, but is not globally unique and may be repeated after some time within the same system.

esgdlgid

Role dialog identifier esg. Has a non-empty value only if the dialog is created based on an external incoming call from the provider’s account.

Can be used as an external caller service session identifier, since the esg dialog is not changed during call transfer.

esgcallid

CallId an external caller hidden behind the role esg. Has a non-empty value only if the dialog is created based on an external incoming call from the provider’s account.

inviteid

Globally unique identifier of the call leading to the dialog. It is formed when an INVITE SIP request is received in the system and exists until the dialog is terminated. Present in all CDR class events callevents.

status

The general state of the dialog. Value options:

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

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

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

legs

List of dialog shoulders. Each dialog always has exactly one initiator (calling party A) and an arbitrary number of called arms (party B) due to forking. In a general state of status=forking:

  • a dialog can contain more than one called arm B;

  • called shoulders can be added and removed depending on the call routing process and its implementation for a particular dialog.

In the general state status=dialog the shoulder of the side B:

  • singular;

  • represents the subscriber who answered;

  • does not change until the dialog is terminated.

Each element of the list is object.

localuri

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

The format is "<sip:USERNAME@DOMAIN>", where USERNAME and DOMAIN strictly correspond to the values in the header.

remoteuri

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

The format is "<sip:USERNAME@DOMAIN>", where USERNAME and DOMAIN strictly correspond to the values in the header.

site

The name of the site whose servers serve the dialog.

startts

Timestamp of the time the initiating SIP request INVITE arrives in the system. Is a representation of a point in time and can be converted to a specific date in any time zone.

For example, 1571743463336.

uris

A list of all URIs involved in the call.

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

opts

An object with additional dialog parameters. Contains:

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

  • replaces – Replaces header value from the initiating SIP request INVITE.
Table 10. Shoulder fields of the dialog in the field value legs:
Field Description

callid

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

expirets

Limits the call time of the caller in milliseconds. Valid only for the shoulder side B.

localuri

String representation local URI.

For the shoulder of side A - from the To header of the initiating SIP request INVITE, for the shoulder of side B - from the From header of the sending SIP request INVITE.

The format is "<sip:USERNAME@DOMAIN>", where USERNAME and DOMAIN strictly correspond to the values in the header.

remoteuri

String representation remote URI.

For arm side A - from the From header of the initiating SIP request INVITE, for arm side B - from the To header of the sending SIP request INVITE.

The format is "<sip:USERNAME@DOMAIN>", where USERNAME and DOMAIN strictly correspond to the values in the header.

side

Code side of the dialog:

  • "a" – caller;

  • "b" – called party.
Response example
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "acallid": "3113017065@192.168.0.149",
  "callids": [
    "rB2-002-484FD3-01-3113017065@192.168.0.149",
    "3113017065@192.168.0.149"
  ],
  "dialogid": "rDlg-002-484FD3",
  "esgdlg": "",
  "esgcallid": "",
  "inviteid": "357924f1-0623-b685-c105-b80000000002",
  "legs": [
    {
      "callid": "3113017065@192.168.0.149",
      "expirets": "undefined",
      "localuri": "<sip:sip3@test.rootdomain.ru>",
      "remoteuri": "<sip:sip2@test.rootdomain.ru>",
      "side": "a"
    },
    {
      "callid": "rB2-002-484FD3-01-3113017065@192.168.0.149",
      "expirets": 30000,
      "localuri": "<sip:12@test.rootdomain.ru>",
      "remoteuri": "<sip:sip3@test.rootdomain.ru>",
      "side": "b"
    }
  ],
  "localuri": "<sip:sip3@test.rootdomain.ru>",
  "opts": {
    "referred-by": "<sip:sip1@test.rootdomain.ru>"
  },
  "remoteuri": "<sip:sip2@test.rootdomain.ru>",
  "site": "SITE1",
  "startts": 1571747612067,
  "status": "forking",
  "uris": [
    "<sip:12@test.rootdomain.ru>",
    "<sip:sip3@test.rootdomain.ru>",
    "<sip:sip3@test.rootdomain.ru>",
    "<sip:sip2@test.rootdomain.ru>"
  ]
}

Transferring a call to a number (REFER)

Performs call transfer - dialog subscriber (opponent) - to the specified number. Valid for any active dialog in the current domain. There are standard limitations when translating dialog that is in a state of status=forking.

Process Flowchart: X-Y | IVR→Y, IVR REFER Z, Y→Z.

The operation is carried out through the launch of a hidden service script that performs a prepared call to a specified subscriber with substitution of a specific specified dialog box (Dialer script component with Replaces and Referred-By headers installed), and then transferring control to a specially prepared hidden IVR script with the Dial-up component]. The specified number is substituted as the number to be transferred referto. If the transfer fails, the next script component transfers the call back to the transfer initiator’s number.

The request is pre-filtered. To be allowed to execute, the specified dialog must have as one of its participants an authorized user (through any of the accounts belonging to the user) sipuser).

Request

Table 11. Request parameters
Name Type Description

dialogid

str

Identifier of the dialog to be translated.

Passed on as part of Endpoint URI.

by

str

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

Based on the value, the oppositional party to be translated is calculated. It is to this party that the INVITE SIP request with Replaces from the IVR and the subsequent SIP request are sent REFER.

referto

str

The number to which the subscriber is being transferred. Allows the characters “'” and “,” to be specified. The first such character allocates the remaining sequence as a DTMF pre-dial after the response is received, and each subsequent such character provides a 1-second pause in the set DTMF.

response_mode

int

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

Possible options:

  • 0 – send a response immediately after initiating an IVR→Y call. It is sent almost instantly without waiting for responses from callers Y and Z. The response contains only the CallId of the initiating call IVR→Y.

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

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

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

  • 4 – send a reply after receiving a final response from Z (200-699, Y→Z). From this mode onwards, the response contains valid information about the success of the connection Y→Z.

  • 5 - send a response after the operation and all its processes are complete (excluding the Y→Z dialog itself, which may last several hours).

Default 3.

binding

str

Label bound to the swap call and trace to the transfer call. Not assigned by default.
Request example
REFER /rest/v1/user/sip/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 12. Field Description
Field Description

dialogid

The identifier of the dialog to be translated. Matches the identifier in the endpoint or is transferred unchanged from the request parameters.

result

The final result of the operation. Value options.

ivrcallid

Call-Id initiating automatic IVR→Y call (different from CallId of the target dialog shoulders). Present in any case.

new_acallid

Call-Id call received in the system from subscriber Y to subscriber Z after processing SIP REFER request. This is the Call-Id of the A arm of the target Y→Z dialog. It may not be present for some unsuccessful operation results.

new_last_response

Response-Line the last received response from subscriber Z, based on the results of which a response to the request is generated. In case of some unsuccessful results of the operation may be absent.

new_dialogid

The identifier of the target Y→Z dialog. May be absent in some unsuccessful results of the operation. It may also be absent if the dialog duration is 0 seconds.
Table 13. Field value options result
Significance Description

"ok"

The response is formed at a stage where no problems are identified to successfully create a Y→Z dialog. For example, for

  • response_mode=0 – IVR script is successfully initialized for calling IVR→Y.

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

  • response_mode=2 – received a final response of `2xx' from the subscriber Y (IVR→Y).

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

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

  • response_mode=5 – Y→Z dialog is set, after some small timeout initializing processes are terminated.

"rejected"

IVR→Y call failed (4xx-6xx) or Y→Z call failed (4xx-6xx). Both the server and the subscriber device could have sent the failed response.

In case an unsuccessful response is received from subscriber Y, the result does not contain information about dialog Y→Z, fields acallid, dialogid, last_response are missing. In case an unsuccessful response is received from subscriber Z, the result contains the acallid and last_response fields about the Y→Z dialog and does not contain the dialogid.

"redirected"

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

The value is hypothetical, since 3xx redirects are handled by the server itself (role b2b), automatically initiating alternate forks.

"timeout"

The IVR→Y call after the pre-reply has timed out.

The value is hypothetical because if there is no final response, the server (role b2b), terminates the call by automatically emulating the response 408 Timeout.

"error"

No response from subscriber Y, or other unexpected situation.

Fields may be missing from the response acallid, dialogid, last_response.

"undefined"

Subscriber Y successfully answered the IVR→Y call, the status of the Y→Z call is unknown due to missing or unknown content of NOTIFY SIP requests in the dialog served by the REFER.
Response example
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "dialogid": "rDlg-002-WOabz0",
  "result": "ok",
  "ivrcallid": "rIV-006-5avZy6B3IC5nivAvVS5B6n4prqT",
  "new_acallid": "1920460747@192.168.0.149",
  "new_dialogid": "rDlg-002-JKNked",
  "new_last_response": "SIP/2.0 180 Ringing"
}

Transferring a spoofed call (REFERREPLACES)

Makes a connection between the subscribers of two different active dialogs in the current domain.

The subscriber connects its two opponents in different active dialogs, and releases itself according to the SIP protocol (in particular, a SIP-UA that receives an INVITE from Replaces performs a BYE send towards the opponent in the spoofed dialog).

A schematic of the process in general terms: X-Y, P-Q | IVR→Y, IVR REFER+REPLACES Q, Y→Q.

Cmain case process flowchart: X-Y, X-Z | IVR→Y, IVR REFER+REPLACES Z, Y→Z.

Since two calls are involved, the name of each parameter contains the prefix: "master" or "slave".

The operation is carried out through the launch of a hidden service script that performs a prepared dial-up to the subscriber of one dialog with substitution (script component "Dial-up" with installed headers Replaces and Referred-By), followed by transfer of control to a specially prepared hidden IVR script with the component "Transfer with substitution". The identifier of the second specified dialog is substituted as the target for transfer (slave).

The request is pre-filtered. To be allowed to execute, the specified dialogs must have as one of their participants an authorized user (via any of the accounts belonging to the user) sipuser).

Request

Table 14. Options for transferring a call to dialogid.
Name Type Description

masterdialogid

str

Identifier of the dialog to be translated (master).

Passed on as part of Endpoint URI.

masterby

str

The side of the master dialog initiating the call transfer. SIP URI or Call-Id.

Based on the value, the oppositional party to be translated is calculated. It is to this party that the INVITE SIP request with Replaces from the IVR and the subsequent SIP request are sent REFER.

slavedialogid

str

Identifier of the dialog to be spoofed (slave).

There are other ways of specifying a slave dialog alternative to this. All the ways to specify a dialog are listed below in descending order of priority with a brief description. For details, see the parameters of the call lookup operation with the prefix added "slave".

  • slavedialogid – by dialog identifier.

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

  • slavecallid – by the Call-Id identifier of one of the dialog’s arms.

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

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

  • slavesipuserid – by SIP user account ID.

  • slavesipuserlogin – by SIP user account login.

  • slavesipuserphonenumber – by the phone number of the SIP user account.

  • slaveuserid – by the system user account ID.

slaveby

str

The side of the slave dialog to be spoofed. SIP URI or Call-Id.

Based on the value, the opposing side is calculated, at which the shoulder should be swapped. The REFER with Replaces is targeted to it and as a consequence it is sent a SIP request INVITE with Replaces from Y.

response_mode

int

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

Possible options:

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

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

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

  • 3 – send a response after receiving a preliminary response from Q (101-199, Y→Q). The 100 response is excluded because it is sent by the server and not by the caller. Starting from this mode, the context of the call contains information about the target dialog.

  • 4 – send a reply after receiving a final reply from Q (200-699, Y→Q). From this mode onwards, the response contains valid information about the success of the connection Y→Q.

  • 5 - send a response after the operation and all its processes are complete (excluding the Y→Q dialog itself, which may last several hours).

Default 4.

binding

str

A label to be bound to the swap call and trace to the transferred swap call. Not assigned by default.
Request example
REFERREPLACES /rest/v1/user/sip/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 15. Field Description
Field Description

masterdialogid

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

slavedialogid

Identifier of the dialog to be swapped (slave). Goes unchanged from the request parameters.

result

The final result of the operation. Value options.

ivrcallid

Call-Id initiating automatic IVR→Y call (different from CallId of the target dialog shoulders). Present in any case.

new_acallid

Call-Id call received in the system from subscriber Y to subscriber Z after processing SIP REFER request. This is the Call-Id of the A arm of the target Y→Z dialog. It may not be present for some unsuccessful operation results.

new_last_response

Response-Line the last received response from subscriber Z, based on the results of which a response to the request is generated. In case of some unsuccessful results of the operation may be absent.

new_dialogid

The identifier of the target Y→Z dialog. May be absent in some unsuccessful results of the operation. It may also be absent if the dialog duration is 0 seconds.
Table 16. Field value options result
Significance Description

"ok"

The response is formed at a stage where no problems are identified to successfully create a Y→Z dialog. For example, for

  • response_mode=0 – IVR script is successfully initialized for calling IVR→Y.

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

  • response_mode=2 – received a final response of `2xx' from the subscriber Y (IVR→Y).

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

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

  • response_mode=5 – Y→Q dialog is set, after some small timeout initializing processes are terminated.

"rejected"

IVR→Y call failed (4xx-6xx) or Y→Z call failed (4xx-6xx). Both the server and the subscriber device could have sent the failed response.

In case an unsuccessful response is received from subscriber Y, the result does not contain information about the dialog Y→Q, the fields acallid, dialogid, last_response are missing. In case an unsuccessful response is received from subscriber Q, the result contains the acallid and last_response fields about the Y→Q dialog and does not contain the dialogid.

"redirected"

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

The value is hypothetical, since 3xx redirects are handled by the server itself (role b2b), automatically initiating alternate forks.

"timeout"

The IVR→Y call after the pre-reply has timed out.

The value is hypothetical because if there is no final response, the server (role b2b), terminates the call by automatically emulating the response 408 Timeout.

"error"

No response from subscriber Y, or other unexpected situation.

Fields may be missing from the response acallid, dialogid, last_response.

"undefined"

Subscriber Y successfully answered the IVR→Y call, the status of the Y→Q call is unknown due to missing or unknown content of NOTIFY SIP requests in the dialog served by REFER.
Response example
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "masterdialogid": "rDlg-002-HKO7cn",
  "slavedialogid": "rDlg-002-YWR7ts",
  "result": "ok",
  "ivrcallid": "rIV-006-OCXV3CJPkbUUlFx6v8O00kjTm22",
  "new_acallid": "3762659316@192.168.0.146",
  "new_dialogid": "rDlg-002-RqNtEp",
  "new_last_response": "SIP/2.0 200 OK"
}

Converting a call to a conference (SWITCHCONF)

Soft switches both callers of the specified dialog to the conference room. Both subscriber devices receive INVITE SIP requests from Replaces, connect to IVRs, which translate them to the conference room using SIP requests REFER. Subscribers can be in different domains. The conference will be created in the domain in which the conversion API request is made (or the script that performs the operation is executed).

The operation is performed by running hidden service scripts - one for each of the subscribers making a prepared call to the corresponding dialog subscriber with substitution (script component Outgoing call with Replaces and Referred-By headers set), with subsequent transfer of control to a specially prepared hidden IVR script with the component Transfer to number. The conference room number along with the CAF is substituted as the target for transfer (featurecode type conf). The number to be transferred can be specified in the referto request parameter, otherwise it is calculated automatically - routing must be configured.

Process Flowchart: X-Y | IVR1→X, IVR2→Y, IVR1 REFER CONF, IVR2 REFER CONF, X→CONF, Y→CONF.

The by request parameter specifies an arbitrary username or number in the current domain on behalf of which both subscribers of the dialog are transferred to the conference. Actually should be used if the routing is special and not everyone has access to the featurecode of the conference.

So that when one subscriber receives an INVITE from Replaces, the other subscriber does not fall off by BYE (the receiving party sends a BYE to the opponent of the spoofed dialog according to the SIP protocol, and the b2b role brushes it through), the role b2b receives a command to temporarily pause the dialog (effectively blocking the BYE resend - instead, a delayed asynchronous BYE sending operation for 3 seconds is started when the BYE is received). After receiving 2xx SIP responses from both subscribers to INVITE with Replaces, the dialog is paused. In a normal situation, he’s out of existence by this time.

In case of failure, the original conversation is not restored. Theoretically, it is possible that one subscriber will be able to reach the conference room and the other will not. In this case, one will get a bounce and the other will be alone in the conference.

A dialog whose subscriber is a conference (username = "conf-…​") is not allowed to be converted to a conference (is not due to implementation complexities, it’s just an external restriction so that empty conferences related to each other don’t hang).

The request is pre-filtered. To be allowed to execute, the specified dialog must have as one of its participants an authorized user (through any of the accounts belonging to the user) sipuser).

Request

Table 17. Request parameters
Name Type Description

dialogid

str

Identifier of the dialog to be translated (master).

Passed on as part of Endpoint URI.

referto

str

The full conference number along with the CAF prefix.

The parameter is optional. If it is missing, a random 8-digit conference room number is generated, and the prefix of the first one found in the domain featurecode with type conf.

by

str

The number or username of the subscriber on whose behalf you want to transfer to the conference room.

The parameter is optional. Default value: "callmanager".

For the specified subscriber, route to the conference room must be available (routing rules are defined by the entities route and vectorrule).

response_mode

int

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

Possible options:

  • 0 – send a response immediately after initiating IVR1→X and IVR2→Y calls. It is sent almost instantly without waiting for responses from callers X and Y. The response contains only CallId of initiating calls IVR1→X and IVR2→Y.

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

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

  • 3 – send a response after receiving the preliminary responses from CONF (101-199, X→CONF, Y→CONF). The 100 response is excluded because it is not sent by the conference but by one of the servers on the boundary. Starting from this mode, the operation context contains information about the target dialogs with the conference.

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

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

Default 4.

binding

str

Label bound to the swap call and trace to the transfer call. Not assigned by default.
Request example
SWITCHCONF /rest/v1/user/sip/calls/rDlg-002-Maw6qN HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "referto":"*99358",
  "by":"sip3",
  "response_mode": 4
}

Response

Table 18. Field Description
Field Description

dialogid

The identifier of the dialog to be converted to a conference. Matches the identifier in the endpoint or passes unchanged from the request parameters.

referto

String containing the number used for conference transfer. Indicates the system-generated full number with a prefix, or the number specified in the request in the field referto.

result

The final result of the operation. Value options.

confid

The identifier of the conference to which subscribers are redirected.

x_ivrcallid

Call-Id initiating automatic call IVR1→X (different from the CallId of the shoulders of the target conference dialog). Present in any case.

x_new_acallid

Call-Id call received in the system from subscriber Y to subscriber Z after processing SIP REFER request. This is the Call-Id of the A arm of the target Y→Z dialog. It may not be present for some unsuccessful operation results.

x_new_last_response

Response-Line the last received response from subscriber Z, based on the results of which a response to the request is generated. In case of some unsuccessful results of the operation may be absent.

x_new_dialogid

The identifier of the target Y→Z dialog. May be absent in some unsuccessful results of the operation. It may also be absent if the dialog duration is 0 seconds.

y_ivrcallid

Call-Id initiating automatic IVR2→Y call (different from the CallId of the shoulders of the target conference dialog). Present in any case.

y_new_acallid

Call-Id call received in the system from subscriber Y to subscriber Z after processing SIP REFER request. This is the Call-Id of the A arm of the target Y→Z dialog. It may not be present for some unsuccessful operation results.

y_new_last_response

Response-Line the last received response from subscriber Z, based on the results of which a response to the request is generated. In case of some unsuccessful results of the operation may be absent.

y_new_dialogid

The identifier of the target Y→Z dialog. May be absent in some unsuccessful results of the operation. It may also be absent if the dialog duration is 0 seconds.
Table 19. Field value options result
Significance Description

"ok"

The response is formed at a stage where no problems are identified to successfully create a Y→Z dialog. For example, for

  • response_mode=0 – IVR scripts are successfully initialized for IVR1→X call and IVR2→Y.

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

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

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

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

  • response_mode=5 – X→CONF and Y→CONF dialogs are set, after some small timeout the initializing processes are completed.
Response example
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "dialogid": "rDlg-002-Maw6qN",
  "referto": "*99358",
  "result": "ok",
  "confid": "rCF-005-ZIzwBi",
  "x_ivrcallid": "rIV-006-D0qaTIsaTzBoWDHiAYgCIOo7odO",
  "x_new_acallid": "27142922@192.168.0.149",
  "x_new_dialogid": "rDlg-002-UTx2LP",
  "x_new_last_response": "SIP/2.0 200 OK",
  "y_ivrcallid": "rIV-006-TTBdJOR0ifh8HYiE9sVwqqJ31HW",
  "y_new_acallid": "817803971@192.168.0.147",
  "y_new_dialogid": "rDlg-002-XVRAsk",
  "y_new_last_response": "SIP/2.0 200 OK"
}

Transferring a call to a conference (REFERCONF)

Transfers the specified call (opponent in a dialog) to an existing conference. This is analogous to the transfer-to-number operation with automatic conference lookup, calculation and substitution of the conference number for routing.

The operation is carried out through the launch of a hidden service script that performs a prepared dial-up to the specified subscriber with substitution of a specific specified dialog (script component "Dial-up" with Replaces and Referred-By headers set) and subsequent transfer of control to a specially prepared hidden IVR script with the component "Transfer to number". The number of the detected conference is substituted as the number to be translated, as follows featurecode + confroomnum. If the transfer fails, the next component transfers the subscriber back to the number of the transferor.

Process Flowchart: X→CONF (hold), X→Y | IVR→Y, IVR REFER CONF, Y→CONF.

The transfer is done in the conference domain. If the request is suddenly executed in a different domain relative to the conference, an error is returned. This is possible if a subscriber from another domain participates in the conference and the conference is specified by referring to his dialog.

After successful completion of the operation, the transferring subscriber X remains on hold in the conference. In order to return to it, he/she needs to take it off hold using commands from his/her SIP device.

An alternative approach to this operation is to use the "Transfer to Number" method, specifying the number at which a particular conference room is available.

The request is pre-filtered. To be allowed to execute, the specified dialog must have as one of its participants an authorized user (through any of the accounts belonging to the user) sipuser).

Request

Table 20. Request parameters
Name Type Description

dialogid

str

The identifier of the dialog to be transferred to the conference.

Passed on as part of Endpoint URI.

by

str

The side of the dialog initiating the call transfer to the conference. SIP URI or Call-Id.

Based on the value, the oppositional party to be translated is calculated. It is to this party that the INVITE SIP request with Replaces from the IVR and the subsequent SIP request are sent REFER.

referdialogid

str

The identifier of the dialog, one of the participants of which is the conference - transfer destination. This is one possible way of indicating the conference that is the target of the transfer.

There are other ways of specifying the conference alternative to this. All ways of indicating the conference are listed below in descending order of priority with a brief description. For details, see the parameters of the call lookup operation with the prefix added "refer".

  • Through specifying a dialog, one side of which is the target conference:

    • referdialogid – by dialog identifier.

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

    • refercallid – by the Call-Id identifier of one of the dialog’s arms.

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

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

    • refersipuserid – by SIP user account ID.

    • refersipuserlogin – by SIP user account login.

    • refersipuserphonenumber – by the phone number of the SIP user account.

    • referuserid – by the system user account ID.

  • Through the direct instruction of the conference:

    • referconfid – by conference ID.

    • referconfroomnum – by conference room number.

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

response_mode

int

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

Possible options:

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

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

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

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

  • 4 – send a response after receiving a final response from Z (200-699, Y→CONF). From this mode onwards, the response contains valid information about the success of the connection Y→CONF.

  • 5 - send a response after the operation and all its processes are complete (excluding the Y→CONF dialog itself, which may last several hours).

Default 3.

binding

str

Label bound to the swap call and trace to the transfer call. Not assigned by default.
Request example
REFERCONF /rest/v1/user/sip/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

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

{
  "dialogid": "rDlg-002-96Ptom",
  "result": "ok",
  "ivrcallid": "rIV-006-1pq2q9apUWvHHJRXiImXOlPrOOC",
  "new_acallid": "1920460747@192.168.0.149",
  "new_dialogid": "rDlg-002-Uf38zV",
  "new_last_response": "SIP/2.0 180 Ringing"
}

Sending a device control event to one of the parties (NOTIFY)

Realizes server-initiated software control of the subscriber’s device.

Sends a NOTIFY request with an event message to the specified subscriber’s device. In particular, this may be used to control the device in accordance with the extension Cisco Broadsoft (https://pubhub.devnetcloud.com/media/broadsoft-docs/docs/pdf/BW-SIPAccessSideExtensionsInterfaceSpec.pdf) Depending on the type of message, the device can:

  • answer the phone (talk),

  • enter hold mode (hold),

  • exit hold mode (talk),

  • combine held callers in a phone-controlled conference (conference)

  • other

The operation is performed in call mode for the called party (talk), or in dialog mode for either party.

According to RFC3265, supported events are listed by the device in the Allow-Events header in the INVITE request or response 1xx/2xx. If the device does not support the extension, it does not send the appropriate values in the header, and on that basis the server blocks the NOTIFY request from being sent.

Sending a message is asynchronous, the final result is not reported. A successful response means only that the request was sent.

The server does not apply the extensions itself, but provides the ability to use their functionality externally to the system through APIs and scripts. The composition of supported extensions is determined by the device. The quality of the system’s support for device expansion is not guaranteed. As a recommendation: use the method only in optional mode and when it is known that all devices used support the method and is not foreseen otherwise.

The request is pre-filtered. To be allowed to execute, the specified dialog must have as one of its participants an authorized user (through any of the accounts belonging to the user) sipuser).

Request

Table 21. Request parameters
Name Type Description

dialogid

str

The identifier of the dialog to be transferred to the conference.

Passed on as part of Endpoint URI.

callid

str

The side of the dialog whose device is being controlled, Call-Id.

event

str

Event name for controlling the device (talk,hold,conference,refer,check-sync,…​)
Request example
NOTIFY /rest/v1/user/sip/calls/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "callid": "4139247432@192.168.0.149",
  "event": "talk"
}

Response

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

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

Sending a DTMF character to one of the parties (SEND_DTMF)

Implements sending DTMF characters to the specified shoulder of the specified dialog. Sending sequences is supported. The request is answered immediately, but there is a queue for sending individual characters in the shoulder. The same queue is used when multiple requests are received.

Allows you to specify a sequence of DTMF characters including ' and ,. Each such character provides a 1 second pause in the set DTMF.

Depending on the protocol specified (proto): * sipinfo - sends an INFO request with a DTMF character. * rfc2833 - sends RTP packets according to the protocol RFC-2833.

Sending a message is asynchronous, the final result of work is not reported. A successful response means only that a request or a series of RTP packets has been sent.

The request is pre-filtered. To be allowed to execute, the specified dialog must have as one of its participants an authorized user (through any of the accounts belonging to the user) sipuser).

Request

Table 22. Request parameters
Name Type Description

dialogid

str

The identifier of the dialog to be transferred to the conference.

Passed on as part of Endpoint URI.

callid

str

The side of the dialog to which the DTMF character is to be sent, Call-Id.

side

str

Alternate indication of the party to the dialog (a is the initiator of the call, b is the addressee of the call), or Call-Id.

opposite

bool

An indication of the taking of another party relative to the specified party.

proto

str

Selects the mode of sending DTMF character (rfc2833, sipinfo). Default sipinfo.

dtmf

str

DTMF-character to send (0-9*##). Only character-by-character sending is supported.
Request example
SEND_DTMF /rest/v1/user/sip/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

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

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

Start/stop stenography by one of the parties (SETUP_ASR)

Enables/disables recording and recognition in the text of the specified shoulder of the specified dialog.

A successful response to an enable operation means only that a request or series of RTP packets has been sent.

When the mode is turned off, the response is delayed for a few seconds until the recognition session is complete.

You can use the following to get events about the result as you recognize it websocket api.

The mode works when the speech steno subsystem (master domain) is installed and configured, settings.record_asr_options)

The request is pre-filtered. To be allowed to execute, the specified dialog must have as one of its participants an authorized user (through any of the accounts belonging to the user) sipuser).

Request

Table 23. Request parameters
Name Type Description

dialogid

str

The identifier of the dialog to be transferred to the conference.

Passed on as part of Endpoint URI.

command

str

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

layer

str

Specifies a unique name for the layer. Multiple layers are supported at the same time, when an existing layer is specified, it is replaced. In order to stop recording and recognition, you also need to specify an existing layer.

callid

str

The side of the dialog that needs to be sent for shorthand, Call-Id.

side

str

Alternate indication of the party to the dialog (a is the initiator of the call, b is the addressee of the call), or Call-Id.

opposite

bool

An indication of the taking of another party relative to the specified party.

result_text

bool

For the stop operation, sets the wait and return mode of the summary text. In the case of true (default), the response is delayed for 2-3 seconds.
Request example
SETUP_ASR /rest/v1/user/sip/calls/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8

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

Response

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

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

Start/stop (add/remove) a dialog recording channel (SETUP_RECORD)

Enables/disables the recording channel of the specified dialog.

The request is pre-filtered. To be allowed to execute, the specified dialog must have as one of its participants an authorized user (through any of the accounts belonging to the user) sipuser).

Request

Table 24. Request parameters
Name Type Description

dialogid

str

The identifier of the dialog to be transferred to the conference.

Passed on as part of Endpoint URI.

command

str

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

layer

str

Specifies a unique name for the layer. Multiple layers are supported at the same time, when an existing layer is specified, it is replaced. In order to stop recording and recognition, you also need to specify an existing layer.

callid

str

The side of the dialog to be put on the record, Call-Id.

side

str

Alternate indication of the party to the dialog (a is the initiator of the call, b is the addressee of the call), or Call-Id.
Request example
SETUP_RECORD /rest/v1/user/sip/calls/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "layer": "default"
}

Response

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

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

Managing dialog labels (SETUP_BINDINGS)

Manages the labels of the specified dialog.

Dialog labels are string values tied to specific conversations/dialogs, set via API or scripts. Tags are available at any point in the lifecycle of a conversation right up to the end of the conversation. The tags are saved when the call is transferred and transferred to the newly transferred conversation.

Tags are based on the binding to service sessions in the CC (name "seance_…​"), as well as the post call survey mechanism (name "post call survey") "PCS:…​").

In the Operation script component, label management is available through a separate command group (labels).

The request is pre-filtered. To be allowed to execute, the specified dialog must have as one of its participants an authorized user (through any of the accounts belonging to the user) sipuser).

Request

Table 25. Request parameters
Name Type Description

dialogid

str

The identifier of the dialog to be transferred to the conference.

Passed on as part of Endpoint URI.

command

str

Operation:

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

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

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

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

  • clean - clears all dialog labels.

  • contains - checks if the specified label is present in the dialog. Requires the 'label' parameter, which is a string. Returns true or false in the field 'contains'.

label

str or array<str>

Specifies a label or a list of labels.
Request example
SETUP_BINDINGS /rest/v1/user/sip/calls/rDlg-002-WOabz0 HTTP/1.1
Content-Type: application/json; charset=utf-8

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

Response

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

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

Ending a call (DELETE)

Concludes the dialog. The server acts as a break initiator for both subscribers (sends a BYE SIP request to both subscribers). If the dialog is in a call state, a SIP request is sent to all called subscribers CANCEL.

In the current version, the completion is external without indicating in the events of the callevents class a sign of binding to the actions of party A or the party B.

The request is pre-filtered. To be allowed to execute, the specified dialog must have as one of its participants an authorized user (through any of the accounts belonging to the user) sipuser).

Request

Request example
DELETE /rest/v1/user/sip/calls/rDlg-002-9dEcfh HTTP/1.1

Response

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

{
  "dialogid": "rDlg-002-9dEcfh"
}
Example of an 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

  • Personalization
  • Increase font size
  • Decrease font size