Referência da API

Autenticação

Cabeçalho Authorization: Bearer rsp_sua_chave em toda rota. A chave em claro aparece só na hora em que é gerada; no painel fica o começo dela. Até 5 chaves ativas por conta, revogáveis a qualquer momento.

HTTP	Quando
401	Sem chave, chave inválida ou revogada.
403	Conta bloqueada.
402	Sem saldo ou sem canal livre.
429	Mais de 60 pedidos no minuto.

GET /v1/saldo

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

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

// erro, sempre neste formato
{
  "erro": "NAO_AUTORIZADO",
  "mensagem": "Chave de API inválida."
}

Criar ligação

POST /v1/ligacoes. Use um agente do painel (agente_id) ou mande o roteiro no pedido (prompt, modo e voz). A API confere saldo e canais, reserva a ligação e responde 202 na hora.

telefone

Só dígitos, de 10 a 15, com o DDI. Obrigatório.

agente_id

Id do agente do painel. Ele ou prompt.

prompt

Roteiro inline. Aceita {{variavel}}.

modo

super (voz da Super IA), ia (voz pronta, pelo nome) ou flex (IA Flex: consome metade do minuto). Com prompt.

voz

{codigo, velocidade}. Super IA: bossa, tempo. IA: o nome de uma das vozes prontas, como {"codigo": "Cristina"}. IA Flex: faber-medium, nova-medium, cadu-medium.

variaveis

Objeto chave e valor. Até 30; valor até 500 caracteres.

ferramentas

{url, timeout_ms, headers, lista[]}. Veja Ferramentas.

audio_fundo

Só no modo IA. Som ambiente baixo durante toda a ligação: audio1 (pessoas conversando) ou audio2 (pessoa digitando). Sem o campo, a ligação sai sem fundo.

webhook_url

Onde o resultado desta ligação chega. Sem ela, nada é enviado: o resultado fica disponível no painel e pela API por até 24 horas.

POST /v1/ligacoes

curl -X POST "https://api-homologacao.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
}

o mesmo, com o roteiro no pedido

{
  "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" }
}

com uma das vozes prontas, escolhida pelo nome, e som de fundo (só no modo ia)

{
  "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" }
}

Vozes femininas: Carla, Cristina, Fernanda, Sheila, Thayane, Greta, Isabela, Mariane, Raquel. Masculinas: Rogerio, Cicerao, Eduardo, Carlos, Bruno, Vinicius, Gabriel. Em voz.codigo vai o nome da voz.

Consultar

GET /v1/ligacoes/{id} devolve a situação em status: na_fila, em_andamento, concluida, falhou ou cancelada. Com a ligação concluída vêm custo, resumo, transcrição e o link assinado da gravação, válido por 1 hora.

GET /v1/ligacoes?de=2026-10-05&ate=2026-10-05&pagina=1 lista o período (até 31 dias), 100 por página, sem transcrição.

DELETE /v1/ligacoes/{id} tira da fila (cancelada) ou derruba a ligação em andamento (encerrando). O resultado chega no webhook do mesmo jeito.

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-homologacao.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

Quando a ligação termina, fazemos um POST JSON na webhook_url que veio no pedido, com os cabeçalhos X-Respondendo-Event e X-Entrega-Id. Responda 2xx em até 5 segundos.

É uma tentativa só. Cada entrega fica registrada com o que foi enviado, o status e o corpo que você respondeu: no painel, em Webhook, e em GET /v1/webhook-entregas?ligacao_id=512. O reenvio é manual, pelo painel, e gera uma entrega nova. transferencia traz a transferência para um humano (celular, atendida_em, segundos, custo) ou null: o segundos da ligação já inclui esse tempo, e a perna do celular é cobrada à parte como segunda ligação, já somada no custo.

resultado	Significa
entregue	Você respondeu 2xx.
erro	Outro código. Status e corpo gravados.
sem_resposta	Sem resposta em 5 segundos.

POST na sua 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-homologacao.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"
  }]
}

Agentes

GET /v1/agentes lista os seus agentes. POST /v1/agentes cria um, com os mesmos campos do painel: nome, prompt, modo, voz, ferramentas, transferencia. GET /v1/agentes/{id} devolve um. transferencia (opcional) passa a ligação para um humano: {quando, celulares[], frase_aguarde, frase_ninguem}. A IA fica na linha e toca os celulares em rodízio (até 20, com DDD); quem atende recebe a pessoa, e o tempo com o humano é cobrado como o resto da ligação. Ninguém atendeu: a IA diz a frase_ninguem e segue a conversa.

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" }
}

o mesmo agente com voz pronta (Carla) e som de fundo

{
  "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"
}