API reference

Authentication

Header Authorization: Bearer rsp_sua_chave on every route. The plain key is shown only when it is generated; the dashboard keeps just its prefix. Up to 5 active keys per account, revocable at any time.

GET /v1/saldo

curl "https://api.respondendo.app/v1/saldo" \
  -H "Authorization: Bearer rsp_sua_chave"

// 200
{
  "saldo": 93.470,
  "tarifa_minuto": 0.549,
  "canais_permitidos": 18,
  "em_andamento": 3
}

// error, always in this format
{
  "erro": "NAO_AUTORIZADO",
  "mensagem": "Chave de API inválida."
}

Create call

POST /v1/ligacoes. Use an agent from the dashboard (agente_id) or send the script in the request (prompt, modo and voz). The API checks balance and channels, reserves the call and responds 202 right away.

telefone

Digits only, 10 to 15, with the country code. Required.

agente_id

Id of the agent in the dashboard. This or prompt.

prompt

Inline script. Accepts {{variavel}}.

modo

super (Super AI voice), ia (ready voice, by name) or flex (AI Flex: uses half the minute). With prompt.

voz

{codigo, velocidade}. Super AI: bossa, tempo. AI: the name of one of the ready voices, like {"codigo": "Cristina"}. AI Flex: faber-medium, nova-medium, cadu-medium.

variaveis

Key-value object. Up to 30; value up to 500 characters.

ferramentas

{url, timeout_ms, headers, lista[]}. See Tools.

audio_fundo

AI mode only. Low ambient sound during the whole call: audio1 (people talking) or audio2 (someone typing). Without the field the call has no background.

webhook_url

Where this call's result goes. Without it, nothing is sent: the result stays available in the dashboard and through the API for up to 24 hours.

POST /v1/ligacoes

curl -X POST "https://api.respondendo.app/v1/ligacoes" \
  -H "Authorization: Bearer rsp_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "telefone": "5511988888888",
    "agente_id": 12,
    "variaveis": {
      "primeiro_nome": "Antônio",
      "visita": "quinta às 15h"
    },
    "webhook_url": "https://seusite.com/webhooks/ligacoes"
  }'

// 202
{
  "id": 512,
  "status": "em_andamento",
  "saldo": 93.470,
  "canais_permitidos": 18,
  "em_andamento": 4
}

the same, with the script in the request

{
  "telefone": "5511988888888",
  "prompt": "Você é a Marina, da Aurora Residencial. Confirme a visita de {{primeiro_nome}}…",
  "modo": "super",
  "voz": { "codigo": "bossa" },
  "variaveis": { "primeiro_nome": "Antônio" }
}

with one of the ready voices, chosen by name, and background sound (ia mode only)

{
  "telefone": "5511988888888",
  "prompt": "Você é a Marina, da Aurora Residencial. Confirme a visita de {{primeiro_nome}}…",
  "modo": "ia",
  "voz": { "codigo": "Carla" },
  "audio_fundo": "audio1",
  "variaveis": { "primeiro_nome": "Antônio" }
}

Female voices: Carla, Cristina, Fernanda, Sheila, Thayane, Greta, Isabela, Mariane, Raquel. Male: Rogerio, Cicerao, Eduardo, Carlos, Bruno, Vinicius, Gabriel. voz.codigo takes the voice name.

Query

GET /v1/ligacoes/{id} returns the state in status: na_fila, em_andamento, concluida, falhou or cancelada. Once the call is complete you get cost, summary, transcript and the signed recording link, valid for 1 hour.

GET /v1/ligacoes?de=2026-10-05&ate=2026-10-05&pagina=1 lists the period (up to 31 days), 100 per page, without transcript.

DELETE /v1/ligacoes/{id} removes it from the queue (cancelada) or hangs up the call in progress (encerrando). The result arrives in the webhook just the same.

GET /v1/ligacoes/512

