Methods
Objects
Control phone calls in real-time!
When using real-time, we are the HTTP Client, and you are the HTTP Server. It means that you have to configure an URL we will communicate with to request actions.
The URL is configured in a REALTIME10 object. See the method apps.create.
Real-Time works with both inbound and outbound calls. If you want to start an outbound call, check the method calls.realtime.
We will send POST requests to your server with the call status, and the result of the previous command (if any). Your server must reply with a command, within 5 seconds. As soon as the command is completed, we will POST the result to your server, you reply with another command, and so on.
You control the call in real-time!
POST requests we make to your server are RT.Request:
POST /your.url HTTP/1.1
Host: your.host.here
Accept: */*
Content-Length: 219
Content-Type: application/json
{
"app":"4346423A",
"callid":421889,
"request_hash":"4260XMAQ",
"cli_name":"",
"cli_number":"",
"date_started":"2012-01-09 17:27:55",
"number":"+33612345678",
"command":"",
"command_id":0,
"command_result":"",
"command_error":"",
"call_status":"UP",
"cdr_field":"000CUSTOMFIELD42",
"variables":{}
}
And your reply must be a JSON object of RT.Response:
HTTP/1.1 200 OK
Date: Thu, 01 Jan 2012 17:42:01 GMT
Server: nginx
Vary: Accept-Encoding
Content-Length: 114
Content-Type: application/json
{
"command":"read",
"command_id":1,
"params":{
"media_id":"TTS|TTS_FR-FR_AUDREY|Bonjour, appuyez sur \u00e9toile",
"max_digits":1,
"attempts":1,
"timeout_ms":4000
},
"variables":{}
}
Command | Description |
---|---|
conference | Dynamically create a conference room (if needed) and send the current call in it. Can be used to bridge calls together. This is a blocking command until the room is closed. The user can leave the conference room by pressing * (star). |
dialout | Makes another call, and bridges the call on answer. If the call is successful, both legs of the call will be hangup if one party hangs up. |
hangup | Hangup the current call. |
hangup_callid | Hangup a specific callid |
play | Plays a Media.Library or say something with the Text-to-Speech |
play_record | Plays a recording recorded with the "record" command. |
play_talk_detect | Plays a Media with talk detection. During the playback of the file, audio is monitored, and if a period of non-silence which is greater than $min_ms yet less than $max_ms is followed by silence for at least $silence_ms, which occurs during the first $analysistime_ms, then the audio playback is aborted, and "TALK" is returned. |
play_wav_data | Plays WAV data (sent directly) |
read | Plays a Media and wait for a DTMF input at the same time. The DTMF input must end with a # , or reach the 'max_digits' parameter. |
record | Record the user. The recording can be stopped by pressing the hash key '#', when silence is detected, or when maximum recording duration is reached. |
send_dtmf | Send DTMF digits. |
simple_conference | Simple conference bridge. This is a blocking command until the room is closed. The user can leave the conference room by pressing * (star) |
start_call_recording | Start call recording. This will create a Media.Recording object. |
stop_call_recording | Stop call recording |
wait | Wait for a few seconds. |
wait_for_silence | Wait until silence is detected, or timeout is reached. |
conference
Dynamically create a conference room (if needed) and send the current call in it. Can be used to bridge calls together. This is a blocking command until the room is closed. The user can leave the conference room by pressing * (star).
command: "conference"
params: {
string auto_leave_announce,
bool auto_leave_when_alone,
string id,
string pin_code,
string pin_error,
int pin_max_tries,
string pin_prompt,
string pin_valid,
int pin_wait,
string user_join,
string user_leave,
string waiting,
string welcome
}
{
"auto_leave_announce": "(string)",
"auto_leave_when_alone": false,
"id": "(string)",
"pin_code": "(string)",
"pin_error": "(string)",
"pin_max_tries": 0,
"pin_prompt": "(string)",
"pin_valid": "(string)",
"pin_wait": 0,
"user_join": "(string)",
"user_leave": "(string)",
"waiting": "(string)",
"welcome": "(string)"
}
Values are auto-generated and may not be correct. Sub-objects are not shown.
Parameter | Type | Description |
---|---|---|
auto_leave_announce | string |
Media played when leaving the conference room because you are the last participant. Format: rt_media (Media ID (int) or Text-to-Speech "TTS|TTS_EN-GB_DANIEL|Text to say") |
auto_leave_when_alone | bool | Automatically leave the conference room when you're the last participant. Only applies when someone leaves - it does not apply when you are joining and you are first. |
id | string |
Conference room ID. Obviously, you have to set the same id on the calls you wish to bridge... Format: rt_conference_id (Conference ID) |
pin_code | string | PIN code to ask for. Callee must press # after the PIN. Leave empty for auto-joining. Digits only (10 max). |
pin_error | string |
Media played when the PIN is not valid. Format: rt_media (Media ID (int) or Text-to-Speech "TTS|TTS_EN-GB_DANIEL|Text to say") |
pin_max_tries | int | How many times do we ask for the PIN? |
pin_prompt | string |
Media played to ask for a PIN code. Will be repeated until a PIN is entered. Format: rt_media (Media ID (int) or Text-to-Speech "TTS|TTS_EN-GB_DANIEL|Text to say") |
pin_valid | string |
Media played when the PIN is valid. Format: rt_media (Media ID (int) or Text-to-Speech "TTS|TTS_EN-GB_DANIEL|Text to say") |
pin_wait | int | The number of seconds to wait for a digit response. |
user_join | string |
Media played when someone joins the conference room Format: rt_media (Media ID (int) or Text-to-Speech "TTS|TTS_EN-GB_DANIEL|Text to say") |
user_leave | string |
Media played when someone leaves the conference room Format: rt_media (Media ID (int) or Text-to-Speech "TTS|TTS_EN-GB_DANIEL|Text to say") |
waiting | string |
Media played in a loop while there is only one participant. Format: rt_media (Media ID (int) or Text-to-Speech "TTS|TTS_EN-GB_DANIEL|Text to say") |
welcome | string |
Media played before joining the conference (and before optional pin_prompt) Format: rt_media (Media ID (int) or Text-to-Speech "TTS|TTS_EN-GB_DANIEL|Text to say") |
Type | Value | Description |
---|---|---|
string | CONFERENCE_CLOSED | The conference room has been closed |
string | LAST_PARTICIPANT | You left the conference room because you were the last participant |
string | LEFT_CONFERENCE | The user left the conference (by pressing ) |
string | PIN_ERROR | The user did not enter the correct PIN code |
string | PIN_TIMEOUT | The user did not enter any PIN code |
dialout
Makes another call, and bridges the call on answer. If the call is successful, both legs of the call will be hangup if one party hangs up.
command: "dialout"
params: {
string cdr_field,
string cli,
string ringtone,
array targets,
string whisper
}
{
"cdr_field": "(string)",
"cli": "(string)",
"ringtone": "RING",
"targets": [],
"whisper": "(string)"
}
Values are auto-generated and may not be correct. Sub-objects are not shown.
Parameter | Type | Description |
---|---|---|
cdr_field | string |
Custom value written in the CDR. You can set anything you want. Useful to match calls with your database. Format: cdr_customer_field (32 alphanumeric characters maximum) |
cli | string |
Outbound Caller ID. Format: cli_phone_number (International E.164 format "+CCNSN". Example: "+16467890800", "+447890123456", "+33678912345" or "BLOCKED") |
ringtone | string |
Plays music or classic ringtone. Values: "MUSIC", "RING" |
targets | array |
Phone numbers called sequentially until one answers Array of objects: Target |
whisper | string |
Callee whispering Media Format: rt_media (Media ID (int) or Text-to-Speech "TTS|TTS_EN-GB_DANIEL|Text to say") |
Type | Value | Description |
---|---|---|
string | NOANSWER | No one answered the call. |
hangup
Hangup the current call.
command: "hangup"
params: {
}
{
}
Values are auto-generated and may not be correct. Sub-objects are not shown.
hangup_callid
Hangup a specific callid
command: "hangup_callid"
params: {
int callid
}
{
"callid": 0
}
Values are auto-generated and may not be correct. Sub-objects are not shown.
Parameter | Type | Description |
---|---|---|
callid | int |
The callid you wish to hang up. Format: callid (64-bit unsigned integer) |
play
Plays a Media.Library or say something with the Text-to-Speech
command: "play"
params: {
string media_id
}
{
"media_id": "(string)"
}
Values are auto-generated and may not be correct. Sub-objects are not shown.
Parameter | Type | Description |
---|---|---|
media_id | string |
Media ID or Text to say Format: rt_media (Media ID (int) or Text-to-Speech "TTS|TTS_EN-GB_DANIEL|Text to say") |
Type | Value | Description |
---|---|---|
string | 0 | Play successful. |
string | 1 | An error occured. |
play_record
Plays a recording recorded with the "record" command.
command: "play_record"
params: {
string media_file
}
{
"media_file": "(string)"
}
Values are auto-generated and may not be correct. Sub-objects are not shown.
Parameter | Type | Description |
---|---|---|
media_file | string | Temporary file name |
Type | Value | Description |
---|---|---|
string | 0 | Play successful. |
string | 1 | An error occured. |
play_talk_detect
Plays a Media with talk detection. During the playback of the file, audio is monitored, and if a period of non-silence which is greater than $min_ms yet less than $max_ms is followed by silence for at least $silence_ms, which occurs during the first $analysistime_ms, then the audio playback is aborted, and "TALK" is returned.
command: "play_talk_detect"
params: {
int analysistime_ms,
int max_ms,
string media_id,
int min_ms,
int silence_ms
}
{
"analysistime_ms": 0,
"max_ms": 0,
"media_id": "(string)",
"min_ms": 0,
"silence_ms": 0
}
Values are auto-generated and may not be correct. Sub-objects are not shown.
Parameter | Type | Description |
---|---|---|
analysistime_ms | int | Analysis time. min:1 max:60000 recommended:4000 |
max_ms | int | Maximum non-silence duration. min:1 max:60000 recommended:60000 |
media_id | string |
Message Format: rt_media (Media ID (int) or Text-to-Speech "TTS|TTS_EN-GB_DANIEL|Text to say") |
min_ms | int | Minimum non-silence duration. min:1 max:60000 recommended:500 |
silence_ms | int | Silence after non-silence. min:1 max:5000 recommended:5 |
Type | Value | Description |
---|---|---|
string | 0 | talk not detected. |
string | TALK | talk detected! |
play_wav_data
Plays WAV data (sent directly)
command: "play_wav_data"
params: {
string audio_data
}
{
"audio_data": "(string)"
}
Values are auto-generated and may not be correct. Sub-objects are not shown.
Parameter | Type | Description |
---|---|---|
audio_data | string | BASE64 encoded WAV file. MUST BE 8000Hz (8Khz), 16bit, mono. |
Type | Value | Description |
---|---|---|
string | 0 | Play successful. |
string | 1 | An error occured. |
read
Plays a Media and wait for a DTMF input at the same time. The DTMF input must end with a # , or reach the 'max_digits' parameter.
command: "read"
params: {
int attempts,
int max_digits,
string media_id,
int timeout_ms
}
{
"attempts": 0,
"max_digits": 0,
"media_id": "(string)",
"timeout_ms": 0
}
Values are auto-generated and may not be correct. Sub-objects are not shown.
Parameter | Type | Description |
---|---|---|
attempts | int | Maximum attempts. min:1 max:10 |
max_digits | int | Maximum digits. min:1 max:20 |
media_id | string |
Prompt message Format: rt_media (Media ID (int) or Text-to-Speech "TTS|TTS_EN-GB_DANIEL|Text to say") |
timeout_ms | int | Input timeout in milliseconds. min:100 max:30000 |
Type | Value | Description |
---|---|---|
string | (KEYS) | The keys pressed by the user. Example : "345". |
string | TIMEOUT | The user did not press #, nor enough keys to reach "max_digits", before the timeout occured. |
record
Record the user. The recording can be stopped by pressing the hash key '#', when silence is detected, or when maximum recording duration is reached.
command: "record"
params: {
int max_duration,
int silence
}
{
"max_duration": 0,
"silence": 0
}
Values are auto-generated and may not be correct. Sub-objects are not shown.
Parameter | Type | Description |
---|---|---|
max_duration | int | (seconds) Maximum recording duration. Min:0 (disabled), Max:300. |
silence | int | (seconds) Stop recording on silence. Min:0 (disabled), Max:20. |
Type | Value | Description |
---|---|---|
string | media_file | Temporary filename you can use with "play_record" |
send_dtmf
Send DTMF digits.
command: "send_dtmf"
params: {
string digits,
int duration_ms,
int timeout_ms
}
{
"digits": "(string)",
"duration_ms": 0,
"timeout_ms": 0
}
Values are auto-generated and may not be correct. Sub-objects are not shown.
Parameter | Type | Description |
---|---|---|
digits | string | Digits to send (0-9, *, #). Example : "123#" |
duration_ms | int | (milliseconds) Duration of each digit. Min: 1, Max: 5000. |
timeout_ms | int | (milliseconds) Amount of time between tones. Min: 0, Max: 10000. |
Type | Value | Description |
---|---|---|
int | 0 | Successful. |
simple_conference
Simple conference bridge. This is a blocking command until the room is closed. The user can leave the conference room by pressing * (star)
command: "simple_conference"
params: {
bool auto_leave_when_alone,
string id
}
{
"auto_leave_when_alone": false,
"id": "(string)"
}
Values are auto-generated and may not be correct. Sub-objects are not shown.
Parameter | Type | Description |
---|---|---|
auto_leave_when_alone | bool | Automatically leave the conference room when you're the last participant. Only applies when someone leaves - it does not apply when you are joining and you are first. |
id | string |
Conference room ID. Obviously, you have to set the same id on the calls you wish to bridge... Format: rt_conference_id (Conference ID) |
start_call_recording
Start call recording. This will create a Media.Recording object.
command: "start_call_recording"
params: {
string announce,
string feeds,
string locale,
bool ner,
bool pii,
bool sentiment,
bool transcription
}
{
"announce": "(string)",
"feeds": "leg_b",
"locale": "(string)",
"ner": false,
"pii": false,
"sentiment": false,
"transcription": false
}
Values are auto-generated and may not be correct. Sub-objects are not shown.
Parameter | Type | Description |
---|---|---|
announce | string |
Media to announce the call is being recorded. Set to 0 to ignore. Format: rt_media (Media ID (int) or Text-to-Speech "TTS|TTS_EN-GB_DANIEL|Text to say") |
feeds | string |
Specify the feeds to be processed. Defaults to both feeds ("both"). Values: "all", "both", "leg_a", "leg_b" |
locale | string |
Specify the language spoken for transcription. Leave empty for auto detection (not recommended). Format: locale (POSIX/IANA locale code. Example: "en_US" or "fr_FR".) |
ner | bool | Enables Named Entity Recognition. Defaults to true. Only works if transcription is enabled. |
pii | bool | Enables Personally Identifiable Informations. Defaults to true. Only works if transcription is enabled. |
sentiment | bool | Enables sentiment analysis. Defaults to true. Only works if transcription is enabled. |
transcription | bool | Enables transcription. If not set, the account default value will be taken. |
Type | Value | Description |
---|---|---|
string | recording_hash | The media recording id |
stop_call_recording
Stop call recording
command: "stop_call_recording"
params: {
string announce
}
{
"announce": "(string)"
}
Values are auto-generated and may not be correct. Sub-objects are not shown.
Parameter | Type | Description |
---|---|---|
announce | string |
Media to announce the call is not being recorded anymore. Set to 0 to ignore. Format: rt_media (Media ID (int) or Text-to-Speech "TTS|TTS_EN-GB_DANIEL|Text to say") |
Type | Value | Description |
---|---|---|
string | recording_hash | The media recording id |
wait
Wait for a few seconds.
command: "wait"
params: {
int wait
}
{
"wait": 0
}
Values are auto-generated and may not be correct. Sub-objects are not shown.
Parameter | Type | Description |
---|---|---|
wait | int | (seconds) Time to wait. Min:1, Max: 30. |
Type | Value | Description |
---|---|---|
string | 0 | Successful. |
wait_for_silence
Wait until silence is detected, or timeout is reached.
command: "wait_for_silence"
params: {
int iterations,
int silence_ms,
int timeout
}
{
"iterations": 0,
"silence_ms": 0,
"timeout": 0
}
Values are auto-generated and may not be correct. Sub-objects are not shown.
Parameter | Type | Description |
---|---|---|
iterations | int | Number of times to try. Min:1, Max:10. |
silence_ms | int | (milliseconds) Minimum silence duration. Min:1, Max:5000. |
timeout | int | (seconds) Global timeout if silence is not detected. Min:0 (disabled), Max:300. |
Type | Value | Description |
---|---|---|
string | SILENCE | Silence detected. |
string | TIMEOUT | No silence detected before timeout. |