makecall

GET / POST   /api/?service=makecall

Places an outbound call from one of your system's numbers to an Israeli phone number. When the person answers, the system plays up to fifteen prompts in order, optionally waits for keypad digits after each one, plays follow-up prompts depending on the digit pressed, and can transfer the call to a live phone such as your call centre. The request returns as soon as the call is queued; dialing happens in the background and the result is delivered to your call_back_url and recorded in the call records.

Every playfileN value is either the name of an existing prompt file, uploaded with upload_prompt, or plain text, which the system converts to speech with its text-to-speech engine. Plain text must be URL-encoded (UTF-8). You can mix both kinds in one call.

Required parameters

Parameter	Description	Accepted values
destination (required)	Phone number to call. Israeli numbers only.	0523456789, 523456789 or 972523456789. All three dial the same phone.
caller_id (required)	Number shown to the person called. Must be one of the numbers assigned to your system; the error message lists them if you send another.	0554321987 or 972554321987
playfile1 (required)	The first prompt: the name of an existing prompt file, or plain text to read aloud. Plain text must be URL-encoded.	welcome_msg or %D7%A9%D7%9C%D7%95%D7%9D (URL-encoded שלום)

Optional parameters

Parameter	Description	Default
playfile2 … playfile15	Further prompts, played in numeric order. Same rules as playfile1.	none
valid_dtmfN	Keypad digits accepted after prompt N (N = 1…15). 12 accepts 1 or 2. When set, the system waits for a digit before continuing.	none (no input expected)
where_playfileN	Play prompt N only if the answer to an earlier prompt matches, written Q=A. where_playfile3=1=2 plays prompt 3 only when the person pressed 2 after prompt 1.	none (always play)
dial_out_phone	Number to transfer the call to, for example your call centre.	none
where_dial_out_phone	Condition for the transfer, in the same Q=A form.	none
max_simultanic_call	Maximum number of calls transferred to dial_out_phone at the same time.	unlimited
retry	Number of dial attempts when there is no answer. Alias: campaign_redial_retrys.	1
waittime	Seconds to wait between attempts. Alias: campaign_redial_delay. Each attempt rings for 30 seconds.	60
call_back_url	URL your server exposes to receive the call result when the call ends.	none
spread_name	Campaign name shown in reports and call records. Use it to group calls.	API custom dial
private_field1 … private_field3	Your own reference values, for example an order or appointment ID. Returned with the call result and stored in the call record.	none

Prompt names and text

The system first looks for an existing prompt file whose name equals the playfileN value. If one exists it is played; otherwise the value is treated as plain text and converted by the text-to-speech engine. Give uploaded prompts names that cannot be mistaken for sentences, such as appt_reminder_v2. Text must be URL-encoded: every HTTP library does this when you pass parameters as form fields, but if you build the query string by hand, encode it yourself. Prefer uploaded recordings for messages sent at volume: speech is generated on every call and consumes credit.

Request examples

cURL

curl -X POST "https://dialer2.maskyoo.com/{system_name}/api/?service=makecall" \
  -H "Authorization: Bearer 3f9c2a1e7b4d…" \
  --data-urlencode "destination=0523456789" \
  --data-urlencode "caller_id=0554321987" \
  --data-urlencode "playfile1=שלום, לאישור התור הקישו 1, לביטול הקישו 2" \
  --data-urlencode "valid_dtmf1=12" \
  --data-urlencode "playfile2=confirmed_msg" \
  --data-urlencode "where_playfile2=1=1" \
  --data-urlencode "playfile3=cancelled_msg" \
  --data-urlencode "where_playfile3=1=2" \
  --data-urlencode "retry=2" \
  --data-urlencode "waittime=120" \
  --data-urlencode "private_field1=APPT-48213" \
  --data-urlencode "call_back_url=https://example.co.il/vms/result"

PHP

