How to Manage Voice Actions

📋 Prerequisites

Valid api-token and app-id from your LigueLead account.
For SCHEDULE_EVENT and SEND_EMAIL actions: valid OAuth credentials for the chosen provider (Microsoft or Google).

🌐 Base URL

https://api.liguelead.com.br/v1

🔑 Authentication

All requests require both authentication headers:

api-token: your-api-token
app-id: your-app-id

Action Types

Type	Provider(s)	Description
`SCHEDULE_EVENT`	`microsoft`, `google`	Creates a calendar event (Outlook/Teams or Google Calendar).
`SEND_EMAIL`	`microsoft`, `google`	Sends an e-mail (Microsoft Graph or Gmail).
`SEND_SMS`	`internal`	Sends a fixed SMS text to the number being called, through the LigueLead platform.
`TRANSFER_CALL`	`internal`	Transfers the live call to another phone number.
`HTTP_WEBHOOK`	`internal`	POSTs a webhook to your HTTPS `endpoint` at the end of the call.

Credentials by provider

Provider	Required credentials
`microsoft`	`tenant`, `client_id`, `client_secret`
`google`	`client_id`, `client_secret`, `refresh_token`
`internal`	(none)

Config by type

Type	`config` fields
`SCHEDULE_EVENT`	`destination` (e-mail, required), `calendar_id` (optional), `timezone` (optional)
`SEND_EMAIL`	`from_address` (e-mail, required), `destination` (e-mail, required)
`SEND_SMS`	(no config — uses the top-level `message` field)
`TRANSFER_CALL`	(no config — uses the top-level `phone` field)
`HTTP_WEBHOOK`	(no config — uses the top-level `endpoint` field, required, and `authorization_token`, optional)

config is validated strictly — unknown keys inside it are rejected. The destination/from_address fields must be valid e-mail addresses. Top-level fields that do not belong to the action's type are ignored.

Create a Voice Action

POST /v1/voice-action → 201 Created

Schedule Event (Microsoft)

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

Schedule Event (Google)

curl -X POST https://api.liguelead.com.br/v1/voice-action \
  -H "Content-Type: application/json" \
  -H "api-token: YOUR_TOKEN" \
  -H "app-id: YOUR_APP_ID" \
  -d '{
    "name": "Schedule Meeting (Google)",
    "type": "SCHEDULE_EVENT",
    "provider": "google",
    "credentials": {
      "client_id": "<google_client_id>",
      "client_secret": "<google_client_secret>",
      "refresh_token": "<refresh_token>"
    },
    "config": {
      "calendar_id": "primary",
      "timezone": "America/Sao_Paulo",
      "destination": "[email protected]"
    }
  }'

Send E-mail (Microsoft)

curl -X POST https://api.liguelead.com.br/v1/voice-action \
  -H "Content-Type: application/json" \
  -H "api-token: YOUR_TOKEN" \
  -H "app-id: YOUR_APP_ID" \
  -d '{
    "name": "Send Confirmation E-mail",
    "type": "SEND_EMAIL",
    "provider": "microsoft",
    "credentials": {
      "tenant": "<tenant_id>",
      "client_id": "<client_id>",
      "client_secret": "<client_secret>"
    },
    "config": {
      "from_address": "[email protected]",
      "destination": "[email protected]"
    }
  }'

Send SMS (Internal)

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

message is required: up to 1600 characters, checked against the same blocked words as POST /v1/sms (a message carrying one is refused with 422). It is sent to the number being called and charged to your app like any SMS.

Transfer Call (Internal)

curl -X POST https://api.liguelead.com.br/v1/voice-action \
  -H "Content-Type: application/json" \
  -H "api-token: YOUR_TOKEN" \
  -H "app-id: YOUR_APP_ID" \
  -d '{
    "name": "Transfer to Agent",
    "type": "TRANSFER_CALL",
    "provider": "internal",
    "phone": "+5511999999999"
  }'

phone accepts only the characters 0-9 + ( ) - and must contain between 10 and 16 digits.

HTTP Webhook (Internal)

