'ccs' capability for WebSocket Token API
- Overview
- Server requests
- Terminating a call (bye)
- Initiating a new call (new_invite)
- Initiating a new call from IVR (invite_byivr)
- Transferring a call to an IVR script (refer_toivr)
- Pickup
- Transferring a call to a number (refer)
- Transferring a call by replacement (referreplaces)
- Switching a subscriber device to HOLD mode (hold)
- Switching a subscriber device to TALK mode (talk)
- Getting the list of current conversations/dialogs (list_connections)
- Getting information about the specified dialog (get_connection)
- Getting the list of current calls/legs (list_calls)
- Converting a call into a conference (switch_to_conference)
- Transferring a call to a conference (refer_to_conference)
- Ending a conference (stop_conference)
- Getting the list of current conferences (list_conferences)
- Getting conference information (get_conference)
- Getting the list of conference participants (get_participants)
- Getting conference participant information (get_participant)
- Adding a participant to a conference (attach_participant)
- Removing a conference participant (detach_participant)
- Getting conference topology (get_topology)
- Changing conference topology (set_topology)
- Sending a DTMF character to one dialog party (send_dtmf)
- Enabling/disabling subscriber speech recognition (start_asr/stop_asr)
- Enabling/disabling additional recording during a conversation (start_record/stop_record)
- Enabling/disabling file playback in a conversation (start_play/stop_play)
- Pausing/resuming the main built-in recording during a conversation (pause_recording/resume_recording)
- Dialog label management
- SIP user availability (set_sipuser_status)
- Setting up Post Call Survey (setup_post_call_survey)
- Transcribing a previously recorded conversation (transcribe)
- Generating a CTI integration event (cti_event)
- ccsevents stream diagnostics (ccs_setup)
- Concept of integration with an external system and the product layer
- Links
Overview
Provides an interface for call management (a subset of the CallManager REST API).
Requests managing a specific connection require the 'idconn' parameter. It can be found in ccsevents call events, in the 'connectionid' field of callevents events, or in the response to a call collection read request. Requests managing a specific connection leg, or having an application direction, require the 'idcall' parameter. This is the Call-Id of a specific leg. It can be found in ccsevents and callevents events or in the response to a call collection read request.
Server requests
Terminating a call (bye)
Forcibly terminates the dialog by sending BYE to both parties. If the dialog is in the Forking state, it forcibly terminates the dialog by sending CANCEL to all subscribers and a failure response to the call initiator.
[
"bye",
{
"qid": 0.1234,
"idcall": "",
"idconn": "3694473f-0641-450c-2c15-c00000000002.1601282818792"
}
]
Initiating a new call (new_invite)
Performs an intercom call to the initiator device specified in the owner field, on behalf of CallManager with IVR script participation.
After the handset is lifted, transfers the call to the number specified in the number field.
If the initiator device does not support or prohibits intercom calls, the first service call proceeds until the initiator lifts the handset. If the initiator device supports and allows intercom calls, the outgoing call is answered by the device immediately.
If during command execution the initiator device is already in a dialog, then depending on device settings it either makes a second call or interrupts the current dialog, putting it on hold. If the device supports and allows intrusion via an intercom call, the current dialog is put on hold and the newly initiated dialog arrives and is answered automatically by the device. Otherwise, if intrusion is not supported or is prohibited, the device accepts and displays a second call waiting for the initiator to lift the handset.
Case of account incoming call limit. If a simultaneous call limit is configured for the initiator account and no free trunks are available when the initiated new call arrives, the incoming intercom call cannot proceed and the command returns the refusal "rejected".
Case of multiple devices. If the initiator has several registered devices that support and allow intercom calls, the call can be answered automatically on any of them. In this case the choice of a specific device is effectively random.
[
"new_invite",
{
"qid": 0.1234,
"owner": "sip:sip1@test.rootdomain.ru",
"number": "12"
}
]
Optional parameters:
-
owner- URI pointer to the call initiator account. Format: 'sip:USERNAME@DOMAIN' or 'NUMBER'. -
use_intercom- sets the initiator intercom call mode. Default 'true'. -
idseance- session pointer. When a consultation call bound to an existing service session is needed. If the session is not specified, the call gets a session binding unmanaged from outside — it can be an empty session, a new session, or an inherited session. The session is set as a binding label of the format 'seance_DIR_ID' and is inherited on transfers. -
idparentconn- parent call pointer. When a consultation call bound to an existing call is needed. The parent call is set as a binding label of the format 'PARENT:acallid:CALLID' and is not inherited on transfers.
The alternative invite method defaults the 'use_intercom' parameter to false.
More about the method parameters in the HTTP REST API description /rest/v1/uc/calls
[
"invite",
{
"qid": 0.1234,
"owner": "sip:sip2@test.rootdomain.ru",
"number": "11",
"use_intercom": false
}
]
NOTE! For intercom mode to work correctly, a featurecode with type intercom must be configured in the system and available by routes for the initiator to call from their own name.
Optionally, the idseance key can be specified. Its value enters the binding label of the current call. Subsequently it is automatically carried into all subsequent dialogs of the current session created as a result of transfers.
Allows ' and , characters in the number. The first such character marks the remaining sequence as DTMF post-dialing after the answer is received, and each subsequent such character provides a 1-second pause in DTMF dialing.
[
"invite_result",
{
"qid":123,
"result": "ok",
"acallid": "4294572626@192.168.0.149",
"dialogid": "rDlg-002-911Jnh",
"ivrcallid": "rIV-006-Z7Bvucu1smS3jgRRuO8ZhcrHXm1",
"last_response": "SIP/2.0 180 Ringing",
"result": "ok"
}
]
Response parameters:
-
dialogid- internal ID of the redirected dialog. It can be used to obtainidconn. -
ivrcallid- ID of the service CALL from IVR to the call initiator. -
acallid- ID of the target call from the call initiator to the called number.
Initiating a new call from IVR (invite_byivr)
Calls the number specified in the number field on behalf of callerid and connects it to the IVR script whose code is specified in the scriptcode field.
If the script is not specified, the built-in ext_api_management script is started with control transferred to the external system. The key field passes the value to the corresponding property of the "External control" component.
The use_intercom field allows initiating an intercom call to the subscriber.
[
"invite_byivr",
{
"qid": 0.1234,
"number": "12",
"use_intercom": false,
"callerid": "1234567",
"scriptcode": "script_abc"
}
]
Optional parameters:
-
use_intercom- sets the intercom call mode. Default 'false'. -
idseance- session pointer. When a call bound to an existing service session is needed. If the session is not specified, the call gets a session binding unmanaged from outside — it can be an empty session or a new session. The session is set as a binding label of the format 'seance_DIR_ID' and is inherited on transfers. -
idparentconn- parent call pointer. When a consultation call bound to an existing call is needed. The parent call is set as a binding label of the format 'PARENT:acallid:CALLID' and is not inherited on transfers. -
scriptcode- pointer to the code of the IVR call handler script. If not specified, the built-in 'ext_api_management' script handles the call, transferring control to the API (the External control component). -
key- when using the built-in 'ext_api_management' script, sets the key passed through it to the API 'ivrevents.api_start' event. -
param- places this value in start parameter 2 of the IVR script. -
callerid- initiator subscriber number substituted by the IVR script into the sent INVITE request, From header, username field. -
callername- initiator subscriber name substituted by the IVR script into the sent INVITE request, From header, displayname field. -
calltimeout- response wait timeout in seconds.
NOTE! For intercom mode to work correctly, a featurecode with type intercom must be configured in the system and available by routes for the initiator to call from their own name.
Optionally, the idseance key can be specified. Its value enters the binding label of the current call. Subsequently it is automatically carried into all subsequent dialogs of the current session created as a result of transfers.
Allows ' and , characters in the number. The first such character marks the remaining sequence as DTMF post-dialing after the answer is received, and each subsequent such character provides a 1-second pause in DTMF dialing.
More about the method parameters in the HTTP REST API description /rest/v1/uc/calls
[
"invite_byivr_result",
{
"qid": 123,
"ivrcallid": "rIV-0GC-LBQTDymNxd2hdGyhBu1QNdjTIdz",
"result": "answered",
"sipcode": 200
}
]
Response parameters:
* ivrcallid - ID of the service CALL from IVR to the call initiator.
Transferring a call to an IVR script (refer_toivr)
Transfers the dialog idconn leg opposite to idcall to an IVR script (call with leg replacement).
[
"refer_toivr",
{
"qid": 0.1234,
"idcall": "4111998404@192.168.0.149",
"idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872",
"scriptcode": "ext_api_management"
}
]
Optional parameters:
-
scriptcode— IVR script code, defaultext_api_management; -
idseance,idparentconn— binding label values of the new call (as in refer); -
key— an arbitrary key passed to the script.
Response — refer_toivr_result with the result field.
Pickup
Calls the request initiator device and then transfers to the call pickup number.
[
"pickup",
{
"qid": 0.1234,
"owner": "sip:sip2@test.rootdomain.ru",
"number": "11",
"use_intercom": true
}
]
Optional parameters:
NOTE! If "number" is not specified, a group pickup attempt is made.
NOTE! For intercom mode to work correctly, a featurecode with type intercom must be configured in the system and available by routes for the initiator to call from their own name.
NOTE! For pickup to work correctly, a featurecode with type pickup must be configured in the system and available by routes for a call on behalf of the initiator to the specified number (or to the group in group pickup).
Transferring a call to a number (refer)
Calls with leg replacement of the specified dialog (idconn), then initiates a REFER command to transfer it to the specified number. The dialog leg determined by the idcall parameter is the REFER initiator. The opposite leg is replaced and transferred. The dialog (idconn) and its leg (idcall) must exist. The call must be active and cannot be in the call state or waiting for a response to a sent request.
The idconn value comes in ccsevents class events, or can be taken from callevents class events, from the connectionid field, or built as a concatenation of the cid and its fields.
[
"refer",
{
"qid": 0.1234,
"idcall": "4111998404@192.168.0.149",
"idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872",
"number": "11"
}
]
Optional parameters:
Optionally, the idseance key can be specified. Its value enters the binding label of the call initiating pickup via an INVITE request with the Replaces header. Subsequently it is automatically carried into all subsequent dialogs of the current session created as a result of transfers.
Allows ' and , characters in the number. The first such character marks the remaining sequence as DTMF post-dialing after the answer is received, and each subsequent such character provides a 1-second pause in DTMF dialing.
More about the method parameters in the HTTP REST API description /rest/v1/uc/calls
[
"refer_result",
{
"qid":123,
"result": "ok",
"dialogid": "rDlg-002-Ml5kfx",
"ivrcallid": "rIV-006-R4AvhlGXOnYjEsTWbUPSiHQcI4N",
"new_acallid": "4163136050@192.168.0.146",
"new_dialogid": "rDlg-002-L45G2b",
"new_last_response": "SIP/2.0 180 Ringing",
"result": "ok"
}
]
Response parameters:
-
dialogid- internal ID of the redirected dialog. It can be used to obtainidconn. -
new_dialogid- internal ID of the newly created dialog. It can be used to obtainidconn. -
ivrcallid- ID of the service call by which IVR cut into the dialog and sent the refer. -
new_acallid- ID of the target call by which the subscriber started calling the specified number.
Transferring a call by replacement (referreplaces)
Calls with leg replacement of the specified dialog, then initiates a REFER command to transfer it by replacement to another dialog. As a result, subscribers of two different dialogs are connected, and BYE requests are sent to their counterparts. The dialog (idconn) and the specified leg (idcall) must exist. The call must be active and cannot be in the call state or waiting for a response to a sent request. If the second call does not exist or is in an unsuitable state, the command results in both subscribers of the first dialog hanging up.
The dialog leg determined by the idcall parameter is the REFER initiator. The opposite leg of the idconn dialog is replaced and transferred. Similarly, the target replacement leg of the second dialog idconn2 is the leg opposite to the one specified by the idcall2 parameter.
The idconn and idconn2 values come in ccsevents class events, or can be taken from callevents class events, from the connectionid field, or built as a concatenation of the cid and its fields.
As a rule, this command specifies both legs of the same subscriber — the request initiator — to connect the counterparts from two conversations involving them.
More about the method parameters in the HTTP REST API description /rest/v1/uc/calls
[
"referreplaces",
{
"qid": 0.1234,
"idcall": "4111998404@192.168.0.149",
"idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872",
"idcall2": "1094205346@192.168.0.149",
"idconn2": "469e785a-0641-488c-eba4-780000000002.1601297166763"
}
]
Optionally, the idseance key can be specified. Its value enters the binding label of the call initiating pickup via an INVITE request with the Replaces header. Subsequently it is automatically carried into all subsequent dialogs of the current session created as a result of transfers.
Switching a subscriber device to HOLD mode (hold)
Emulates the subscriber pressing the HOLD button (putting their counterpart in the current conversation on hold).
The dialog (idconn) and the specified leg (idcall) must exist. The call must be active and cannot be in the call state or waiting for a response to a sent request.
The idconn value comes in ccsevents class events, or can be taken from callevents class events, from the connectionid field, or built as a concatenation of the cid and its fields.
NOTE! Device support for the broadsoft extension is required.
NOTE! Applies only if the hold value is present in the Allowed-Events header received from the device during connection establishment. If the Allow-Events header is absent in all requests and responses from the device, a trial NOTIFY request is also sent according to the broadsoft protocol.
More about the method parameters in the HTTP REST API description /rest/v1/uc/calls
[
"hold",
{
"qid": 0.1234,
"idcall": "4111998404@192.168.0.149",
"idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872"
}
]
[
"referreplaces_result",
{
"qid": 123,
"result": "ok",
"ivrcallid": "rIV-006-BPLitgCyrFr6MtfwgJB5i7l0OhW",
"masterdialogid": "rDlg-002-Et7v2Z",
"new_acallid": "2799416178@192.168.0.146",
"new_dialogid": "rDlg-002-TQIZyK",
"new_last_response": "SIP/2.0 200 OK",
"result": "ok",
"slavedialogid": "rDlg-002-PEckZP"
}
]
Response parameters:
-
masterdialogid- internal ID of the redirected dialog. It can be used to obtainidconn. -
slavedialogid- internal ID of the accepting dialog. It can be used to obtainidconn. -
new_dialogid- internal ID of the newly created dialog. It can be used to obtainidconn. -
ivrcallid- ID of the service call by which IVR cut into the dialog and sent the refer. -
new_acallid- ID of the target call by which the subscriber of dialog X replaced the subscriber in dialog Y.
Switching a subscriber device to TALK mode (talk)
Used to automatically lift the handset on the device to answer an incoming call, and also to cancel HOLD mode and take the subscriber off hold.
The dialog (idconn) and the specified leg (idcall) must exist. The call must be active and cannot be in the call state or waiting for a response to a sent request.
The idconn value comes in ccsevents class events, or can be taken from callevents class events, from the connectionid field, or built as a concatenation of the cid and its fields.
NOTE! Device support for the broadsoft extension is required.
NOTE! Applies only if the talk value is present in the Allowed-Events header received from the device during connection establishment. If the Allow-Events header is absent in all requests and responses from the device, a trial NOTIFY request is also sent according to the broadsoft protocol.
More about the method parameters in the HTTP REST API description /rest/v1/uc/calls
[
"talk",
{
"qid": 0.1234,
"idcall": "4111998404@192.168.0.149",
"idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872"
}
]
Getting the list of current conversations/dialogs (list_connections)
Returns the list of dialogs of the current domain. Used for periodic data synchronization. It is assumed that the external system also receives data from events.
[
"list_connections",
{
"qid":"1234"
}
]
[
"list_connections_result",
{
"qid":"1234",
"data":[
{
"a_dn":"SIP4",
"a_domain":"test.incoplax.com",
"a_number":"14",
"a_type":"user",
"b_dn":"SIP2**",
"b_domain":"test.incoplax.com",
"b_number":"12",
"b_type":"user",
"dialed":"12",
"direction":"user -> user",
"id":"9cbe2eac-068e-e834-0292-7100000003ee.1678951104168",
"idseance":"1wOVlMzgF96mOjJc5JmqWW7wxp2",
"state":"connected"
}
],
"result":"ok"
}
]
Getting information about the specified dialog (get_connection)
Returns brief information about a dialog in the current domain.
[
"get_connection",
{
"qid":"1234",
"idcall": "4111998404@192.168.0.149",
"idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872"
}
]
[
"get_connection_result",
{
"qid":"1234",
"acallid":"1_1683566754@192.168.0.229",
"callids":["rB2-0GE-EULJka-01-1_1683566754@192.168.0.229","1_1683566754@192.168.0.229"],
"dialogid":"rDlg-0GE-EULJka",
"esgcallid":"",
"esgdlg":"",
"inviteid":"9cbe2eac-068e-e834-0292-7100000003ee",
"legs":[
{"callid":"1_1683566754@192.168.0.229","expirets":"undefined","localuri":"","remoteuri":"","side":"a"},
{"callid":"rB2-0GE-EULJka-01-1_1683566754@192.168.0.229","expirets":40000,"localuri":"","remoteuri":"","side":"b"}
],
"localuri":"",
"opts":{},
"remoteuri":"",
"result":"ok",
"site":"main_site",
"startts":1678951104168,
"status":"dialog",
"uris":["","","",""]
}
]
Getting the list of current calls/legs (list_calls)
Returns the list of calls/legs in the current domain. Used for periodic data synchronization. It is assumed that the external system also receives data from events.
[
"list_calls",
{
"qid":"1234"
}
]
[
"list_calls_result",
{
"qid":"1234",
"data":[
{
"dn":"SIP4",
"id":"rB2-0GE-EULJka-01-1_1683566754@192.168.0.229",
"idseance":"1wOVlMzgF96mOjJc5JmqWW7wxp2",
"number":"14",
"owner":"sip:sip2@test.incoplax.com",
"side":"b",
"state":"connected",
"type":"user"
},
{
"dn":"SIP2**",
"id":"1_1683566754@192.168.0.229",
"idseance":"1wOVlMzgF96mOjJc5JmqWW7wxp2",
"number":"12",
"owner":"sip:sip4@test.incoplax.com",
"side":"a",
"state":"connected",
"type":"user"
}
],
"result":"ok"
}
]
Converting a call into a conference (switch_to_conference)
Used to organize a conference based on the specified dialog. It is done by replacing the call in both legs and transferring to the conference number (referto). The call is made on behalf of the account whose username or number is passed in the 'by' parameter, or on behalf of the call manager.
The dialog (idconn) and the specified leg (idcall) must exist. The call must be active and cannot be in the call state or waiting for a response to a sent request.
If the 'by' parameter is passed and the 'referto' parameter is not passed, an ad-hoc conference is created with a room number allowing the owner participant to end the conference. Otherwise the transfer is made to a regular conference room with the number specified in the 'referto' field or a generated room number.
Other subscriber participants, knowing the room number, can enter it via routing if 'referto' is specified and consists of digits, and if routing rules and feature code rules make this number reachable through the conference feature code.
More about the method parameters in the HTTP REST API description /rest/v1/uc/calls
[
"switch_to_conference",
{
"qid": 0.1234,
"idcall": "4111998404@192.168.0.149",
"idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872",
"by": "sip3"
}
]
Transferring a call to a conference (refer_to_conference)
Used to transfer the subscriber of the specified call to an existing conference. It is done by replacing the call in the specified dialog leg and transferring it to the conference number. The call is made on behalf of the account whose username or number is passed in the 'by' parameter, or on behalf of the call manager.
The dialog (idconn) and the specified leg (idcall) must exist. The call must be active and cannot be in the call state or waiting for a response to a sent request. The conference must exist.
More about the method parameters in the HTTP REST API description /rest/v1/uc/calls
[
"refer_to_conference",
{
"qid": 0.1234,
"idcall": "4111998404@192.168.0.149",
"idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872",
"referdialogid": "rDlg-002-96Ptom",
"by": "2362769183@192.168.0.203"
}
]
Ending a conference (stop_conference)
Ends the conference and hangs up all participants, discovering it by the 'idconf' identifier.
The identifier can be obtained, among other ways, from the dialog with the conference using the get_conference method.
More about the method parameters in the HTTP REST API description /rest/v1/uc/conferences
[
"stop_conference",
{
"qid": 0.1234,
"idconf": "rCF-0GB-QKZ1gz"
}
]
Getting the list of current conferences (list_conferences)
More about the method parameters in the HTTP REST API description /rest/v1/uc/conferences
[
"list_conferences",
{
"qid": 0.1234
}
]
Getting conference information (get_conference)
Returns conference information, discovering it by identifier (idconf) or by a dialog one of whose subscribers is the conference.
More about the method parameters in the HTTP REST API description /rest/v1/uc/conferences
[
"get_conference",
{
"qid": 0.1234,
"idconf": "rCF-0GB-QKZ1gz"
}
]
or
[
"get_conference",
{
"qid": 0.1234,
"idcall": "4111998404@192.168.0.149",
"idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872"
}
]
[
"get_conference_result",
{
"qid": 0.1234,
"result": "ok",
"data": {
"confid": "rCF-0GB-KbQYEI",
"confnumber": "KbQYEI",
"confroomnum": "9",
"confuri": "<sip:conf-9@test.incoplax.com>",
"site": "main_site",
"startts": 1650533772987
}
}
]
Getting the list of conference participants (get_participants)
Returns the list of current participants of an active conference, discovering it by identifier (idconf).
The conference identifier can be obtained, among other ways, from the dialog with the conference using the get_conference method.
For each participant, the identifier ('participantid') and the call identifier ('callid') are returned.
More about the method parameters in the HTTP REST API description /rest/v1/uc/conferences
[
"get_participants",
{
"qid": 0.1234,
"idconf": "rCF-0GB-QKZ1gz"
}
]
[
"get_participants_result",
{
"qid": 0.1234,
"result": "ok",
"data": [
{
"participantid": "2919aaa2-0180-4b7a-d155-7cd30a921f58",
"callid": "rB2-0GE-CCwUzc-01-913257614@192.168.0.149",
"state": "active"
"luri": "<sip:conf-9@test.incoplax.com>",
"ltag": "rCF-0GB-IrzvfF",
"ruri": "<sip:12@test.incoplax.com>",
"rtag": "rB2-0GE-9UAM"
},
{
"participantid": "e846809b-0180-4b7a-aebb-7cd30a921f58",
"callid": "rB2-0GE-Wix6va-01-823279851@192.168.0.146",
"state": "active"
"luri": "<sip:conf-9@test.incoplax.com>",
"ltag": "rCF-0GB-YGKQhJ",
"ruri": "<sip:13@test.incoplax.com>",
"rtag": "rB2-0GE-CIa0"
}
]
}
]
Getting conference participant information (get_participant)
Returns information about the specified participant of an active conference, discovering it by identifier (idconf).
The conference identifier can be obtained, among other ways, from the dialog with the conference using the get_conference method.
More about the method parameters in the HTTP REST API description /rest/v1/uc/conferences
[
"get_participant",
{
"qid": 0.1234,
"idconf": "rCF-0GB-QKZ1gz",
"participantid": "dcdd6e3e-0180-4bdb-abe3-7cd30a921f58",
}
]
[
"get_participant_result",
{
"qid": 0.1234,
"result": "ok",
"data": {
"participantid": "e846809b-0180-4b7a-aebb-7cd30a921f58",
"callid": "rB2-0GE-Wix6va-01-823279851@192.168.0.146",
"state": "active",
"luri": "sip:conf-9@test.incoplax.com",
"ruri": "sip:13@test.incoplax.com",
"ltag": "rCF-0GB-YGKQhJ",
"rtag": "rB2-0GE-CIa0"
}
}
]
Adding a participant to a conference (attach_participant)
Calls the specified to number from the idconf conference.
More about the method parameters in the HTTP REST API description /rest/v1/uc/conferences
[
"attach_participant",
{
"qid": 0.1234,
"idconf": "rCF-0GB-QKZ1gz",
"to": "102"
}
]
Response — attach_participant_result with the result field and REST API response fields.
Removing a conference participant (detach_participant)
More about the method parameters in the HTTP REST API description /rest/v1/uc/conferences
[
"detach_participant",
{
"qid": 0.1234,
"idconf": "rCF-0GB-QKZ1gz",
"participantid": "dcdd6e3e-0180-4bdb-abe3-7cd30a921f58"
}
]
Response — detach_participant_result with the result field.
Getting conference topology (get_topology)
Returns the current conference topology, discovering it by identifier (idconf).
The conference identifier can be obtained, among other ways, from the dialog with the conference using the get_conference method.
By default the conference always has the "everyone hears everyone" topology. This rule is always first in the output. It is followed by all exceptions: who, whom, and the disable flag.
More about the method parameters in the HTTP REST API description /rest/v1/uc/conferences
[
"get_topology",
{
"qid": 0.1234,
"idconf": "rCF-0GB-QKZ1gz"
}
]
[
"get_topology_result",
{
"qid": 0.1234,
"result": "ok",
"data": [
{
"enabled": true,
"from": "*",
"to": "*"
},
{
"enabled": false,
"from": "e846809b-0180-4b7a-aebb-7cd30a921f58",
"to": "2919aaa2-0180-4b7a-d155-7cd30a921f58"
}
]
}
]
Changing conference topology (set_topology)
Applies a modifier to the current conference topology, discovering it by identifier (idconf).
The conference identifier can be obtained, among other ways, from the dialog with the conference using the get_conference method.
By default the conference always has the "everyone hears everyone" topology. This rule is always first in the output. It is followed by all exceptions: who, whom, and the disable flag.
More about the method parameters in the HTTP REST API description /rest/v1/uc/conferences
[
"set_topology",
{
"qid": 0.1234,
"idconf": "rCF-0GB-QKZ1gz",
"setup": [
{
"from": "e846809b-0180-4b7a-aebb-7cd30a921f58",
"to": "*",
"enabled": false
},
{
"from": "e846809b-0180-4b7a-aebb-7cd30a921f58",
"to": "2919aaa2-0180-4b7a-d155-7cd30a921f58",
"enabled": true
},
]
}
]
[
"set_topology_result",
{
"qid": 0.1234,
"result": "ok",
"confid": "rCF-0GB-KbQYEI"
}
]
Sending a DTMF character to one dialog party (send_dtmf)
Sends DTMF characters to the specified leg of the specified dialog. Sending individual characters and their sequences is supported. The response to the request 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.
Sending can be performed in SIP-INFO or RFC2833 format.
The dialog must exist.
By default sending is performed toward the specified leg.
If the opposite parameter value is true, sending is performed toward the side opposite to the specified one.
Analog of the REST API method SEND_DTMF /rest/v1/uc/calls/:id
[
"send_dtmf",
{
"qid": 0.1234,
"idcall": "4111998404@192.168.0.149",
"idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872",
"opposite": true,
"proto": "sipinfo",
"dtmf": "2"
}
]
Possible proto parameter values:
-
rfc2833- default value. Sending is performed in RTP traffic. -
sipinfo- sending is performed via a SIP INFO message. -
any other value -
rfc2833.
More about the method parameters in the HTTP REST API description /rest/v1/uc/calls
[
"send_dtmf_result",
{
"qid": 123,
"result": "ok",
"dialogid": "rDlg-002-911Jnh"
}
]
Enabling/disabling subscriber speech recognition (start_asr/stop_asr)
Searches for the dialog, determines the leg, and sends a command to start the recording and streaming transcription process. The conversation topology is arranged so that only the speech of the target dialog leg enters the recording.
The dialog must exist and be in the conversation state.
By default the specified leg is transcribed.
If the opposite parameter value is true, the leg selection is inverted.
The layer parameter is optional. It allows creating different layers in the same dialog. Such layers are recorded and recognized independently.
It also allows stopping previous recognition and immediately starting a new one while events from the previous one have not yet stopped arriving — to separate events, for example, when transcribing data entry into various conversation card fields.
When the same value is specified, the previous session ends automatically and a new one starts instead.
The mode works when the speech transcription subsystem is installed and configured (master domain, settings.record_asr_options)
Analog of the REST API method SETUP_ASR /rest/v1/uc/calls/:id
[
"start_asr",
{
"qid": 0.1234,
"idcall": "4111998404@192.168.0.149",
"idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872",
"opposite": false,
"layer": "abcdefg",
"notify": true
}
]
The notify parameter indicates whether events should be sent. By default true — send events as changes appear in the transcript.
If false — partial recognition events are not sent. In this case the result can be obtained in the response when disabling recognition with the result_text=true parameter.
For recognition purposes, recording of the specified leg is activated, and preliminary results are sent with a delay of about 2 seconds. Events with preliminary results are sent to the same connection.
The response returns:
-
dialogid- identifier of the discovered dialog, -
layer- assigned layer, -
eid- generated UUID value for binding events to different closely located sessions.
More about the method parameters in the HTTP REST API description /rest/v1/uc/calls
[
"start_asr_result",
{
"qid": 123,
"result": "ok",
"dialogid": "rDlg-002-911Jnh",
"layer":"abcdefg",
"eid": "12341234-1234-1234-1234-123412341234"
}
]
When the notification mode is selected (notify=true), events with results are sent as speech recognition results appear.
[
"asr_result",
{
"dialogid": "rDlg-002-911Jnh",
"layer": "bbb",
"eid": "12341234-1234-1234-1234-123412341234",
"text": "one two three\r\nfour five six"
}
]
Streaming recognition should be stopped with the same layer that was specified at start.
[
"stop_asr",
{
"qid": 1,
"idconn": "94f2ee21-0678-66bd-0715-9f00000003ee.1656420816464",
"layer":"bbb"
"result_text": true
}
]
-
The
result_textparameter is optional. By default true — wait for recording and recognition to complete, up to 2-3 seconds, and only then send the response together with the final text. If false — the response is immediate, right after recording is disabled. In this case the text parameter is absent from the response. Results after stopping can be collected using events that continue to arrive for some time (about 2-3 seconds).
[
"stop_asr_result",
{
"qid": 1.234,
"dialogid": "rDlg-0GE-SyxZRk",
"layer":"bbb",
"result": "ok",
"text":"one two three\r\nfour five six"
}
]
Enabling/disabling additional recording during a conversation (start_record/stop_record)
Allows selectively enabling conversation recording in the specified layer. Regardless of whether conversation recording is enabled according to rules or a parallel recording process exists — by specifying a unique layer name, a separate recording of the specified time interval can be obtained.
More about the method parameters in the HTTP REST API description /rest/v1/uc/calls
[
"start_record",
{
"qid": 0.1234,
"idcall": "4111998404@192.168.0.149",
"idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872",
"layer": "abcdefg"
}
]
[
"start_record_result",
{
"qid": 1.234,
"dialogid": "rDlg-0GE-SyxZRk",
"layer":"abcdefg",
"result": "ok"
}
]
[
"stop_record",
{
"qid": 0.1234,
"idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872",
"layer": "bbb"
}
]
[
"stop_record_result",
{
"qid": 1.234,
"dialogid": "rDlg-0GE-SyxZRk",
"layer":"bbb",
"result": "ok"
}
]
Enabling/disabling file playback in a conversation (start_play/stop_play)
Adds or removes audio file playback in the dialog in the specified layer.
More about the method parameters in the HTTP REST API description /rest/v1/uc/calls
[
"start_play",
{
"qid": 0.1234,
"idcall": "4111998404@192.168.0.149",
"idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872",
"layer": "promo",
"file": "promo.wav"
}
]
Required parameters for start_play: idcall, idconn; for stop_play: idconn. The layer (layer) defaults to custom_player.
[
"stop_play",
{
"qid": 0.1234,
"idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872",
"layer": "promo"
}
]
Response — start_play_result / stop_play_result with the result field.
Pausing/resuming the main built-in recording during a conversation (pause_recording/resume_recording)
Allows pausing or resuming the main conversation recording.
If recording was not initially enabled, specifically disabled by a suitable conversation recording rule, it can be activated with the resume_recording command — it starts from the moment the command is executed. If recording was not initially enabled because no suitable rule exists, it cannot be activated in this case.
If initially in a cross-domain conversation one domain activated recording and the other did not, recording will not be available for the latter even when resumed after a pause.
More about the method parameters in the HTTP REST API description /rest/v1/uc/calls
[
"pause_recording",
{
"qid": 0.1234,
"idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872"
}
]
[
"pause_recording_result",
{
"qid": 1.234,
"dialogid": "rDlg-0GE-SyxZRk",
"result": "ok"
}
]
[
"pause_recording_result",
{
"qid": 1.234,
"dialogid": "rDlg-0GE-SyxZRk",
"success":false,
"result": "error",
"error_msg": "already_paused"
}
]
Logical failure variants:
-
media_disabled
-
recording_disabled
-
already_paused
-
already_recording
-
pausing_is_restricted_by_recordrule
-
resuming_restricted
Other possible failures are systemic in nature of interaction with the media controller or media gateway.
Dialog label management
Dialog labels are string values bound to specific conversations/dialogs, set via the API or by 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, as well as the post call survey mechanism, are based on labels.
Reading all labels (get_bindings)
Returns all set labels of the specified dialog
More about the method parameters in the HTTP REST API description /rest/v1/uc/calls
[
"get_bindings",
{
"qid": 123,
"idconn":"16661130-068e-da2b-7555-4700000003ee.1678893623349"
}
]
[
"get_bindings_result",
{
"qid": 123,
"result": "ok",
"dialogid": "rDlg-002-911Jnh",
"labels": ["seance_inner_5dBiGQrcFNFimwK3i7kuO9JrlfF","PCS:a:13","aaa"]
}
]
Setting (replacing) labels with the specified ones (set_bindings)
Replaces the current label set of the specified dialog with a new set. A single label as a string or a list of labels as an array of strings may be specified in the 'label' field.
More about the method parameters in the HTTP REST API description /rest/v1/uc/calls
[
"set_bindings",
{
"qid": 123,
"idconn":"16661130-068e-da2b-7555-4700000003ee.1678893623349",
"label": ["aaa","bbb"]
}
]
[
"set_bindings_result",
{
"qid": 123,
"result": "ok",
"dialogid": "rDlg-002-911Jnh"
}
]
Adding the specified labels (add_bindings)
Adds the specified labels to the specified dialog. A single label as a string or a list of labels as an array of strings may be specified in the 'label' field.
More about the method parameters in the HTTP REST API description /rest/v1/uc/calls
[
"add_bindings",
{
"qid": 123,
"idconn":"16661130-068e-da2b-7555-4700000003ee.1678893623349",
"label": ["aaa","bbb"]
}
]
[
"add_bindings_result",
{
"qid": 123,
"result": "ok",
"dialogid": "rDlg-002-911Jnh"
}
]
Removing the specified labels (remove_bindings)
Removes the specified labels from the specified dialog. A single label as a string or a list of labels as an array of strings may be specified in the 'label' field.
More about the method parameters in the HTTP REST API description /rest/v1/uc/calls
[
"remove_bindings",
{
"qid": 123,
"idconn":"16661130-068e-da2b-7555-4700000003ee.1678893623349",
"label": ["aaa","bbb"]
}
]
[
"remove_bindings_result",
{
"qid": 123,
"result": "ok",
"dialogid": "rDlg-002-911Jnh"
}
]
Clearing all labels (clean_bindings)
Clears the specified dialog of labels.
More about the method parameters in the HTTP REST API description /rest/v1/uc/calls
[
"clean_bindings",
{
"qid": 123,
"idconn":"16661130-068e-da2b-7555-4700000003ee.1678893623349"
}
]
[
"clean_bindings_result",
{
"qid": 123,
"result": "ok",
"dialogid": "rDlg-002-911Jnh"
}
]
Checking for a label (contains_bindings)
Replaces the current label set of the specified dialog with a new set. A single label as a string may be specified.
More about the method parameters in the HTTP REST API description /rest/v1/uc/calls
[
"contains_bindings",
{
"qid": 123,
"idconn":"16661130-068e-da2b-7555-4700000003ee.1678893623349",
"label": "aaa"
}
]
[
"contains_bindings_result",
{
"qid": 123,
"result": "ok",
"contains": true,
"dialogid": "rDlg-002-911Jnh"
}
]
SIP user availability (set_sipuser_status)
unavailable — creates for the SIP user number an unconditional redirect rule to the redirectto number; available — deletes this rule.
[
"set_sipuser_status",
{
"qid": 0.1234,
"owner": "sip1",
"status": "unavailable",
"redirectto": "200"
}
]
Parameters:
-
owner— SIP user login or URI (sip:sip1@test.rootdomain.ru), required; -
status—availableorunavailable, required; -
redirectto— redirect number, defaultdnd.
[
"set_sipuser_status_result",
{
"qid": 0.1234,
"result": "ok"
}
]
Setting up Post Call Survey (setup_post_call_survey)
Post Call Survey is a transfer-on-hangup feature. If one dialog subscriber hangs up and the other has the Post Call Survey feature assigned, instead of hanging up their leg receives a REFER to the configured number. As a rule this is the number of the service quality evaluation script.
Places a dialog label of a special format. The B2B role logic serving the dialog works based on the label.
The dialog must exist.
By default the binding is made to the specified leg. That is, the transfer feature is activated for it if the counterpart hangs up.
If the opposite parameter value is true, the binding is made to the opposite leg.
Additional information:
-
PCS is set by a call label with a special format.
-
Setting "to"="" erases a previously set PCS.
-
Setting a new PCS with the setup_post_call_survey method overwrites all previous ones.
-
PCS, like all other labels, is inherited on transfers.
-
PCS is automatically deleted when applied and is not inherited further.
-
PCS is not applied if the call was transferred, and then the label is inherited further.
-
Label format set by the setup_post_call_survey method for 'sticky=true' mode (default):
PCS:aor:ToNumber:AOR, where AOR is a record of the form 'user@domain'. Such a PCS is inherited and will be applied in one of the future dialogs only with respect to the leg whose RemoteURI is equivalent to the AOR in the PCS label. In turn, AOR is determined at the moment the PCS label is set from the RemoteURI of one of the legs based on the 'opposite' flag value and the specified 'idcall'. -
Label format set by the setup_post_call_survey method for 'sticky=false' mode:
PCS:x:ToNumber:IdCallfor opposite=true,PCS:y:ToNumber:IdCallfor opposite=false. Such a PCS, despite inheritance, is not applied after transfers, since the IdCall specified in the PCS label is unique and relates only to the leg of a specific dialog that ended during the transfer. -
Formats
PCS:a:ToNumberandPCS:b:ToNumberare also supported, and after inheritance do not lose effect on transfer.aandbare leg pointers (initiator and callee).
[
"setup_post_call_survey",
{
"qid": 123,
"idconn":"16661130-068e-da2b-7555-4700000003ee.1678893623349",
"idcall": "rB2-0GE-a9SZVY-01-1_3991209766@192.168.0.229",
"opposite": true,
"sticky": true,
"to": "13"
}
]
[
"setup_post_call_survey_result",
{
"qid": 123,
"result": "ok",
"dialogid": "rDlg-002-911Jnh"
}
]
Transcribing a previously recorded conversation (transcribe)
Transcription is the process of accurately converting a recording of spoken speech into written form.
The system can be configured to automatically transcribe all or part of completed and recorded conversations. For conversations that were not transcribed automatically, a late transcription option on request is available.
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.
More about the method parameters in the HTTP REST API description /rest/v1/uc/calls
[
"transcribe",
{
"qid": 123,
"idconn":"16661130-068e-da2b-7555-4700000003ee.1678893623349",
"reclink": "sk:test_s3_records:2025-04-09/15:46/mg12_1883946680-1744213599840.mp3"
}
]
[
"transcribe_result",
{
"qid": 123,
"result": "ok"
}
]
Generating a CTI integration event (cti_event)
Sends an event of the ctievents class of an arbitrary type to master domain subscribers: type, params (object). There is no response.
Description — in the section External events.
ccsevents stream diagnostics (ccs_setup)
Management of the buffer of recent events for reconciling sent and received: commands set_ccsevents_buffer, dump_ccsevents_buffer, ping.
Description — in the section Event stream diagnostics.
Concept of integration with an external system and the product layer
Together with
-
events of the
ccseventsclass, -
events of the
ivreventsclass, -
the IVR script component External control via API,
-
the
ivrapimodule WebSocket interface it allows integration with an external call center management system. -
Each domain can be connected to its own instance of the external management system X.
-
Operators are SIP users of the Incoplax platform domain to which instance X or various systems performing the management function are connected.
-
All calls arrive and are processed in Incoplax.
-
The external system is informed about all calls in the corresponding Incoplax domain. X keeps records of them, provides statistics to users, and tracks operator occupancy.
-
X manages user calls from the client application using the Incoplax CallManager interface.
-
When calls are routed to an IVR script and there reach the "external control" component, Incoplax informs X about it. When leaving this component for any reason, Incoplax also informs X.
-
While in the "external control" component, the subscriber is served by X script logic. For Incoplax all such calls are equivalent, and X holds them in its queues.
-
While subscribers are served in X, X scripts manage media content using commands; the Incoplax "external control" component executes these commands by executing component code: playback, recording, transfer, etc.
-
File exchange is performed via the HTTP interface with hash verification (presumably X uploads and downloads files from Incoplax, but the reverse is also possible).
-
If there is no connection to X when the Incoplax script enters the "external control" component, an immediate exit occurs through failure branch 1.
-
If connection to X is lost during operation of the "external control" component, Incoplax takes no action for N pings, and after they expire exits through failure branch 2.
-
In case of file access failures, interaction does not stop.
-
Calls in Incoplax can be collected into virtual queues to avoid overloading X.
-
Calls in Incoplax can be routed and served bypassing X, including using call-waiting and queues.
-
Any request can end with a successful response, an unsuccessful response, or no response. Integration logic on both sides accounts for these variants.
External system X also has access to APIs of the data model it can use for its own needs and for deeper integration (HTTP REST and Websocket rest). In addition, the Websocket subscr API is useful.
Technological aspects:
-
TCP connection between X and Incoplax. Incoplax connects to Incoplax.
-
Asynchronous duplex protocol based on WebSocket.
-
Each node can send short JSON messages to the other, containing an identifier, name, and parameters.
-
Each message is either an event/asynchronous command, a request, or a response. Request and response have the same identifier. The name in the response is insignificant.
-
X connects to one of the Incoplax web servers; on connection loss X automatically reconnects to the same or any other Incoplax web server.
-
The connection endpoint to Incoplax has an HTTP path containing a GUID defined in the
integration_pointentity in the Incoplax domain with subscription permission. -
Within the duplex asynchronous protocol, the following command groups are distinguished:
-
Connection setup (
setup) -
Ping-pong (
ping) -
Event subscription (
subscr) -
Exchange of call information (sessions, connections) (
calleventsand/orccseventsevents) -
Exchange of operator/SIP user information (
rest) -
User call management (
ccs) -
Management of media modes in IVR (
ivrapi)
-
-
Within the file exchange protocol, the group is distinguished:
-
File CRUD with hashes (
ivrapi, http/rest/v1/fs).
-