<?php
$ch = curl_init("https://dialer2.maskyoo.com/{system_name}/api/?service=makecall");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ["Authorization: Bearer 3f9c2a1e7b4d…"],
    CURLOPT_POSTFIELDS     => http_build_query([
        "destination"     => "0523456789",
        "caller_id"       => "0554321987",
        "playfile1"       => "שלום, לאישור התור הקישו 1, לביטול הקישו 2",
        "valid_dtmf1"     => "12",
        "playfile2"       => "confirmed_msg",
        "where_playfile2" => "1=1",
        "playfile3"       => "cancelled_msg",
        "where_playfile3" => "1=2",
        "retry"           => 2,
        "waittime"        => 120,
        "private_field1"  => "APPT-48213",
        "call_back_url"   => "https://example.co.il/vms/result",
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$body = curl_exec($ch);
curl_close($ch);

$xml = @simplexml_load_string($body);
if ($xml === false) {
    throw new RuntimeException("makecall rejected: " . trim($body));      // plain-text validation error
}
if (strcasecmp((string)$xml->status, "Ok") !== 0) {
    throw new RuntimeException("makecall failed: " . $xml->description);  // XML Error
}
echo "Call queued\n";

C#

using System.Net.Http;
using System.Net.Http.Headers;
using System.Xml.Linq;

var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "3f9c2a1e7b4d…");

var form = new FormUrlEncodedContent(new Dictionary<string, string>
{
    ["destination"]     = "0523456789",
    ["caller_id"]       = "0554321987",
    ["playfile1"]       = "שלום, לאישור התור הקישו 1, לביטול הקישו 2",
    ["valid_dtmf1"]     = "12",
    ["playfile2"]       = "confirmed_msg",
    ["where_playfile2"] = "1=1",
    ["playfile3"]       = "cancelled_msg",
    ["where_playfile3"] = "1=2",
    ["retry"]           = "2",
    ["waittime"]        = "120",
    ["private_field1"]  = "APPT-48213",
    ["call_back_url"]   = "https://example.co.il/vms/result",
});

var response = await http.PostAsync(
    "https://dialer2.maskyoo.com/{system_name}/api/?service=makecall", form);
var body = await response.Content.ReadAsStringAsync();   // StatusCode is always 200

if (!body.TrimStart().StartsWith("<"))
    throw new Exception($"makecall rejected: {body.Trim()}");           // plain-text validation error

var root = XDocument.Parse(body).Root!;
var status = root.Element("status")?.Value ?? "";
if (!status.Equals("Ok", StringComparison.OrdinalIgnoreCase))
    throw new Exception($"makecall failed: {root.Element("description")?.Value}");

Console.WriteLine("Call queued");

Responses

Response — HTTP 200, success (XML)

<?xml version="1.0"?>
<root>
  <service>makecall</service>
  <status>Ok</status>
</root>

Response — HTTP 200, error (XML)

<?xml version="1.0"?>
<root>
  <service>makecall</service>
  <status>Error</status>
  <description>Error: Internal server error</description>
</root>

Response — HTTP 200, validation error (plain text)

The "caller_id" is not legal for this web service please select one of your numbers 972554321987 or 972554321988

All responses of this service

HTTP	Format	Body	Meaning
200	XML	<status>Ok</status>	Call queued. Dialing starts within seconds.
200	XML	<status>Error</status> <description>Error: Internal server error</description>	The call could not be queued. Retry later; contact support if it persists.
200	text	The "caller_id" is not legal for this web service please select one of your numbers …	caller_id is not one of your numbers. The message lists the allowed ones.
200	text	The "destination" is not legal for this web service please select an Israeli phone number like "972776670000"	destination missing or empty.
200	text	The variable "playfile1" is empty or not set, in order to activate dialing, there must be at least one sound file to play	playfile1 missing. Also the symptom of sending a JSON body.
200	text	authentication messages	See Response messages.

ראו גם

• סקירה כללית של VMS API
• העלאת הקלטה — upload_prompt
• שאילתות CDR — cdrquery
• הודעות תגובה