How to Send Voice with AI

Send AI-driven phone calls to one or more recipients and interpret the resulting webhook data.

Prerequisites

1. Get your api-token and app-id from Integrations > API Token in your LigueLead account.
2. Create a voice agent (optionally with a voice action attached) and copy its id — it is the voice_agent_id of this endpoint.
3. Collect recipient phone numbers in Brazilian format without the country code (for example, 11999999999).
4. A webhook URL to receive call results: the one configured for your app, or a webhook_url passed on the send (see How to Receive Webhooks).

Step 1: Send calls with an AI agent

Endpoint: POST /v1/voice-agent/call

Send a campaign title, the ID of the voice agent that will place the calls, and one to 1,000 recipient phone numbers.

curl -X POST "https://api.liguelead.com.br/v1/voice-agent/call" \
  -H "api-token: YOUR_API_TOKEN" \
  -H "app-id: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Appointment reminders",
    "voice_agent_id": "f9e8d7c6-b5a4-4321-8fed-cba987654321",
    "phones": ["11999999999", "11888888888"]
  }'

Required fields

Expected response

{
  "campaign_id": "corr-abc123-def456-ghi789",
  "phones_count": 2
}

A 202 Accepted response means the calls were accepted and enqueued for processing. Use the campaign_id to correlate the campaign with its status webhooks.

Webhook After Each Call

When a call ends, the platform sends a webhook to the webhook_url of the send or, when the send carried none, to the URL configured for your app, with campaign.type: "voice_ai". It always carries the action the agent executed, plus the transcript and the recording URL when the call produced them.

The payload, the field reference and the list of action_executed values live in the Voice AI tab of How to Receive Webhooks — the same page that documents the webhooks of every other channel.

Optional: Add context for an individual recipient

Pass a phone object with call_context when the agent needs details that apply only to that recipient. call_context is optional and nullable, and always stored as a single line: every whitespace run — line breaks (\n, \r\n, \r) and tabs included — is collapsed into a single space and both ends are trimmed. The 1–1500 character limit applies to that normalized value, so redundant whitespace never counts against it — an empty string, a value made only of whitespace, or one still longer than 1500 characters after normalization is rejected with 422. Accents and punctuation travel exactly as sent, with one exception: a single quote inside the text (Maria D'Ávila) is replaced by the typographic apostrophe ’ (U+2019). It reads the same to the voice agent, and it is what keeps the value from breaking the dial string used to place the call, where the context travels quoted. Plain strings and objects can be freely mixed in the same phones array (a plain string is equivalent to omitting call_context).

curl -X POST "https://api.liguelead.com.br/v1/voice-agent/call" \
  -H "api-token: YOUR_API_TOKEN" \
  -H "app-id: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Appointment reminders",
    "voice_agent_id": "f9e8d7c6-b5a4-4321-8fed-cba987654321",
    "phones": [
      {
        "phone": "11999999999",
        "call_context": "Name: Maria; appointment: 12 August at 14:30."
      }
    ]
  }'

Optional: Configure retries

Provide retry_attempts to enable automatic re-dialing of unanswered calls. The remaining retry fields apply only when you provide retry_attempts.

Optional: Receive the results at another URL

Provide webhook_url to have the results of these calls delivered somewhere other than the app's webhook URL.

Limits

Troubleshooting

The exact messages the API returns:

End-to-End Example

Create a scheduling action, attach it to an agent, and use that agent to dispatch calls. Each step returns the ID required by the next step.

1. Create the scheduling Action

A voice action gives the agent the ability to execute an operation during a call. Use the returned action ID as action_id in step 2.

curl -X POST "https://api.liguelead.com.br/v1/voice-action" \
  -H "api-token: YOUR_API_TOKEN" \
  -H "app-id: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Schedule demonstration",
    "type": "SCHEDULE_EVENT",
    "provider": "microsoft",
    "credentials": {
      "tenant": "YOUR_TENANT_ID",
      "client_id": "YOUR_CLIENT_ID",
      "client_secret": "YOUR_CLIENT_SECRET"
    },
    "config": {
      "calendar_id": "primary",
      "timezone": "America/Sao_Paulo",
      "destination": "[email protected]"
    }
  }'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Sending an SMS instead

To have the agent text the recipient during the call, create a SEND_SMS action. The text is fixed when you create the action: up to 1600 characters, checked against the same blocked words as POST /v1/sms. It goes to the number being called and is charged to your app like any SMS.

curl -X POST "https://api.liguelead.com.br/v1/voice-action" \
  -H "api-token: YOUR_API_TOKEN" \
  -H "app-id: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Send the proposal link",
    "type": "SEND_SMS",
    "provider": "internal",
    "message": "Hi! Here is the link to your proposal: https://example.com/p/123"
  }'

To change the text later, send { "message": "..." } to PUT /v1/voice-action/{id}. When the agent sends the SMS, the call webhook carries action_executed: "send_sms", and the SMS itself reports its delivery in its own webhook, with campaign.type: "sms" and campaign.source: "voice_ai".

If you follow this path, step 2 changes too: use this action's id as action_id, and replace the scheduling instructions in the agent's prompt with ones about the SMS. For example: "You are a sales assistant. Explain the product briefly and, when the recipient is interested, offer to send the proposal link by SMS. Send it only if they agree."

2. Create the Voice Agent with the Action

Create a sales agent that schedules a demonstration. Choose the engine here, as described in the Choosing the engine note; use the action ID from step 1 as action_id.

curl -X POST "https://api.liguelead.com.br/v1/voice-agent" \
  -H "api-token: YOUR_API_TOKEN" \
  -H "app-id: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Demonstration Scheduling Agent",
    "prompt": "You are a sales assistant. Explain the product briefly, qualify interest, and schedule a demonstration when the recipient agrees. Use the scheduling action to register the appointment.",
    "greetings": "Hello! I am calling to help you schedule a product demonstration. Do you have a minute?",
    "engine": {
      "version": "lumen-1",
      "voice_id": "RGymW84CSmfVugnA5tvA"
    },
    "action_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

{
  "id": "f9e8d7c6-b5a4-4321-8fed-cba987654321"
}

3. Dispatch the calls

Use the agent ID from step 2 to send the calls. Any item in phones can be a { phone, call_context } object to provide recipient-specific context; see Optional: Add context for an individual recipient.

curl -X POST "https://api.liguelead.com.br/v1/voice-agent/call" \
  -H "api-token: YOUR_API_TOKEN" \
  -H "app-id: YOUR_APP_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Demonstration scheduling",
    "voice_agent_id": "f9e8d7c6-b5a4-4321-8fed-cba987654321",
    "retry_attempts": 2,
    "phones": [
      "11999999999",
      {
        "phone": "11888888888",
        "call_context": "Name: Maria; interested in a demonstration next week."
      }
    ]
  }'

{
  "campaign_id": "corr-abc123-def456-ghi789",
  "phones_count": 2
}