Stringee Call Control Object

A Stringee Call Control Object (SCCO) is a JSON array that you use to control the flow of a call. For your SCCO to execute correctly, the JSON objects must be valid.

The order of actions in the SCCO controls the flow of the Call. Actions that have to complete before the next action can be executed are synchronous. Other actions are asynchronous. That is, they are supposed to continue over the following actions until a condition is met. When all the actions in the SCCO are complete, the Call ends.

The SCCO actions and the options and types for each action are:

Action	Description	Synchronous
connect	Connect endpoint such as a phone number or app.	Yes
record	Record call	No
recordMessage	Record a voice message	No
talk	Send synthesized speech to a call	No, unless bargeIn=false
play	Send a uploaded audio file to a call	No, unless bargeIn=false
stream	Send an audio file to a call	No, unless bargeIn=false
input	Collect digits from the person	Yes

Connect

Sample:

[
    {
      "action": "connect",

      "from": {
        "type": "internal",
        "number": "user_1",
        "alias": "user_1"
      },

      "to": {
        "type": "internal",//internal: app-to-app call type
        "number": "user_2",//make a call to user_2
        "alias": "user_2",
      },

      "customData": "test-custom-data",
      "continueOnFail": false,
      "timeout": 45
    }
]

in which:

Name	Description	Required	Default
action	Always is "connect"	Yes
from	JSON data which specify where's the call from	Yes
to	JSON data which specify where's the call to	Yes
customData	Custom data (in String type) is sent to the client's app when the client makes a call or receives an incoming call.	No
continueOnFail	(Bool) Controls what happens when the called party (type: "internal") can not be reached (busy/offline ...). If true, Stringee sends a POST request to the onFailEventUrl. Your server should return another SCCO that replaces the existing SCCO and controls the call.	No	false
onFailEventUrl	(String) Url receives POST request when connect failed and continueOnFail=true	No
timeout	(Int) If the call is unanswered, set the number in seconds before Stringee stops ringing.	No	60
maxConnectTime	(Int) Maximum length of the call in seconds.	No	-1 (unlimited)
peerToPeerCall	(Bool) + true: The media stream of calls will not go through Stringee's server. The calls will be peer-to-peer calls. If the parameter "peerToPeerCall" is "true", the calls can not be recorded, even when you put action "record" before action "connect". + false: The media stream of calls will always go through Stringee'server. If you want the calls to be recorded, the parameter "peerToPeerCall" must be "false" and the action "record" must be placed before action "connect" in the SCCO. Caution: With call types other than app-to-app, all calls will always go through Stringee's server. At the time, the "peerToPeerCall" value does not make sense.	No	true

from/to JSON data:

{
    "type": "internal",
    "number": "user_1",
    "alias": "user_1"
}

in which

Name	Description	Required
type	"internal": The call is from/to Client App (using Stringee SDK); "external": The call is from/to the outside of the Stringee platform	Yes
number	Phone Number or user ID	Yes
alias	number alias name	Yes

Body of POST request to onFailEventUrl:

{
    "call_status": "connect_failed",
    "project_id": Your_project_id,
    "timestamp_ms": 1530868776975,
    "from": {
        "type": "external",
        "number": "from_number",
        "alias": "from_alias",
        "is_online": false
    },
    "to": {
        "type": "internal",
        "number": "user_2",
        "alias": "user_2",
        "is_online": true
    },
    "type": "stringee_call",
    "call_id": "callid",
    "agent_status": "ended",
    "toNumber": "YOUR_STRINGEE_NUMBER",
    "start_time": 1530868766746
}

Field	Type	Description
call_status	String	Call status: - connect_failed
project_id	Long	Project ID
timestamp_ms	Long	timestamp in millisecond
from	JSON	from
to	JSON	to
type	String	- stringee_call
agent_status	String	The called party status: - ended
call_id	String	Call ID
start_time	Long	Time start call

Record

Sample:

[
    {
      "action": "record",
      "eventUrl": "https://example.com/recording",
      "format": "mp3",
    },
    {
      "action": "connect",

      "from": {
        "type": "internal",
        "number": "user_1",
        "alias": "user_1"
      },

      "to": {
        "type": "external",
        "number": "phone_number",
        "alias": "phone_number",
      }
    }
]

in which

Name	Description	Required
action	Always is "record"	Yes
eventUrl	The URL to the webhook endpoint that is called asynchronously when a recording is finished.	No
format	Record the Call in a specific format. Options are: mp3, wav. The default value is mp3.	No
recordStereo	Record the Call in Stereo. Options are: true, false. The default value is false.	No

Record message

Use the recordMessage action to record voice message from the call in your Interactive Voice Response (IVR).

Sample:

[
    {
        "action": "play",
        "fileName": "start_record.wav"
    },
    {
        "action": "recordMessage",
        "eventUrl": "https://example.com/recording",
        "beepStart": "true",
        "timeout": "10"
    },
    {
        "action": "play",
        "fileName": "stop_record.wav",
        "bargeIn": "true"
    }
]

in which

Name	Description	Required
action	Always is "recordMessage"	Yes
eventUrl	The URL to the webhook endpoint that is called asynchronously when a recording is finished.	No
format	Record the Call in a specific format. Options are: mp3, wav. The default value is mp3.	No
endOnKey	Stop recording when a digit is pressed on the handset. Default is #	No
timeout	The maximum length of a recording in seconds.	No
beepStart	Set to true to play a beep when a recording starts	No

