POST / voice/broadcast/send
Base URL: https://backend.easify.app/api/v2
This endpoint is used to initiate a voice broadcast, with optional IVR menu support.
The broadcast content can be delivered as a text-to-speech message, an audio file URL, or an existing voice file already uploaded to your account. Existing voice files and their IDs can be fetched using the List Voices API.
If you exceed the allowed rate limit, you will receive a 429 Too Many Requests status, along with a message indicating when you can try again.
The authenticated user must have access to the Voice Outreach (voice-outreach) module. Requests made without the proper module permissions will receive a 403 Forbidden response.Authentication
The Easify API token used for authentication is passed in the header as a Bearer token, which can be obtained from the easify app under Settings > API Settings.
Headers
Authorization string required Bearer << YOUR_EASIFY_API_TOKEN_HERE >>
Content-Type application/json
Request Body
| from_number string |
The registered caller ID (phone number) from which the broadcast will be sent *Ensure that you are using a phone number associated with the api token, please use the Phone Numbers API to retrieve the associated phone numbers. |
Required |
| country_code string |
The international calling code (dialing prefix) for the destination number, prefixed with + (e.g., +1 for US, +91 for India) *Not an ISO 3166-1 alpha-2 code such as US |
Required |
| to_number string | The recipient's phone number (Must be valid for the provided country code) | Required |
| message string | Text-to-speech message content (Maximum 5000 characters) | Required without voice_url and voice_id |
| voice_url string | URL of an audio file (.wav or .mp3) | Required without message and voice_id |
| voice_id integer |
The ID of an existing voice file already in the system *Use the List Voices API to retrieve the available voice files and obtain their IDs. |
Required without message and voice_url |
| ivr array | Interactive Voice Response (IVR) menu configuration (Maximum 8 items) | Optional |
| ivr[].name string | Description or name of the IVR option (Maximum 100 characters) | Required with ivr |
| ivr[].dial_code integer | The keypad digit (0-8) the recipient must press (Each value must be distinct) | Required with ivr |
| ivr[].number string | The phone number to forward the call to when the digit is pressed | Required with ivr |
Sample Request and Success Response:
Request:
{
"from_number": "+1555123****",
"country_code": "+1",
"to_number": "+1555987****",
"message": "This is a reminder about your upcoming appointment.",
"ivr": [
{
"name": "Confirm Appointment",
"dial_code": 1,
"number": "+1555000****"
},
{
"name": "Reschedule",
"dial_code": 2,
"number": "+1555000****"
}
]
}
Success Response:
{
"status": true,
"message": "Voice Broadcast processed successfully",
"data": {
"voice_broadcast_id": "60d5ec498b...f12"
}
}
Api Response Status
| Case | Status Code | Response |
|---|---|---|
| If the user provides an invalid Easify API token or does not pass the Easify API token in the header. | 401 |
{
"status":false,
"message":"Unauthenticated",
"errors":[]
}
|
| If the user does not provide from_number | 422 |
{
"message": "The from number field is required.",
"errors": {
"from_number": ["The from number field is required."]
}
}
|
| If the user provides an invalid or inactive from_number | 422 |
{
"message": "Selected from number is invalid or not active.",
"errors": {
"from_number": ["Selected from number is invalid or not active."]
}
}
|
| If the user does not provide to_number | 422 |
{
"message": "The to number field is required.",
"errors": {
"to_number": ["The to number field is required."]
}
}
|
| If the user provides an ISO 3166-1 alpha-2 code (e.g., US) instead of the international calling code in country_code | 422 |
{
"message": "Invalid country code.",
"errors": {
"country_code": ["Invalid country code."]
}
}
|
| If the user does not provide any of message, voice_url or voice_id | 422 |
{
"message": "One of message, voice_url, or voice_id is required. (and 2 more errors)",
"errors": {
"message": ["One of message, voice_url, or voice_id is required."],
"voice_url": ["One of message, voice_url, or voice_id is required."],
"voice_id": ["One of message, voice_url, or voice_id is required."]
}
}
|
| If the user exceeds the allowed rate limit for requests | 429 |
{
"status":false,
"message":"Too many requests. Try again in 59 seconds",
"errors":[]
}
|
| If the user's subscription has ended | 402 |
{
"status":false,"message":"You need to recharge your account to proceed","errors":[]
}
|
| If the user does not have enough credits to send the broadcast | 400 |
{
"status": false,
"message": "Sorry you do not have enough credits to send this broadcast.",
"errors": []
}
|
| When the user account is inactive | 403 |
{
"status": false,
"message": "Your account is currently inactive.",
"errors": []
}
|
Response Explanation
- success: Indicates whether the request was processed successfully.
- message: A human-readable description of the result.
- voice_broadcast_id: The unique identifier of the voice broadcast created by the request.
PHP-cURL
php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'https://backend.easify.app/api/v2/voice/broadcast/send',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => json_encode([
'from_number' => '+1555123****',
'country_code' => '+1',
'to_number' => '+1555987****',
'message' => 'This is a reminder about your upcoming appointment.',
'ivr' => [
[
'name' => 'Confirm Appointment',
'dial_code' => 1,
'number' => '+1555000****'
]
]
]),
CURLOPT_HTTPHEADER => [
'Accept: application/json',
'Authorization: Bearer 1955|43da5bb5-5c2b-4059-a4de-d44bf5****',
'Content-Type: application/json'
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;