Call Handle, Status, and Callback (Webhook)

Flow: Call Handle

Call Handle

Flow: Call Status

Call Status

Call Handle: Setup, Alert, Connect, and Disconnect Parameters

The following parameters are shared across the Setup, Alert, Connect, and Disconnect events.

Parameter Name Description
result 0 = Success; <0 = Error Code
result_desc Result description
service_name Service name
channel Channel ID within session
session_id Unique call session ID
call_status Call status value:
  • SETUP = Calling
  • ALERT = Alerting
  • CONNECT = Connected
  • DISCONNECT = Disconnected
calling_party Calling party number
called_party Called party number
redirecting_number Redirecting number
direction 0 = Inbound
1 = Outbound
reference_id Custom reference ID
call_setup_time Call setup time in YYYY-MM-DD hh:mm:ss format
(E.g. 2018-06-22 15:32:08}
call_alert_time Call alert time in YYYY-MM-DD hh:mm:ss format
(E.g. 2018-06-22 15:32:08)
call_connected_time Call connected time in YYYY-MM-DD hh:mm:ss format
(E.g. 2018-06-22 15:32:08)
call_disconnected_time Call disconnected time in YYYY-MM-DD hh:mm:ss format
(E.g. 2018-06-22 15:32:08)
gmt Time zone. For example, 8 for Singapore, 0 for London / GMT
call_cause SIP Status Code defined in RFC 3261 or refer to Call Status Code List
call_connected 1 = Call connected
0 = Call not connected
call_duration Call duration in seconds

Call Handle: DTMF Parameters

The table below lists DTMF parameters and their descriptions.

Parameter Value
service_name Service name
session_id Unique call session id
channel Channel ID within session
call_status Call Status Value:
DTMF = DTMF Input
number the number subscribed to this service
direction 0 = Inbound; 1 = Outbound
dtmf Collection of DTMF value, e.g. 0~9, *, #
referenceid Custom reference ID

Call Handle: Handle Callback Event

The tabbed example below illustrates how one might implement a call flow for handling automated callbacks.

Handle Callback Event
Example use of Handle Callback

Setup

Parameter Value
result 0
result_desc Ok
service_name PROGRAMMABLE_CALL
channel 0
session_id 123
call_status SETUP
calling_party 6531234567
called_party 6591234567
redirecting_number
direction 0
reference_id myrefid_123
call_setup_time 2018-06-22 13:28:00
call_alert_time 2018-06-22 13:28:00
call_connected_time
call_disconnected_time
gmt 8
call_cause
call_connected 0
call_duration 0

Call Handle Commands

Call Handling: MAKE, SLEEP, DROP SESSIONS, HANGUP

MakeCall

Parameter Required Value
function Yes MakeCall
calling_party Yes Calling party number
called_party Yes Called party number
ringtone No Play ringtone, valid value
Default =
au = Australian
eu =European
jp = Japanese
uk = UK
us = US
record_call No Record conversation
Default value = "false"
Valid value = “true” or “false”
record_callback_method No Record status callback method
Valid value = “GET” or “POST”
record_callback_url No Record status callback URL
handle_interrupt No Force callback to handle URL when outbound call disconnected.
Default = "false"
Valid value = “true” or “false”
Call Handling: PLAY TTS, PLAY FILE, START/STOP RECORDING

Play TTS

Parameter Required Value
function Yes PlayTTS
message Yes Text to speech message
voice Yes f = female, m = male
language Yes Two letter language abbreviation (e.g. “en” = English)
See also “Text-to-Speech Language Support
dtmf No Collect DTMF input
Valid range = 0 ~ 20
Default = 0
replay No Replay TTS
Valid range = 0 ~ 3
Default = 0
Note: if dtmf = 0, TTS will replay based on replay value, if dtmf >0, TTS will replay only if no input
no_dtmf_message No Text to speech message, only play if dtmf >0 and no input, if no_dtmf_message not provided, “message” will be played.
Default =
handle_interrupt No Force callback to handle URL after DTMF input, subsequence command will be deleted, new command will be executed based on callback returned. See: Handle Callback Event – DTMF for details.
Valid value = “true” or “false”
Default = “false”
Note

System will answer the incoming call if PlayTTS on incoming call.

Scenarios
The code samples provided below are for reference, only.
Scenario: PlayTTS and MakeCall
{
  	"commands": [
      {
        "function":"PlayTTS",
        "message":"This is a test message!",
        "voice":"f",
        "language":"en",
        "dtmf":0,
        "replay":0
      },
      {
        "function":"MakeCall",
        "called_party":"6531234567",
        "calling_party":"6598765432",
        "ringtone":"us",
      }
    ]
}

Status Callback Event

The events related to call status and the their parameters are below, along with sample values, for your reference.

Call Status Event
Example use of Call Status Function

Setup

Parameter Value
result 0
result_desc OK
service_name PROGRAMMABLE_CALL
channel 0
session_id 123
call_status SETUP
calling_party 6531234567
called_party 6591234567
redirecting_number
direction 0
reference_id myrefid_123
call_setup_time 2018-06-22 13:28
call_alert_time
call_connected_time
call_disconnected_time
gmt 8
call_cause
call_connected 0
call_duration 0

Error Callback (Webhook)

Parameters

Name Description
result 0 = Success
<0 = Error code
result_desc Result description
service_name Service name
session_id Unique call session ID
call_status Call status value: ERROR

Call Recording Callback (Webhook)

Parameters

Name Description
service_name Service name
session_id Unique call session ID
call_status Recording status, i.e. START_RECORD/END_RECORD
start_time Recording start time
end_time Recording end time
duration Recording duration
reference_id Custom reference ID