'ccs' capability for WebSocket Token API
- Overview
- Server requests
- Ending a call (bye)
- Initiating a new call (new_invite)
- Initiating a new call from IVR (invite_byivr)
- Call interception (pickup)
- Transferring a call to a number (refer)
- Call transfer by spoofing (referreplaces)
- Switching the subscriber device to the HOLD (hold)
- Switching the subscriber device to the TALK (talk)
- Getting a list of current conversations/dialogs (list_connections)
- Getting information about the specified dialog (get_connection)
- Getting a list of current calls/shoulders (list_calls)
- Converting a call to a conference (switch_to_conference)
- Wrapping up the conference (stop_conference)
- Getting a list of current conferences (list_conferences)
- Receiving information about the conference (get_conference)
- Obtaining the list of conference participants (get_participants)
- Receiving information about a conference participant (get_participant)
- Obtaining the conference topology (get_topology)
- Changing the conference topology (set_topology)
- Sending a DTMF character to one side of the dialog (send_dtmf)
- Enable/disable caller speech recognition (start_asr/stop_asr)
- Enable/disable recording during a call (start_record/stop_record)
- Managing dialog labels
- Installation Post Call Survey (setup_post_call_survey)
- Concept of integration with external system and product layer
- References
Overview
Provides an interface for call management (Subset of CallManager REST-API).
Queries that control a specific connection require the 'idconn' parameter. It can be found in ccsevents class events about calls, or in the 'connectionid' field of callevents class events, or in the response to a call collection read request. Requests that control a specific arm of a connection, or have a direction of application, require the 'idcall' parameter. This is the call-Id of the specific arm. It can be found in the events of the ccsevents and callevents classes, or in the response to a call collection read request.
Server requests
Ending a call (bye)
The dialog is forcibly broken by sending a BYE to both parties. If the dialog is in the Forking state, performs a forced termination of the dialog by sending CANCEL to all callers and a failed response to the call initiator.
[ "bye", { "qid": 0.1234, "owner": "", "idcall": "", "idconn": "3694473f-0641-450c-2c15-c00000000002.1601282818792" } ]
Initiating a new call (new_invite)
Makes an intercom call to the initiator device specified in the owner
field on behalf of the CallManager involving an IVR script.
After picking up the handset, makes a transfer to the number specified in the number
field.
If the initiator device does not support or prohibits intercom calling, the first service call is made until the initiator picks up the handset. If the initiator device supports and allows intercom calls, the call being made is answered immediately by the device.
In case the initiator device is already in some dialog at the time of command execution, it either makes a second call or interrupts the current dialog by placing it on hold, depending on the device settings. In this case, if the device supports and allows intrusion via intercom call, the current dialog is put on hold and a new initiated dialog is received and automatically answered by the device. Otherwise, if intrusion is not supported or denied, the device receives and displays a second call waiting for the initiator to pick up the handset.
The case of limiting the number of incoming calls for an account. If the initiator account is configured to limit the number of simultaneous calls, and there are no free trunks at the time the initiated new call arrives, the incoming intercom call cannot go through and the command returns a rejection "rejected".
Case of multiple devices. If the initiator has several devices registered to support and allow intercom calls, the call can be answered automatically on any of them. In this case, the choice of a particular device is effectively random.
[ "new_invite", { "qid": 0.1234, "owner": "sip:sip1@test.rootdomain.ru", "number": "12" } ]
Optional Parameters:
-
owner
- pointer to the URI of the account of the call initiator. Format: 'sip:USERNAME@DOMAIN' or 'NUMBER'. -
use_intercom
- sets the intercom mode of the initiator call. By default 'true'. -
idseance
- session indicator. When you need to make a consultation call that is bound to an existing service session. If no session is specified, the call receives an unmanaged session binding - it can be an empty session, a new session, or an inherited session. The session is set as a binding in the format 'seance_DIR_ID' and is inherited on transfers. -
idparentconn
- parent call pointer. If it is necessary to make an advisory call bound to an existing call. The parent call is set as a binding in the format 'PARENT:acallid:CALLID' and is not inherited in transfers.
The alternative invite
method has a default value for the parameter 'use_intercom' = false.
[ "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 the intercom
type must be configured in the system and available by routes to call the initiator itself on its own behalf.
Optionally the idseance
key can be specified. Its value will be included in the binding label for the current call. Later it will be automatically transferred to all subsequent dialogs of the current session created as a result of transfers.
Allows the characters '
and ,
to be specified in the number. The first such character allocates the remaining sequence as a DTMF pre-dial after a response is received, and each subsequent such character provides a 1-second pause in the set DTMF.
[ "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 retrieveidconn
. -
ivrcallid
- is the ID of the service CALL from the IVR to the Call Initiator. -
acallid
- is the target call ID from the Call Initiator to the called number.
Initiating a new call from IVR (invite_byivr)
Makes the call specified in the number
field on behalf of callerid
and connects it to the IVR script whose code is specified in the field scriptcode
.
If no script is specified, the built-in ext_api_management
script is started with the transfer of control to the external system. The key
field passes the value to the corresponding property of the "External Management" component".
The use_intercom
field allows you to initiate an intercom call to a 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 setting 'false'. -
idseance
- session pointer. When you need to make a call that is bound to an existing service session. If no session is specified, the call gets an unmanaged session binding - it can be an empty session or a new session. The session is set as a binding in the format 'seance_DIR_ID' and is inherited on transfers. -
idparentconn
- parent call pointer. If it is necessary to make an advisory call bound to an existing call. The parent call is set as a binding in the format 'PARENT:acallid:CALLID' and is not inherited in transfers. -
scriptcode
- pointer to the IVR code of the call handler script. If not specified, it is serviced by the built-in 'ext_api_management' script that transfers control to the API (component External management)]]). -
key
- when using the built-in script 'ext_api_management' sets the key passed through it to an API event 'ivrevents.api_start'. -
callerid
- number of the initiator subscriber, substituted by the IVR script in the sent INVITE request, From header, field username. -
callername
- name of the initiator subscriber, inserted by the IVR script into the sent INVITE request, From header, field displayname. -
calltimeout
- response timeout in seconds.
NOTE! For intercom mode to work correctly, a featurecode
with the intercom
type must be configured in the system and available by routes to call the initiator itself on its own behalf.
Optionally the idseance
key can be specified. Its value will be included in the binding label for the current call. Later it will be automatically transferred to all subsequent dialogs of the current session created as a result of transfers.
Allows the characters '
and ,
to be specified in the number. The first such character allocates the remaining sequence as a DTMF pre-dial after a response is received, and each subsequent such character provides a 1-second pause in the set DTMF.
[ "invite_byivr_result", { "qid": 123, "ivrcallid": "rIV-0GC-LBQTDymNxd2hdGyhBu1QNdjTIdz", "result": "answered", "sipcode": 200 } ]
Response Parameters:
* ivrcallid
- is the ID of the service CALL from the IVR to the Call Initiator.
Call interception (pickup)
Produces a call to the request initiator’s device followed by a transfer to a call intercept number.
[ "pickup", { "qid": 0.1234, "owner": "sip:sip2@test.rootdomain.ru", "number": "11", "use_intercom": true } ]
Optional Parameters:
NOTE! If no "number" is specified, a group intercept will be attempted.
NOTE! For intercom mode to work correctly, a featurecode
with the intercom
type must be configured in the system and available by routes to call the initiator itself on its own behalf.
NOTE! For the interception to work correctly, a featurecode
with the pickup
type must be configured in the system and available by routes to call on behalf of the initiator to the specified number (or to a group in case of group interception).
Transferring a call to a number (refer)
Makes a call with the specified dialog shoulder swap (idconn), then initiates a REFER command to transfer it to the specified number. The dialog shoulder defined by the idcall parameter is a REFER initiator. The shoulder opposing it is substituted and translated. The dialog (idconn) and its shoulder (idcall) must exist. The call must be active, and cannot be in a call state, or in a state waiting for a response to a sent request.
The idconn
value comes as part of events of the ccsevents
class, or can be taken from events of the callevents
class either from the connectionid
field, or constructed as a concatenation of the cid
and its
..
[ "refer", { "qid": 0.1234, "owner": "sip:sip2@test.rootdomain.ru", "idcall": "4111998404@192.168.0.149", "idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872", "number": "11" } ]
Optional Parameters:
The idseance
key can be optionally specified. Its value will be included in the binding label to the call initiating the interception by an INVITE request with the Replaces header. Thereafter, it will be automatically transferred to all subsequent dialogs of the current session created as a result of transfers.
Allows the characters '
and ,
to be specified in the number. The first such character allocates the remaining sequence as a DTMF pre-dial after a response is received, and each subsequent such character provides a 1-second pause in the set DTMF.
[ "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 retrieveidconn
. -
new_dialogid
- internal ID of the newly created dialog. It can be used to retrieveidconn
. -
ivrcallid
- ID service call, which the IVR used to cut the dialog and send it to the refer. -
new_acallid
- ID of the target call by which the subscriber started calling the specified number.
Call transfer by spoofing (referreplaces)
Makes a call with a swapped arm of the specified dialog, after which it initiates the REFER command in order to transfer it by swapping it to another dialog. As a result, subscribers of two different dialogs are connected, and requests are sent to their opponents BYE. The dialog (idconn) and the specified arm (idcall) must exist. The call must be active, and cannot be in a call state, or in a state waiting for a response to a sent request. In case the second call does not exist or is in an inappropriate state, the command will result in both callers of the first dialog being disconnected.
The dialog shoulder defined by the idcall parameter is the initiator of the REFER. The dialog shoulder opposite to it is substituted and translated idconn. Similarly, the target arm of the second idconn2 dialog swap is the arm in opposition to the one specified by the parameter idcall2.
The idconn
and idconn2
values come as part of events of the ccsevents
class, or can be taken from events of the callevents
class or from the connectionid
field, or constructed as a concatenation of the cid
and its
.
Typically, this command points both shoulders of the same caller - the initiator of the request - in order to connect opponents from two conversations involving him.
[ "referreplaces", { "qid": 0.1234, "owner": "sip:sip2@test.rootdomain.ru", "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" } ]
The idseance
key can be optionally specified. Its value will be included in the binding label to the call initiating the interception by an INVITE request with the Replaces header. Thereafter, it will be automatically transferred to all subsequent dialogs of the current session created as a result of transfers.
Switching the subscriber device to the HOLD (hold)
Emulates a subscriber pressing the HOLD button (putting his/her opponent in the current call on hold).
The dialog (idconn) and the specified arm (idcall) must exist. The call must be active, and cannot be in a call state or waiting for a response to a sent request.
The idconn
value comes as part of events of the ccsevents
class, or can be taken from events of the callevents
class either from the connectionid
field, or constructed as a concatenation of the cid
and its
..
NOTE! Expansion device support required broadsoft.
NOTE! Applies only if the Allowed-Events
header received from the device during connection establishment contains the value hold
. If the Allowed-Events
header is not present in all requests and responses from the device, a trial NOTIFY request is also sent according to the broadsoft protocol.
[ "hold", { "qid": 0.1234, "owner": "sip:sip2@test.rootdomain.ru", "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 retrieveidconn
. -
slavedialogid
- internal ID of the received dialog. It can be used to retrieveidconn
. -
new_dialogid
- internal ID of the newly created dialog. It can be used to retrieveidconn
. -
ivrcallid
- ID service call, which the IVR used to cut the dialog and send it to the refer. -
new_acallid
- ID of the target call, by which the subscriber of dialog X substituted for the subscriber in the dialog Y.
Switching the subscriber device to the TALK (talk)
Used to automatically hang up the handset on the device to answer an incoming call, as well as to cancel HOLD mode and take the caller off hold.
The dialog (idconn) and the specified arm (idcall) must exist. The call must be active, and cannot be in a call state or waiting for a response to a sent request.
The idconn
value comes as part of events of the ccsevents
class, or can be taken from events of the callevents
class either from the connectionid
field, or constructed as a concatenation of the cid
and its
..
NOTE! Expansion device support required broadsoft.
NOTE! Applies only if the Allowed-Events
header received from the device during connection establishment contains the talk
value. If the Allowed-Events
header is not present in all requests and responses from the device, a trial NOTIFY request is also sent according to the broadsoft protocol.
[ "talk", { "qid": 0.1234, "owner": "sip:sip2@test.rootdomain.ru", "idcall": "4111998404@192.168.0.149", "idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872" } ]
Getting a list of current conversations/dialogs (list_connections)
Returns a list of dialogs in the current domain. Used for periodic synchronization of data. It is assumed that the external system receives and event-based data.
[ "list_connections", { "qid":"1234" } ]
[ "list_connections_result", { "qid":"1234", "data":[ { "a_dn":"SIP4", "a_domain":"test.okteller.ru", "a_number":"14", "a_type":"user", "b_dn":"SIP2**", "b_domain":"test.okteller.ru", "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 the dialog in the current domain.
[ "get_connection", { "qid":"1234", "owner": "sip:sip2@test.rootdomain.ru", "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 a list of current calls/shoulders (list_calls)
Returns a list of calls/shoulders of the current domain. Used for periodic synchronization of data. It is assumed that the external system receives and event-based data.
[ "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.okteller.ru", "side":"b", "state":"connected", "type":"user" }, { "dn":"SIP2**", "id":"1_1683566754@192.168.0.229", "idseance":"1wOVlMzgF96mOjJc5JmqWW7wxp2", "number":"12", "owner":"sip:sip4@test.okteller.ru", "side":"a", "state":"connected", "type":"user" } ], "result":"ok" } ]
Converting a call to a conference (switch_to_conference)
It is used for the organization of confrenecion, including for the purpose of connecting a prompter.
The dialog (idconn) and the specified arm (idcall) must exist. The call must be active, and cannot be in a call state or waiting for a response to a sent request.
[ "switch_to_conference", { "qid": 0.1234, "owner": "sip:sip2@test.rootdomain.ru", "idcall": "4111998404@192.168.0.149", "idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872" } ]
Wrapping up the conference (stop_conference)
Ends the conference and bounces all participants, discovering it by its identifier 'idconf'.
The identifier can be obtained also by dialog with the conference method get_conference
[ "stop_conference", { "qid": 0.1234, "idconf": "rCF-0GB-QKZ1gz" } ]
Getting a list of current conferences (list_conferences)
[ "list_conferences", { "qid": 0.1234 } ]
Receiving information about the conference (get_conference)
Returns information about a conference, discovering it by its identifier (idconf), or by the dialog of which the conference is one of the subscribers.
[ "get_conference", { "qid": 0.1234, "idconf": "rCF-0GB-QKZ1gz" } ]
or
[ "get_conference", { "qid": 0.1234, "owner": "sip:sip2@test.rootdomain.ru", "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.okteller.ru>", "site": "main_site", "startts": 1650533772987 } } ]
Obtaining the list of conference participants (get_participants)
Returns a list of the current participants of the active conference, locating it by its identifier (idconf).
The conference identifier can be retrieved also by dialog with the conference method get_conference
.
An identifier ('participantid') and call ID will be returned for each participant ('callid').
[ "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.okteller.ru>", "ltag": "rCF-0GB-IrzvfF", "ruri": "<sip:12@test.okteller.ru>", "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.okteller.ru>", "ltag": "rCF-0GB-YGKQhJ", "ruri": "<sip:13@test.okteller.ru>", "rtag": "rB2-0GE-CIa0" } ] } ]
Receiving information about a conference participant (get_participant)
Returns information about the specified participant of the active conference, locating it by its identifier (idconf).
The conference identifier can be retrieved also by dialog with the conference method get_conference
.
[ "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.okteller.ru", "ruri": "sip:13@test.okteller.ru", "ltag": "rCF-0GB-YGKQhJ", "rtag": "rB2-0GE-CIa0" } } ]
Obtaining the conference topology (get_topology)
Returns the current conference topology, discovering it by its identifier (idconf).
The conference identifier can be retrieved also by dialog with the conference method get_conference
.
By default, a conference always has an "everyone hears everyone" topology. This rule is always placed first in the output. Next are all the exceptions: who, whom, and the shutdown flag.
[ "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 the conference topology (set_topology)
Applies a modifier to the current conference topology, detecting it by its identifier (idconf).
The conference identifier can be retrieved also by dialog with the conference method get_conference
.
By default, a conference always has an "everyone hears everyone" topology. This rule is always placed first in the output. Next are all the exceptions: who, whom, and the shutdown flag.
[ "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 side of the dialog (send_dtmf)
Implements sending DTMF characters to the specified shoulder of the specified dialog. Sending single characters and sequences of characters is supported. The response to the request is received immediately, but there is a queue in the shoulder to send individual characters. 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.
Sending can be done in SIP-INFO or RFC2833.
Dialogue must exist.
By default, sending is done towards the specified shoulder.
If opposite
= true, the sending is done in the opposite direction to that specified.
Analog of REST-API method SEND_DTMF /rest/v1/uc/calls/:id
[ "send_dtmf", { "qid": 0.1234, "owner": "sip:sip2@test.rootdomain.ru", "idcall": "4111998404@192.168.0.149", "idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872", "opposite": true, "proto": "sipinfo", "dtmf": "2" } ]
Possible parameter values proto
:
-
rfc2833
- default value. Sending is done in RTP traffic. -
sipinfo
- sending is done via SIP message INFO. -
any other value -
rfc2833
.
[ "send_dtmf_result", { "qid": 123, "result": "ok", "dialogid": "rDlg-002-911Jnh" } ]
Enable/disable caller speech recognition (start_asr/stop_asr)
Searches for a dialog, determines the shoulder, and sends a command to start the recording and streaming stenography process. The topology of the conversation is arranged in such a way that only the speech of the target shoulder of the dialog is recorded.
Dialogue must exist and be in a state of conversation.
By default, the specified shoulder is stenographed.
If opposite
= true, the shoulder selection is inverted.
The layer
parameter is optional. Provides the possibility to create different layers in the same dialog. Such layers are written and recognized independently of each other.
It is also possible to stop the previous recognition and immediately start a new one while the previous one is still in progress - in order to divide events, for example, when transcribing data filling in various fields of a conversation card.
If the same value is specified, the previous session will automatically end and a new session will start instead.
The mode works when the speech steno subsystem (master domain) is installed and configured, settings.record_asr_options)
Analog of REST-API method SETUP_ASR /rest/v1/uc/calls/:id
[ "start_asr", { "qid": 0.1234, "owner": "sip:sip2@test.rootdomain.ru", "idcall": "4111998404@192.168.0.149", "idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872", "opposite": false, "layer": "abcdefg", "notify": true } ]
The notify
parameter indicates whether to send events. The default is true - send events as changes occur in the transcript.
If false - partial recognition events will not be sent. The result in this case can be taken in the response when disabling recognition with the parameter result_text
=true.
For recognition purposes, recording of the specified arm is activated and preliminary results are sent with a lag of about 2 seconds. Sending events with preliminary results occurs on the same connection.
The answer returns:
-
dialogid
- identifier of the detected dialog, -
layer
- assigned layer, -
eid
- generated UUID value to bind events to different closely spaced sessions.
[ "start_asr_result", { "qid": 123, "result": "ok", "dialogid": "rDlg-002-911Jnh", "layer":"abcdefg", "eid": "12341234-1234-1234-1234-123412341234" } ]
If you select the mode with notification (notify
=true), events with the results will be sent as speech recognition results occur.
[ "asr_result", { "dialogid": "rDlg-002-911Jnh", "layer": "bbb", "eid": "12341234-1234-1234-1234-123412341234", "text": "one, two, three, four, five, six" } ]
Stop streaming recognition with the same layer
specified at startup.
[ "stop_asr", { "qid": 1, "owner": "sip:sip3@test.okteller.ru", "idconn": "94f2ee21-0678-66bd-0715-9f00000003ee.1656420816464", "idcall": "2451417359@192.168.0.146", "layer":"bbb" "result_text": true } ]
-
The
result_text
parameter is optional. Defaults to true - will wait for the recording and recognition to complete, up to 2-3 seconds, and only then send a response along with the final text. If false - the response is instantaneous, immediately after the record is turned off. In this case, the text parameter will be absent in the response. You can add results after stopping by means of events, which will 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, four, five, six" } ]
Enable/disable recording during a call (start_record/stop_record)
Allows you to pinpoint the conversation recording in the specified layer. Regardless of whether conversation recording is enabled according to the rules, whether there is a parallel recording process - by specifying a unique name for a layer it is possible to get a separate recording of the specified time interval.
[ "start_record", { "qid": 0.1234, "owner": "sip:sip2@test.rootdomain.ru", "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, "owner": "sip:sip2@test.rootdomain.ru", "idcall": "4111998404@192.168.0.149", "idconn": "168fa0ba-0641-4772-cd4e-400000000002.1601292652872", "layer": "bbb" } ]
[ "stop_record_result", { "qid": 1.234, "dialogid": "rDlg-0GE-SyxZRk", "layer":"bbb", "result": "ok" } ]
Managing dialog labels
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.
Tagging is based on the binding to service sessions in the CC, as well as the mechanism of post call survey.
Read all tags (get_bindings)
Returns all set labels of the specified dialog box
[ "get_bindings", { "qid": 123, "owner":"sip:sip4@test.okteller.ru", "idconn":"16661130-068e-da2b-7555-4700000003ee.1678893623349", "idcall": "rB2-0GE-a9SZVY-01-1_3991209766@192.168.0.229" } ]
[ "get_bindings_result", { "qid": 123, "result": "ok", "dialogid": "rDlg-002-911Jnh", "labels": ["seance_inner_5dBiGQrcFNFimwK3i7kuO9JrlfF","PCS:a:13","aaa"] } ]
Installing (replacing) the tags to the specified ones (set_bindings)
Replaces the current set of labels of the specified dialog with a new set. It is allowed to specify one label as a string or a list of labels as an array of strings in the field 'label'.
[ "set_bindings", { "qid": 123, "owner":"sip:sip4@test.okteller.ru", "idconn":"16661130-068e-da2b-7555-4700000003ee.1678893623349", "idcall": "rB2-0GE-a9SZVY-01-1_3991209766@192.168.0.229", "label": ["aaa","bbb"] } ]
[ "set_bindings_result", { "qid": 123, "result": "ok", "dialogid": "rDlg-002-911Jnh" } ]
Adding specified labels (add_bindings)
Adds the specified labels to the specified dialog. It is allowed to specify one label as a string or a list of labels as an array of strings in the field 'label'.
[ "add_bindings", { "qid": 123, "owner":"sip:sip4@test.okteller.ru", "idconn":"16661130-068e-da2b-7555-4700000003ee.1678893623349", "idcall": "rB2-0GE-a9SZVY-01-1_3991209766@192.168.0.229", "label": ["aaa","bbb"] } ]
[ "add_bindings_result", { "qid": 123, "result": "ok", "dialogid": "rDlg-002-911Jnh" } ]
Deleting specified marks (remove_bindings)
Removes the specified labels from the specified dialog. It is allowed to specify one label as a string or a list of labels as an array of strings in the field 'label'.
[ "remove_bindings", { "qid": 123, "owner":"sip:sip4@test.okteller.ru", "idconn":"16661130-068e-da2b-7555-4700000003ee.1678893623349", "idcall": "rB2-0GE-a9SZVY-01-1_3991209766@192.168.0.229", "label": ["aaa","bbb"] } ]
[ "remove_bindings_result", { "qid": 123, "result": "ok", "dialogid": "rDlg-002-911Jnh" } ]
Clearing all tags (clean_bindings)
Clears the specified dialog from labels.
[ "clean_bindings", { "qid": 123, "owner":"sip:sip4@test.okteller.ru", "idconn":"16661130-068e-da2b-7555-4700000003ee.1678893623349", "idcall": "rB2-0GE-a9SZVY-01-1_3991209766@192.168.0.229" } ]
[ "clean_bindings_result", { "qid": 123, "result": "ok", "dialogid": "rDlg-002-911Jnh" } ]
Checking for a tag (contains_bindings)
Replaces the current set of labels of the specified dialog with a new set. It is allowed to specify one label as a string.
[ "contains_bindings", { "qid": 123, "owner":"sip:sip4@test.okteller.ru", "idconn":"16661130-068e-da2b-7555-4700000003ee.1678893623349", "idcall": "rB2-0GE-a9SZVY-01-1_3991209766@192.168.0.229", "label": "aaa" } ]
[ "contains_bindings_result", { "qid": 123, "result": "ok", "contains": true, "dialogid": "rDlg-002-911Jnh" } ]
Installation Post Call Survey (setup_post_call_survey)
Post Call Survey - rebound transfer function. If one dialog caller hangs up, and a Post Call Survey is assigned to the other, their shoulder receives a REFER to the assigned number instead of a rebound. This is typically the number of the service level assessment scenario.
Places a dialog label of a special format. Based on the label, the logic of the B2B role serving the dialog works.
Dialogue must exist.
By default, binding is performed to the specified shoulder. That is, the transfer function is activated with respect to it if the opponent hangs up.
If opposite
= true, the binding is done to the opposite arm.
Additional information:
-
PCS is set by a bell tag with a special format.
-
Setting "to"="" erases the previously set PCS.
-
Installing a new PCS using the setup_post_call_survey method will overwrite all previous ones.
-
PCS, like all other labels, are inherited in transfers.
-
PCS is automatically deleted when applied and is not inherited further.
-
PCS does not apply if the call has been translated, in which case the label is inherited further.
-
The format of the label to be set by the setup_post_call_survey method for the 'sticky=true' mode (default):
PCS:aor:ToNumber:AOR
, where AOR is an entry of the form 'user@domain'. Such a PCS is inherited, and will be applied in a future dialog only to a shoulder whose RemoteURI is equivalent to the AOR in the PCS label. In turn, the AOR is determined at the time of setting the PCS label from the RemoteURI of one of the arms based on the value of the 'opposite' flag and the specified 'idcall'. -
The format of the label set by the setup_post_call_survey method for the 'sticky=false' mode is
PCS:x:ToNumber:IdCall
for opposite=true,PCS:y:ToNumber:IdCall
for opposite=false. Such a PCS, despite inheritance, is not applied after transfers, because the IdCall label specified in the PCS is unique and relates only to the shoulder of a particular dialog that ended during the transfer. -
The format
PCS:a:ToNumber
andPCS:b:ToNumber
are also supported, and after inheritance, they do not lose effect upon transfer.a
andb
are shoulder pointers (initiator and called).
[ "setup_post_call_survey", { "qid": 123, "owner":"sip:sip4@test.okteller.ru", "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" } ]
Concept of integration with external system and product layer
In conjunction with
-
class events
ccsevents
, -
class events
ivrevents
, -
component ivr-script External management via API,
-
websocket-by the module interface
ivrapi
allows integration with an external call center management system. -
Each domain can have its own instance of an external management system connected to it X.
-
Operators are considered sip users of the Incoplax platform domain to which the X instance or the various systems performing the management function are connected.
-
All calls are received and handled in Incoplax.
-
External with is informed about all calls in the corresponding Incoplax domain. X keeps track of them, provides users with statistics, and monitors operator occupancy.
-
X manages user calls from the client application using the interface Incoplax CallManager.
-
The moment calls are routed to the IVR script and there get to the "external management" component, Incoplax informs X about it. Leaving this component for any reason Incoplax also informs Incoplax X.
-
While in the "external management" component, the caller is served by X’s scripting logic. For Incoplax all such calls are equal, and X holds them in its queues.
-
While serving subscribers in X, X scripts control media content with commands, the "external control" component Incoplax executes these commands by executing component code: play, record, translate, etc.
-
Files are exchanged via HTTP interface with hash verification (presumably X posts and downloads files from Incoplax, but possibly vice versa)
-
If there is no communication with X when the Incoplax script enters the "external control" component, an instant exit on the failed branch is performed 1.
-
If communication with X is lost while the "external control" component is running, Incoplax takes no action for N pings, and when they expire, performs a failing branch exit 2.
-
In case of file access failures, the interaction is not terminated.
-
Calls to Incoplax can be collected into virtual queues so as not to overload the X.
-
Calls to Incoplax can be routed and serviced bypassing X, including using call-waiting and queuing.
-
Any request can end with a successful response, an unsuccessful response, or no response. The integration logic on both sides takes these options into account.
The external X system also has access to the APIs (HTTP REST and Websocket rest) of the data model, which it can use both for its own needs and for deeper integration purposes. In addition to these are useful API Websocket subscr.
Technological Aspects:
-
TCP connection between X and Incoplax. Incoplax is connected to the Incoplax.
-
Asynchronous duplex protocol based on WebSocket.
-
Each of the nodes can send short messages to each other in JSON format containing an identifier, a name, and parameters.
-
Each message is either an event/asynchronous command, a request, or a response. A request and a response have the same identifier. The title in the response is insignificant.
-
X connects to one of the Incoplax web servers, if X loses connection, it will automatically reconnect to the same or any other web server Incoplax.
-
The connection point to Incoplax has an HTTP path containing the GUID defined in the entity
integration_point
in the Incoplax domain with subscription permission. -
The following groups of commands are distinguished within the duplex asynchronous protocol:
-
Connection setup (
setup
) -
Ping-Pong (
ping
) -
Subscribe to events (
subscr
) -
Exchange of information about calls (sessions, connections) (
callevents
events and/orccsevents
) -
Exchange of information about operators/sip-users (
rest
) -
User call management (
ccs
) -
Managing media modes in IVR (
ivrapi
)
-
-
As part of the file sharing protocol, a group is allocated:
-
CRUD hash files (
ivrapi
, http/rest/v1/fs
).
-
References
-
Component 'Operation' scripts for call management.