curl -X POST https://api.liguelead.com.br/v1/voice-action \
  -H "Content-Type: application/json" \
  -H "api-token: YOUR_TOKEN" \
  -H "app-id: YOUR_APP_ID" \
  -d '{
    "name": "Notify CRM",
    "type": "HTTP_WEBHOOK",
    "provider": "internal",
    "endpoint": "https://crm.example.com/hooks/voice",
    "authorization_token": "<your_token>"
  }'

endpoint is required and must be an https:// URL of up to 2048 characters. authorization_token is optional (up to 2048 characters); when present, it is sent in the webhook request to your endpoint.

Response (201 Created)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Schedule Meeting",
  "type": "SCHEDULE_EVENT",
  "provider": "microsoft",
  "credentials": {
    "tenant": "<tenant_id>",
    "client_id": "<client_id>",
    "client_secret": "<client_secret>"
  },
  "config": {
    "calendar_id": "primary",
    "timezone": "America/Sao_Paulo",
    "destination": "[email protected]"
  }
}

Save the returned id. You will use it as action_id when creating or updating a Voice Agent.

List All Voice Actions

GET /v1/voice-action → 200 OK

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

Returns an array of the stored actions, in the same shape as the create response. A client with no actions gets an empty array.

🔒 Treat these responses as secrets. Today the create, list, get and update responses carry the action's stored credentials (including client_secret and refresh_token) and authorization_token as you sent them. Do not log them, forward them to other systems or expose them to end users, and call these endpoints only from your back end.

Get a Voice Action by ID

GET /v1/voice-action/:id → 200 OK

curl -X GET https://api.liguelead.com.br/v1/voice-action/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "api-token: YOUR_TOKEN" \
  -H "app-id: YOUR_APP_ID"

Update a Voice Action

PUT /v1/voice-action/:id → 200 OK

This is a partial update — send only the fields you want to change. At least one field is required. Updatable fields: name, config, credentials, phone, endpoint, authorization_token, message. message is accepted only on a SEND_SMS action, with the same rules as on creation.

⚠️ config is replaced as a whole, not merged. A config sent on update becomes the action's entire config: any key you leave out is removed, including required ones such as destination. To change one key, send the complete config with that key changed.

curl -X PUT https://api.liguelead.com.br/v1/voice-action/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Content-Type: application/json" \
  -H "api-token: YOUR_TOKEN" \
  -H "app-id: YOUR_APP_ID" \
  -d '{
    "name": "Schedule Meeting (Updated)",
    "config": {
      "calendar_id": "primary",
      "timezone": "America/Fortaleza",
      "destination": "[email protected]"
    }
  }'

When rotating credentials, send the full credentials object of the action's provider. On update, the API checks that it is a valid Microsoft or Google credentials object, but not that it matches the action's provider; likewise, phone, endpoint and config are not checked against the action's type. Only message is refused on a type other than SEND_SMS.

Delete a Voice Action

DELETE /v1/voice-action/:id → 204 No Content

curl -X DELETE https://api.liguelead.com.br/v1/voice-action/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "api-token: YOUR_TOKEN" \
  -H "app-id: YOUR_APP_ID"

⚠️ Stale references: deleting an action does not clear the action_id on Voice Agents that reference it. Update those agents manually to point at a valid action.

Limits

Resource	Limit
Voice Actions per client	50
Action `name` length	1–100 characters
`SEND_SMS` `message` length	1–1600 characters
`HTTP_WEBHOOK` `endpoint` / `authorization_token` length	up to 2048 characters each

Common Errors

Code	Message	Cause
`400`	`Maximum number of actions (50) reached for this client`	Per-client action limit reached.
`401`	`Authorization token missing`, `Authorization app id missing`, `Authorization failed`, …	Missing, invalid or blocked `api-token`/`app-id`, or an inactive app.
`404`	`Action not found`	The `id` does not exist for this client.
`422`	`At least one field must be provided for update`	Empty `PUT` body.
`422`	`Message contains blocked words: <words>`	The `SEND_SMS` `message` carries a blocked word.
`422`	`message is only accepted on SEND_SMS actions`	`PUT` with `message` on an action of another type.
`422`	Validation error	Invalid `type`/`provider` combination, missing required `config`/`credentials`/`endpoint`, or invalid e-mail/phone/URL.

Next Steps

How to Manage Voice Agents — attach this action to an AI agent.
How to Send Voice Calls with AI — dispatch calls and receive the webhook with the executed action.