דלג לתוכן הראשי

upload_prompt

POST multipart   /api/?service=upload_prompt

Uploads an audio recording and converts it to the telephone audio format used by the system. The prompt's name is derived from the file name and returned in the response; pass that name in playfileN when placing calls and in delete_prompt to remove it.

Parameters​

FieldDescriptionRules
prompt_file (required)The audio file, sent as a multipart form-data file field.Up to 50 MB. Any common audio or video format: WAV, MP3, M4A, AAC, OGG, Opus, FLAC, WMA, AMR, GSM, MP4 and others. Mono 8 kHz or 16 kHz WAV gives the best telephone quality.
How the prompt name is derived
  • The file name is converted to lower case and cut at the first dot: Welcome Msg.v2.mp3 becomes welcome msg.
  • Characters other than a–z, 0–9, _ and - are removed, giving welcomemsg. A file name in Hebrew only receives a generated name such as file_66e4a1b2c3d4e.
  • Name files with Latin letters, digits, underscores and hyphens, for example appt_reminder_v2.wav, so the returned name is the one you expect.
  • Uploading a file whose derived name already exists replaces the existing prompt.

Request examples​

cURL​

curl -X POST "https://dialer2.maskyoo.com/{system_name}/api/?service=upload_prompt" \
  -H "Authorization: Bearer 3f9c2a1e7b4d…" \
  -F "prompt_file=@/path/to/welcome_msg.mp3"

PHP​

<?php
$ch = curl_init("https://dialer2.maskyoo.com/{system_name}/api/?service=upload_prompt");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ["Authorization: Bearer 3f9c2a1e7b4d…"],
    CURLOPT_POSTFIELDS     => ["prompt_file" => new CURLFile("/path/to/welcome_msg.mp3", "audio/mpeg", "welcome_msg.mp3")],
    CURLOPT_RETURNTRANSFER => true,
]);
$body = curl_exec($ch);
curl_close($ch);

if ($body === "" || $body === false) {
    throw new RuntimeException("upload_prompt: conversion failed (empty response)");
}
$xml = simplexml_load_string($body);
if (strcasecmp((string)$xml->status, "OK") !== 0) {
    throw new RuntimeException("upload_prompt failed: " . $xml->description);
}
// "welcome_msg been added to the system" -> the prompt name is the first word
$promptName = strtok((string)$xml->description, " ");
echo "Use playfile1=$promptName\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…");

using var content = new MultipartFormDataContent();
var file = new ByteArrayContent(await File.ReadAllBytesAsync(@"C:\prompts\welcome_msg.mp3"));
file.Headers.ContentType = new MediaTypeHeaderValue("audio/mpeg");
content.Add(file, "prompt_file", "welcome_msg.mp3");     // the field name must be prompt_file

var response = await http.PostAsync(
    "https://dialer2.maskyoo.com/{system_name}/api/?service=upload_prompt", content);
var body = await response.Content.ReadAsStringAsync();

if (string.IsNullOrWhiteSpace(body))
    throw new Exception("upload_prompt: conversion failed (empty response)");

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

var promptName = root.Element("description")!.Value.Split(' ')[0];
Console.WriteLine($"Use playfile1={promptName}");

Responses​

Response — HTTP 200, success (XML)

<?xml version="1.0"?>
<root>
  <service>upload_prompt</service>
  <status>OK</status>
  <description>welcome_msg been added to the system</description>
</root>

Response — HTTP 200, error (XML)

<?xml version="1.0"?>
<root>
  <service>upload_prompt</service>
  <status>Error</status>
  <description>Error: the prompt file `x.exe` is not a valid audio extension</description>
</root>

Response — HTTP 200, conversion failed (empty body)

(no body)

All responses of this service​

HTTPFormatBodyMeaning
200XML<status>OK</status> <description>welcome_msg been added to the system</description>Prompt stored. The first word of the description is the prompt name.
200XML<description>Error: prompt_file cannot be empty</description>No file field named prompt_file in the request.
200XML<description>Error: the prompt file `x.exe` is not a valid audio extension</description>File extension is not an audio or video format.
200XML<description>Error: the prompt file `big.wav` size must be under 50Mb</description>File larger than 50 MB.
200empty(no body)The audio could not be converted. Re-export the file as WAV or MP3 and retry.

ראו גם​