What is voice utils?
The voiceUtils library is available for any programmatic modifications or updates that the developer may want to make specifically for the SmartAssist Voice Gateway. This library is used for various functionalities like:
- Hangup
- Agent Transfer (via Invite and Refer)
- Abort Prompt
- Play and Pause Audio etc
These functions can be used in the SmartAssist Voice Gateway channel specific inside Java script section in the Message Node.
Adding a sample screenshot for reference:
a) Hangup
This function is used to forcefully hangup the call from Bot In mid of Flow/Call
This will play the Message and then Hangup the Call with passing the headers
This will also used to send Dynamically SIP headers In bye (Similar to SIP Bye)
Syntax: print(voiceUtils.hangup(message,headers,queueCommand))
All message and headers , queueCommand are optional Parameters
| Options | Description | Type | Required |
|---|---|---|---|
| Message | Message to play before Hangup | String | No |
| Headers | An object containing SIP headers to include in the BYE request | Object | No |
| queueCommand | If true, queue this command until previous commands are completed; otherwise, interrupt and flush all previous commands and execute this command immediately | Boolean | No (By default True) |
1) With message and headers
var message = "Call completed";
var headers : {
"X-Reason" : "Call hangup from Kore side"
}
print(voiceUtils.hangup(message,headers));
2) Without Message but containg headers
var message = "";
var headers = { "X-Reason" : "completed"}
print(voiceUtils.hangup(message,headers));
Note: IF only headers are to be sent and skip message, send an empty string as the first argument.
b) Abort Prompt
This function aborts all pending prompts that arrived before it was sent. For example, if the bot sends an abortPrompts immediately after 3 prompt messages, even if the first prompt message is still playing, the first prompt will stop, and the remaining two prompts will not be played at all.
Syntax: print(voiceUtils.abortPrompt())
“Message” parameter is optional
| Options | Descriptions | Type | Required |
|---|---|---|---|
| Message | Kill the previous command and play the configured msg | String | Na |
Note:- It supports .wav files and multiple messages also but it should send as an array of messages
var message = "Aborting the Previous Message",
print(voiceUtils.abort(message))
//without message
print(voiceUtils.abortPrompt())
c) SIP Refer
This function is to transfer the call To External Contact Number (Telephone Number / SIP URI ) . Call will disconnect after Refer
Syntax: print(voiceUtils.refer(message,ReferTo,headers,queueCommand))
| Options | Description | Type | Required |
|---|---|---|---|
| message | Play Message before Transfering call to Agent | String | Na |
| ReferTo | A sip uri or a phone number / user identifier | String | Yes |
| headers | Additional SIP headers to include in the response | Object | Na |
| queueCommand | If true, queue this command until previous commands are completed; otherwise, interrupt and flush all previous commands and execute this command immediately | Boolean | Na (Default:True) |
1) Using all the options
var message = "Transferring Call to xxxx number";
var ReferTo = "+91xxxxxxxxxx"; // or sipUrl
var headers: {
"X-Reason" : "Call Received from Kore"
}
print(voiceUtils.refer(message,ExternalPhoneNumber,headers))
2) without Message and headers
var message = "";
print(voiceUtils.refer(message,ReferTo));
3) With QueueCommand
var message = "" , headers = {}, referTo = "sip:test@5060"
print(voiceUtils.refer(message,ReferTo,headers,false));
d) SIP Invite
SIP Invite means Conference of User-Bot-ThirdParty Agent . Bot Leg will be active after calls connect to a third party and after call end bot call will be continued Again . CallerId , the target is the mandatory field (containing either SIP URI or number). Pass empty string in message then pass callerId and target
CallerId – Call ID Bot Number that will do the bridge of Call
Target - is the mandatory field (containing either SIP URI or number).
Message - Optional
Syntax: print(voiceUtils.invite(message, callerId, target,headers,queueCommand))
Note : Passing Headers Functionality will be available after 3.1.0/10.2.0 Release (27th april)
| Options | Description | Type | Required |
|---|---|---|---|
| Message | Message to play before Transferring call to Third Party | String | No |
| CallerId | The inbound caller’s phone number, which is displayed to the number that was dialed. The caller ID must be a valid E.164 number. | String containing phone number with country code (Bot Number) | Yes |
| Target | The target property specifies the call destinations | String (SIP URI) | Yes |
| Headers | Additional SIP headers to include in the response | Object | Na |
| QueueCommand | If true, queue this command until previous commands are completed; otherwise, interrupt and flush all previous commands and execute this command immediately | Boolean | No (Default: True) |
let callerId = "+1901xxxx";
let target = "sip:test.com:5060";
let message = "SIP Invite Transfer"
let headers = {
"X-CallId" : "xxxxx"
}
print(voiceUtils.invite(message,callerId,target,headers))
e) Send DTMF
It is use for Sending DTMF digit from Bot . These are sent as RTP payloads using RFC 2833.
When one bot interact with other bot and try to give DTMF Input
| Options | Description | Type | Required |
|---|---|---|---|
| dtmf | a string containing a sequence of dtmf digits (0-9,*,#) | string | Yes |
| Duration | The length of each digit, in milliseconds, Defaults to 500 | number | Default value : 500 |
let dtmf = "99865",
let duration = 600
print(voiceUtils.sendDTMF(dtmf,duration))
f) Pause And Play
The pause command waits silently for a specified number of seconds.
Play is Optional , If you pass the message it will play after pause
Syntax : print(voiceUtils.pauseAndPlay(length,message))
| Options | Description | Type | Required |
|---|---|---|---|
| length | number of seconds to wait before continuing the app | Number (Second) Ex - 4: Default is 3 seconds | yes |
| message | Play the message after executing the pause time | String or Array of string containing url and string [“this is message” , “https://text.wav”] | No |
let length = 4,
let message = "After 4 second this message will play"
print(voiceUtils.pauseAndPlay(length,message))
g) Play
The play command is used to stream recorded audio to a call or Text Message . For Supporting both
Syntax : print(voiceUtils.play(message))
| Options | Descriptions | Type | Required |
|---|---|---|---|
| message | To Play Text Message and Audio Url | String - Only Message Array of String - Both Audio Url and Message | yes |
let message = [“this is First message”, “https://audiofiile.wav” , “this is second Message”]
// All three message will be played in Sequence WIse (Text Message -> Audio File -> Text Message)
print(voiceUtils.play(message))
Please do let us know if you have any further queries on the voice utils library or functions.