Make calls API

This API allows you to make/schedule phone calls programmatically. It is a very powerful tool that allows you to define the phone call flow depending if it is answered by a human been or an answering machine (phone call bridge API is an alias of this API).

URL

https://voip-communications.net/api-v2/index.php/pcall/call

Method

POST

Authentication

Basic

Parameters

• from (optional): phone number to be displayed to called number as Caller ID, if not provided, the Caller ID of the Endpoint associated with your account will be used.
• to (required): phone number to call to; Formated as COUNTY CODE + AREA CODE + NUMBER.
• call_date (optional): schedule date to make the phone call (YYYY-MM-DD HH:MM)(keep in mind, the system check for scheduled phone calls every 5 minutes); If not provided, the system will make the call immediately. So, if you schedule a call [click here] to see the API methods to list and delete scheduled calls or [Click here] to see all requested phone calls.
• record (optional): record phone call as soon it is answered. Possible values YES / NO. If not provided the value will be taked from the Endpoint associated with your account.
• callback_url (optional): URL to be called by POST method as soon the phone call process finish. You will get the answer status (Person/Machine) and the seconds billed from the call.
• Answer Options if the phone call is answered by a Human been. 
  • answer_play (optional): URL to MP3/WAV (WAVE PCM, 8000 Hz 16 bit or 11025 Hz 16 bit PCM) file to be played when the phone call is answered.
  • answer_speak (optional): Text to speech when the call is answered (This process uses a very basic TTS engine – no charge).
  • answer_speak_lang (required if answer_speak): Language to be used by the TTS engine to process the content of “answer_speak“. See table below for possible values.
  • answer_tts (optional): Text to speech when the call is answered; This process uses our TTS API (extra charges apply) with professional voices.
  • answer_tts_voice (required if answer_tts): Voice to be used by our TTS API to process the content of “answer_tts“. See table below for possible values.
  • answer_ivr (optional): Code of the IVR/Phone menu to be pressented to the person when answers the phone.
  • answer_dial_to (optional): Phone number to be dialed after the phone call is answered.
  • answer_dial_from (optional): phone number to be displayed to “answer_dial_to” as caller ID; If not provided the content of “to” will be used.
  • answer_dial_tone_url (optional): URL to MP3/WAV (WAVE PCM, 8000 Hz 16 bit or 11025 Hz 16 bit PCM) file to be played to “to” instead of the default “ring tone” (on-hold music until “answer_dial_to” answers)
• Answer Options if the phone call is answered by a “Voicemail”
  • answermachine_play (optional): URL to MP3/WAV (WAVE PCM, 8000 Hz 16 bit or 11025 Hz 16 bit PCM) file to be played If phone call goes to “Voice Mail”
  • answermachine_speak (optional): Text to speech when the phone call goes to “Voice Mail” (This process uses a very basic TTS engine – no charge).
  • answermachine_speak_lang (required if answermachine_speak): Language to be used by the TTS engine to process the content of “answermachine_speak“.
  • answermachine_tts (optional): Text to speech when the call goes to “Voice Mail”; This process uses our TTS API (extra charges apply) with professional voices.
  • answermachine_tts_voice (required if answermachine_tts): Voice to be used by our TTS API to process the content of “answermachine_tts“.
  • answermachine_sms (optional): Text to be sent by SMS to “to“
  • answermachine_sms_from (optional): If provided, this number must belong to you and be SMS capable.

At least one of the “answer_” options must be provided in order to process the phone call.

The “answer_” options are processed in the next order play, speak, TTS and dial.

answer_dial is the last option to be processed, it means that if you expect to call a second phone number if the call is answered, the second phone call will not be started until previous options are processed.

Our system is able to detect if the phone call goes to “Voice Mail”; in this case, all “answermachine_” options will be processed in the next order play, speak, TTS, SMS; If no “answermachine_” options are specified the phone call will end.

• Speak Lang
• TTS Voice

Language	Value
English – British	en-GB
English – USA	en-US
French	fr-FR
German	de-DE
Italian	it-IT
Portuguese	pt-BR
Russian	ru-RU
Spanish	es-ES
Spanish – USA	es-US

Code	Gender	Language
en-US_AllisonVoice	female	en-US
de-DE_BirgitVoice	female	de-DE
de-DE_DieterVoice	male	de-DE
ja-JP_EmiVoice	female	ja-JP
es-ES_EnriqueVoice	male	es-ES
it-IT_FrancescaVoice	female	it-IT
pt-BR_IsabelaVoice	female	pt-BR
en-GB_KateVoice	female	en-GB
es-ES_LauraVoice	female	es-ES
en-US_LisaVoice	female	en-US
en-US_MichaelVoice	male	en-US
fr-FR_ReneeVoice	female	fr-FR
es-LA_SofiaVoice	female	es-LA
es-US_SofiaVoice	female	es-US

HTTP Response Codes:

200: Success
400: Invalid request
401: Invalid API credentials

Response data:

You will get a JSON like this.

{
    "data": {
             "from": "12812345678",
             "to": "17134567890",
             "record": "YES",
             "answer_play" : "https://example.com/file.mp3",
             "answer_tts": "This text will be read it when file.mp3 ends",
             "answer_tts_voice": "en-US_AllisonVoice",
             "answer_dial_to": "18323456789",
             "answermachine_speak": "It is a message for you voice mail",
             "answermachine_speak_lang": "en-US",
             "code": 200,
             "code_desc": "",
             "callid": "4812659e8ee99a8167613597768"
    }
}

Please note “callid” in the response; It is a unique code for the process, and it is required to cancel the request (just if it is a scheduled phone call bridge). [click here] to see API methods to list/delete scheduled calls.

curl -u YOUR_API_KEY:YOUR_API_PASSWORD
     --data"to=12812345670&answer_play=http://example.com/file.wav"
     https://voip-communications.net/api-v2/index.php/pcall/call

$service_url = "https://voip-communications.net/api-v2/index.php/pcall/call";
$curl = curl_init($service_url);
curl_setopt($curl, CURLOPT_USERPWD, "YOUR_API_KEY:YOUR_API_PASSWORD");
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$post_fields = array("from" => "12812345678",
                     "to" => "17134567890",
                     "record" => "YES",
                     "answer_play" => "https://example.com/file.mp3",
                     "answer_tts" => "This text will be read it when file.mp3 ends",
                     "answer_tts_voice" => "en-US_AllisonVoice",
                     "answer_dial_to" => "18323456789",
                     "answermachine_speak" => "It is a message for your voicemail",
                     "answermachine_speak_lang" => "en-US",
                     "answermachine_sms" => "SMS message");
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($post_fields));
$curl_response = curl_exec($curl);
if ($curl_response !== false) {
    $http_code = curl_getinfo($curl,CURLINFO_HTTP_CODE);
    if ($http_code == "200") {
        $result = json_decode($curl_response,true);
        print_r($result);
    }
}
curl_close($curl);