Methods

Objects

Real-Time: Reference

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":"+16469820800",
   "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":{}
}

Commands

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

Description

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

Signature

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
}

Parameters

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

Parameters

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")

Result

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

Description

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.

Signature

command: "dialout"

params: {
string cdr_field,
string cli,
string ringtone,
array targets,
string whisper
}

Parameters

{
  "cdr_field": "(string)",
  "cli": "(string)",
  "ringtone": "RING",
  "targets": [],
  "whisper": "(string)"
}
Values are auto-generated and may not be correct. Sub-objects are not shown.

Parameters

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")

Result

Type Value Description
string NOANSWER No one answered the call.

hangup

Description

Hangup the current call.

Signature

command: "hangup"

params: {

}

Parameters

{

}
Values are auto-generated and may not be correct. Sub-objects are not shown.

Parameters

No parameters..

Result

No result.

hangup_callid

Description

Hangup a specific callid

Signature

command: "hangup_callid"

params: {
int callid
}

Parameters

{
  "callid": 0
}
Values are auto-generated and may not be correct. Sub-objects are not shown.

Parameters

Parameter Type Description
callid int The callid you wish to hang up.
Format: callid (64-bit unsigned integer)

Result

No result.

play

Description

Plays a Media.Library or say something with the Text-to-Speech

Signature

command: "play"

params: {
string media_id
}

Parameters

{
  "media_id": "(string)"
}
Values are auto-generated and may not be correct. Sub-objects are not shown.

Parameters

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")

Result

Type Value Description
string 0 Play successful.
string 1 An error occured.

See Also

  • Object: Media.Library

play_record

Description

Plays a recording recorded with the "record" command.

Signature

command: "play_record"

params: {
string media_file
}

Parameters

{
  "media_file": "(string)"
}
Values are auto-generated and may not be correct. Sub-objects are not shown.

Parameters

Parameter Type Description
media_file string Temporary file name

Result

Type Value Description
string 0 Play successful.
string 1 An error occured.

See Also

play_talk_detect

Description

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.

Signature

command: "play_talk_detect"

params: {
int analysistime_ms,
int max_ms,
string media_id,
int min_ms,
int silence_ms
}

Parameters

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

Parameters

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

Result

Type Value Description
string 0 talk not detected.
string TALK talk detected!

play_wav_data

Description

Plays WAV data (sent directly)

Signature

command: "play_wav_data"

params: {
string audio_data
}

Parameters

{
  "audio_data": "(string)"
}
Values are auto-generated and may not be correct. Sub-objects are not shown.

Parameters

Parameter Type Description
audio_data string BASE64 encoded WAV file. MUST BE 8000Hz (8Khz), 16bit, mono.

Result

Type Value Description
string 0 Play successful.
string 1 An error occured.

read

Description

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.

Signature

command: "read"

params: {
int attempts,
int max_digits,
string media_id,
int timeout_ms
}

Parameters

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

Parameters

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

Result

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

Description

Record the user. The recording can be stopped by pressing the hash key '#', when silence is detected, or when maximum recording duration is reached.

Signature

command: "record"

params: {
int max_duration,
int silence
}

Parameters

{
  "max_duration": 0,
  "silence": 0
}
Values are auto-generated and may not be correct. Sub-objects are not shown.

Parameters

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.

Result

Type Value Description
string media_file Temporary filename you can use with "play_record"

See Also

send_dtmf

Description

Send DTMF digits.

Signature

command: "send_dtmf"

params: {
string digits,
int duration_ms,
int timeout_ms
}

Parameters

{
  "digits": "(string)",
  "duration_ms": 0,
  "timeout_ms": 0
}
Values are auto-generated and may not be correct. Sub-objects are not shown.

Parameters

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.

Result

Type Value Description
int 0 Successful.

simple_conference

Description

Simple conference bridge. This is a blocking command until the room is closed. The user can leave the conference room by pressing * (star)

Signature

command: "simple_conference"

params: {
bool auto_leave_when_alone,
string id
}

Parameters

{
  "auto_leave_when_alone": false,
  "id": "(string)"
}
Values are auto-generated and may not be correct. Sub-objects are not shown.

Parameters

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)

Result

No result.

start_call_recording

Description

Start call recording. This will create a Media.Recording object.

Signature

command: "start_call_recording"

params: {
string announce,
string feeds,
string locale,
bool ner,
bool pii,
bool sentiment,
bool transcription
}

Parameters

{
  "announce": "(string)",
  "feeds": "both",
  "locale": "(string)",
  "ner": false,
  "pii": false,
  "sentiment": false,
  "transcription": false
}
Values are auto-generated and may not be correct. Sub-objects are not shown.

Parameters

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.

Result

Type Value Description
string recording_hash The media recording id

See Also

  • Object: Media.Recording

stop_call_recording

Description

Stop call recording

Signature

command: "stop_call_recording"

params: {
string announce
}

Parameters

{
  "announce": "(string)"
}
Values are auto-generated and may not be correct. Sub-objects are not shown.

Parameters

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")

Result

Type Value Description
string recording_hash The media recording id

See Also

  • Object: Media.Recording

wait

Description

Wait for a few seconds.

Signature

command: "wait"

params: {
int wait
}

Parameters

{
  "wait": 0
}
Values are auto-generated and may not be correct. Sub-objects are not shown.

Parameters

Parameter Type Description
wait int (seconds) Time to wait. Min:1, Max: 30.

Result

Type Value Description
string 0 Successful.

wait_for_silence

Description

Wait until silence is detected, or timeout is reached.

Signature

command: "wait_for_silence"

params: {
int iterations,
int silence_ms,
int timeout
}

Parameters

{
  "iterations": 0,
  "silence_ms": 0,
  "timeout": 0
}
Values are auto-generated and may not be correct. Sub-objects are not shown.

Parameters

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.

Result

Type Value Description
string SILENCE Silence detected.
string TIMEOUT No silence detected before timeout.