{
  "id": 512,
  "status": "concluida",
  "telefone": "5511988888888",
  "agente_id": 12,
  "atendida": true,
  "segundos": 102,
  "custo": 0.933,
  "inicio_em": "2026-10-05 10:30:00",
  "fim_em": "2026-10-05 10:31:49",
  "resultado": "confirmado",
  "resumo": "Antônio confirmou a visita de quinta às 15h.",
  "gravacao_url": "https://api.respondendo.app/v1/gravacoes/512?exp=…&t=…",
  "gravacao_expira_em": "2026-10-06 10:31:55",
  "transcricao": { "conversa": [ … ] },
  "variaveis": { "primeiro_nome": "Antônio" },
  "webhook_entrega": {
    "id_entrega": "7f1c…",
    "resultado": "entregue",
    "http_status": 200
  }
}

Webhook

When the call ends, we make a JSON POST to the webhook_url sent in the request, with the headers X-Respondendo-Event and X-Entrega-Id. Respond 2xx within 5 seconds.

It is a single attempt. Every delivery is logged with what was sent, the status and the body you responded with: in the dashboard, under Webhook, and in GET /v1/webhook-entregas?ligacao_id=512. Resending is manual, from the dashboard, and creates a new delivery. transferencia carries the transfer to a human (celular, atendida_em, segundos, custo) or null: the call's segundos already includes that time, and the mobile leg is billed separately as a second call, already added to custo.

POST to your webhook_url

{
  "event": "call.completed",
  "entrega_id": "7f1c2a8e-…",
  "ligacao_id": 512,
  "agente": 12,
  "telefone": "5511988888888",
  "atendida": true,
  "segundos": 102,
  "transferencia": { "atendida": true, "celular": "5511977777777", "segundos": 69, "custo": 0.659 },
  "custo": 0.933,
  "saldo": 93.147,
  "resultado": "confirmado",
  "resumo": "Antônio confirmou a visita de quinta às 15h.",
  "transcricao": { "conversa": [ … ] },
  "gravacao_url": "https://api.respondendo.app/v1/gravacoes/512?exp=…&t=…",
  "variaveis": { "primeiro_nome": "Antônio" }
}

GET /v1/webhook-entregas?ligacao_id=512

{
  "ligacao_id": 512,
  "entregas": [{
    "id_entrega": "7f1c…",
    "resultado": "entregue",
    "http_status": 200,
    "duracao_ms": 212,
    "enviado_em": "2026-10-05 10:31:56"
  }]
}

Agents

GET /v1/agentes lists your agents. POST /v1/agentes creates one, with the same fields as the dashboard: nome, prompt, modo, voz, ferramentas, transferencia. GET /v1/agentes/{id} returns one. transferencia (optional) hands the call to a human: {quando, celulares[], frase_aguarde, frase_ninguem}. The AI stays on the line and rings the mobile numbers in round-robin (up to 20, with area code); whoever answers gets the person, and the time with the human is billed like the rest of the call. Nobody answered: the AI says frase_ninguem and carries on.

POST /v1/agentes

{
  "nome": "Confirmação de visita",
  "modo": "super",
  "voz": "bossa",
  "prompt": "Você é a Marina, da Aurora Residencial…",
  "transferencia": {
    "quando": "a pessoa pedir para falar com alguém da equipe",
    "celulares": ["5511999990000", "5511988880000"]
  }
}

// 201
{
  "id": 12,
  "nome": "Confirmação de visita",
  "modo": "super",
  "voz": { "codigo": "bossa" }
}

the same agent with a ready voice (Carla) and background sound

{
  "nome": "Confirmação de visita",
  "modo": "ia",
  "voz": { "codigo": "Carla", "velocidade": 1.0 },
  "audio_fundo": "audio1",
  "prompt": "Você é a Marina, da Aurora Residencial…",
  "transferencia": {
    "quando": "a pessoa pedir para falar com alguém da equipe",
    "celulares": ["5511999990000"]
  }
}

// 201
{
  "id": 13,
  "nome": "Confirmação de visita",
  "modo": "ia",
  "voz": { "codigo": "Carla", "velocidade": 1.0 },
  "audio_fundo": "audio1"
}