Voice Prompts

Services for managing the voice prompt files of the account: the prompts played at the beginning of a call, at its end, in the IVR menus and more.

---

get_prompts_list

Return the list of all the voice prompts in the account.

Endpoint: /api/?service=get_prompts_list

Parameters

Parameter	Type	Required	Description
format	string	NO	json / xml.

Response fields

name, create_date, size, length.

Error code

Code	Description
9041	There are no voice prompts in the account

---

download_prompt

Download a voice prompt file.

Endpoint: /api/?service=download_prompt

Parameters

Parameter	Type	Required	Description
prompt_name	string	YES	The prompt name (as returned by get_prompts_list).
format	string	NO	json / xml (relevant to error states only).

Error codes

Code	Description
9011	prompt_name is missing
9013	prompt_name is invalid — it contains no valid characters (English letters, digits, hyphens or underscores)
9012	There is no prompt with that name

Example

curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -o greeting.wav \
     "https://[MASKYOO_URL]/api/?service=download_prompt&prompt_name=greeting_welcome"

note

This service has no only_file parameter, and the response may include status data (JSON/XML) after the file content. If the received file does not play correctly, check whether data was appended at its end.

---

upload_prompt

Upload a new voice prompt. The file is processed automatically and adapted for use in the system.

Endpoint: /api/?service=upload_prompt (requires multipart/form-data)

Parameters

Parameter	Type	Required	Description
prompt_file	file	YES	The audio file to upload.
file_name	string	NO	Used for the duplicate check only (whether a prompt with that name already exists) — it does not determine the final prompt name.
format	string	NO	json / xml.

The final prompt name

The stored prompt name is derived from the name of the uploaded file (prompt_file) — the part before the first dot, normalized to lowercase English letters, digits, hyphens and underscores. The file_name parameter does not affect the final name.

Limits

• Maximum size: 50 MB.
• Common audio formats are supported (WAV, MP3, AAC, FLAC, OGG, M4A, AMR, OPUS and more).
• The prompt name must be unique within the account.

Error codes

Code	Description
9021	No file was provided / the file is empty
9022	A prompt with the same name already exists
9023	The file type is not supported
9024	The file is larger than allowed
9025	Processing the file failed

Example

curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -X POST "https://[MASKYOO_URL]/api/?service=upload_prompt" \
     -F "prompt_file=@/path/to/greeting.mp3" \
     -F "file_name=welcome_greeting" \
     -F "format=json"

Response

{
  "service": "upload_prompt",
  "status": {
    "code": 200,
    "description": "prompt `greeting ` been added to the system",
    "prompt_name": "greeting"
  }
}

Note: prompt_name in the response is derived from the uploaded file name (greeting.mp3 → greeting), and not from the file_name parameter.

---

delete_prompt

Delete a voice prompt from the account.

Endpoint: /api/?service=delete_prompt

Parameters

Parameter	Type	Required	Description
prompt_name	string	YES	The name of the prompt to delete.
format	string	NO	json / xml.

Error codes

Code	Description
9031	prompt_name is missing
9034	prompt_name is invalid — it contains no valid characters (English letters, digits, hyphens or underscores)
9032	The prompt does not exist
9033	The deletion failed

---

recording_studio

Telephone recording studio: the system calls the number you specify, guides the person recording and records a prompt that is saved automatically in the account.

Endpoint: /api/?service=recording_studio

Parameters

Parameter	Type	Required	Description
destination	string	YES	The phone number the recording call goes out to.
format	string	NO	json / xml.

Error code

Code	Description
9026	destination is empty / invalid

Example

curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     -X POST "https://[MASKYOO_URL]/api/?service=recording_studio" \
     -d "destination=972544224422" \
     -d "format=json"

System impact

Managing voice prompts through the API is directly connected to the IVR:

• Immediate availability — a file uploaded through upload_prompt is available immediately in IVR Studio and in the Maskyoo number settings under greeting_in / greeting_out / ringback_tone
• Deleting an active file — deleting a prompt that is used by an active IVR component causes a call failure at runtime
• Name normalization — the final prompt name is derived from the uploaded file name and normalized to lowercase English letters, digits, hyphens and underscores; the name must be unique within the account
• Size and format — up to 50 MB; supported formats: WAV, MP3, AAC, FLAC, OGG, M4A, AMR, OPUS; the system converts to an internal format automatically
• Recording studio — recording_studio dials the supplied number and creates a live call; the recording is saved automatically in the account as a prompt

See also

• Managing sound files
• IVR Studio
• Maskyoo Management