Suggestions

close search

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

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