How to Send a Voice Message

Sending a Voice Message via API

Upload an audio file and queue a voice campaign with the LigueLead API.

🤖 Looking for AI-driven calls? This guide covers pre-recorded audio only — POST /v1/voice requires a voice_upload_id and does not accept voice agents. To place AI-driven calls (an AI agent that holds a live conversation), use the dedicated endpoint POST /v1/voice-agent/call. See How to Send Voice Calls with AI.

Prerequisites

1. Get your api-token and app-id in your LigueLead account, or an app-id created through the API.
2. Prepare an audio file in WAV (recommended) or MP3 format. WAV is preferred because MP3's lossy compression can reduce audio quality — see Supported Audio Formats.
3. Collect the recipient phone numbers in Brazilian format (for example, 11999999999). Other formats are also accepted — see Phone number format.

Step 1: Upload the audio file

Endpoint: POST /v1/voice/uploads

Run the request to upload the audio file you want to send.

curl -X POST "https://api.liguelead.com.br/v1/voice/uploads" \
  -H "api-token: YOUR_API_TOKEN" \
  -H "app-id: YOUR_APP_ID" \
  -F "title=Welcome Message" \
  -F "file=@/path/to/your/audio.mp3"

💡 Tip: Upload WAV whenever possible. MP3 is accepted, but its lossy compression may degrade audio quality. The uploaded file's contents are checked against its extension: a file whose bytes clearly belong to the other format (for example, a WAV renamed to .mp3) is rejected with 415.

Expected response

{
  "message": "Voice upload successful.",
  "data": {
    "id": 123456,
    "title": "Welcome Message",
    "url": "https://ll-api-files.s3.amazonaws.com/1234/YOUR_APP_ID/audios/9f2c4e1a7b3d5f60.wav"
  }
}

Save the returned id. You will use it as voice_upload_id in the next request. The id belongs to the app that uploaded it: only requests with the same app-id can send it, list it or fetch it.

The url points to the stored file, so you can listen to what will be played. Anyone with the link can download the file, so do not publish it.

Step 2: Send the voice message

Endpoint: POST /v1/voice

Run the request to queue the voice message for delivery.

curl -X POST "https://api.liguelead.com.br/v1/voice" \
  -H "api-token: YOUR_API_TOKEN" \
  -H "app-id: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Welcome Campaign",
    "voice_upload_id": 123456,
    "phones": ["11999999999", "11888888888"]
  }'

Expected response

{
  "message": "Voice accepted successfully",
  "data": {
    "campaign_id": "3b4f7c5e-7e2d-4157-b542-5eb2155455c5",
    "accepted_at": "2025-12-29T18:34:38.961Z"
  }
}

A 200 OK response means the request was received and queued for processing.

Request parameters

Upload audio (POST /v1/voice/uploads)

Send voice message (POST /v1/voice)

Optional: Configuring retries

Use the retry fields to control how the voice service redials a number after a failed call. All three fields are optional.

When you omit retry_attempts and retry_interval_min, the voice service automatically applies the default values of 3 attempts with a 15-minute interval between them. These defaults are managed by the voice service and may vary by account.

When you omit retry_end_time, no custom cutoff time is applied.

Example payload with retries

curl -X POST "https://api.liguelead.com.br/v1/voice" \
  -H "api-token: YOUR_API_TOKEN" \
  -H "app-id: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Payment Reminder",
    "voice_upload_id": 123456,
    "phones": ["11999999999", "11888888888"],
    "retry_attempts": 3,
    "retry_interval_min": 15,
    "retry_end_time": "21:00"
  }'

Retry validation errors

The API returns 422 Unprocessable Entity when retry_end_time:

• does not match the HH:MM format
• is outside the allowed range of 08:00 to 21:45
• is less than 10 minutes in the future in the America/Sao_Paulo timezone

Optional: Managing uploaded audio files

Use these endpoints to review the audio files uploaded by this app. Audio files of other apps of the same account are not shown.

List uploaded audio files

Lists the audio files uploaded by this app, newest first.

curl -X GET "https://api.liguelead.com.br/v1/voice/uploads" \
  -H "api-token: YOUR_API_TOKEN" \
  -H "app-id: YOUR_APP_ID"

{
  "message": "Voice list.",
  "data": [
    {
      "id": 123456,
      "title": "Welcome Message",
      "url": "https://ll-api-files.s3.amazonaws.com/1234/YOUR_APP_ID/audios/9f2c4e1a7b3d5f60.wav"
    }
  ]
}

When the app has no audio files, data is an empty array and the message is No voice found..

Get one uploaded audio file by ID

curl -X GET "https://api.liguelead.com.br/v1/voice/uploads/123456" \
  -H "api-token: YOUR_API_TOKEN" \
  -H "app-id: YOUR_APP_ID"

{
  "message": "Voice found successfully.",
  "data": {
    "id": 123456,
    "title": "Welcome Message",
    "url": "https://ll-api-files.s3.amazonaws.com/1234/YOUR_APP_ID/audios/9f2c4e1a7b3d5f60.wav"
  }
}

An id uploaded by another app answers 404 with { "error": "Audio not found" }, exactly like an id that does not exist.

Phone number format

The API accepts Brazilian phone numbers in any of these formats:

• National: "11999999999"
• International: "+5511999999999"
• With country code, no +: "5511999999999"

For numbers outside Brazil, send is_international: true and write each number with its country code.

Dialing window (21:45 – 08:00 | America/Sao_Paulo)

To comply with calling time policies, no calls are placed between 21:45 and 08:00 (America/Sao_Paulo).

Requests received during this window are still accepted by the API, but they are not dialed immediately. They remain pending and are processed automatically when dialing resumes at 08:00.

Processing and delivery

• Asynchronous processing: voice messages are queued for delivery.
• Response code: 200 OK indicates successful queuing.
• Delivery time: varies based on the carrier and the number of recipients.
• Status tracking: the status of each call arrives as a campaign.status webhook, sent to the app's webhook URL or to the webhook_url of the send — see How to Receive Webhooks.

Best practices

1. Reuse audio files: upload once and send to multiple campaigns.
2. Monitor delivery: track the campaign.status webhooks to confirm each call.
3. Test first: start with small batches before scaling up.
4. Clear titles: use descriptive names for easy identification.

Troubleshooting