Talk

Sample:

[
    {
        "action": "talk",
        "text": "Stringee xin chào quý khách, xin mời quý khách chọn theo hướng dẫn sau. ",
        "voice": "female",
        "speed": 0,
        "bargeIn": true,
        "loop": 3
    }
]

in which

Name	Description	Required	Default
action	Always is "talk"	Yes
text	A string containing the message to be synthesized in the Call.	Yes
voice	The name of the voice used to deliver text. You use the voice that has the correct language, gender and accent for the message you are sending.	No	female
speed	The speed level that the speech is played. This can be any value between -3 to 3	No	0
bargeIn	Set to true so this action is terminated when the user presses a button on the keypad. Use this feature to enable users to choose an option without having to listen to the whole message in your Interactive Voice Response (IVR). If you set bargeIn to true the next action in the SCCO stack must be an input action.	No	true
loop	The number of times text is repeated	No	1
silenceTime	Silence time (milisecond) before talk	No	0
answerCall	Answer the call before play if the call state is ringing	No	true
continueWhilePlay	Continue process the next action while playing	No	false

Voice

Name	Language	Gender
female	vn-VN	female
male	vn-VN	male
hatieumai	vn-VN	female
ngoclam	vn-VN	female
banmai	vn-VN	female
leminh	vn-VN	female
myan	vn-VN	female
lannhi	vn-VN	female
sg_male_xuankien_vdts_48k-hsmm	vn-VN	male
sg_female_xuanhong_vdts_48k-hsmm	vn-VN	female
hn_male_xuantin_vdts_48k-hsmm	vn-VN	male
hn_female_thutrang_phrase_48k-hsmm	vn-VN	female

Play

Sample:

[
    {
        "action": "play",
        "fileName": "Welcome.wav",
        "bargeIn": false,
        "loop": 1
    }
]

in which

Name	Description	Required	Default
action	Always is "play"	Yes
fileName	A file (mp3 or wav (16-bit) audio file uploaded to server) to play to the call . For upload audio file, use this API	Yes
bargeIn	Set to true so this action is terminated when the user presses a button on the keypad. Use this feature to enable users to choose an option without having to listen to the whole message in your Interactive Voice Response (IVR). If you set bargeIn to true the next action in the SCCO stack must be an input action.	No	true
loop	The number of times file is repeated	No	1
silenceTime	Silence time (milisecond) before play	No	0
answerCall	Answer the call before play if the call state is ringing	No	true
continueWhilePlay	Continue process the next action while playing	No	false

Stream

Sample:

[
    {
        "action": "stream",
        "fileName": "https://example.com/streams/music.mp3",
        "bargeIn": false,
        "loop": 1
    }
]

in which

Name	Description	Required	Default
action	Always is "stream"	Yes
fileName	An array containing a single URL to an mp3 or wav (16-bit) audio file to stream to the Call	Yes
bargeIn	Set to true so this action is terminated when the user presses a button on the keypad. Use this feature to enable users to choose an option without having to listen to the whole message in your Interactive Voice Response (IVR). If you set bargeIn to true the next action in the SCCO stack must be an input action.	No	true
loop	The number of times file is repeated	No	1
silenceTime	Silence time (milisecond) before play	No	0
answerCall	Answer the call before play if the call state is ringing	No	true
continueWhilePlay	Continue process the next action while playing	No	false

Input

You can use the input action to collect digits input by the person you are calling. This action is synchronous, Stringee processes the input and forwards it in the parameters sent to the eventURL webhook endpoint you configure in your request. Your webhook endpoint should return another SCCO that replaces the existing SCCO and controls the Call based on the user input. You could use this functionality to create an Interactive Voice Response (IVR). For example, if your user presses 1, you return a connect SCCO that forwards the call to your technical department. The following SCCO example shows how to configure an IVR endpoint:

[
    {
        "action": "play",
        "fileName": "file1.wav",
    },
    {
        "action": "input",
        "eventUrl": "https://example.com/event_url_dtmf.php",
        "submitOnHash": "false",
        "timeout": "15"
    }
]

in which

Name	Description	Required	Default
action	Always is "input"	Yes
eventUrl	Stringee sends the digits pressed by the user to this URL after timeOut pause in activity or when key is pressed (submitOnHash=false) or when # is pressed (submitOnHash=true).	Yes
timeOut	After timeOut seconds if user doesn't press submit key, Stringee sends the digits pressed by the user to eventUrl	No	5
submitOnHash	Set to true so the user's activity is sent to your webhook endpoint at eventUrl after he or she presses #. If # is not pressed the result is submitted after timeOut seconds. The default value is false. That is, the result is sent to your webhook endpoint when user presses any key or after timeOut seconds.	No	false
customField	Custom data is sent back to your webhook endpoint	No
maxDigits	The number of digits the user can press.	No

The body sent to eventUrl

{
    "time": "1537842882823",
    "dtmf": "3",
    "call_id": "call-vn-1-B1P0VSBAWR-1537842863637",
    "customField": "",
    "timeout": false,
}

Name	Description
time
dtmf	The numbers input by user
call_id	The unique ID for this call
customField	Custom data
timeout	True if this input timed out based on the value of timeOut.

Suggestions

Stringee Call Control Object

Connect

Record

Record message

Talk

Play

Stream

Input