Referencia de la API

Autenticación

Cabecera Authorization: Bearer rsp_sua_chave en toda ruta. La clave en claro aparece solo cuando se genera; en el panel queda su inicio. Hasta 5 claves activas por cuenta, revocables en cualquier momento.

HTTP	Cuándo
401	Sin clave, clave inválida o revocada.
403	Cuenta bloqueada.
402	Sin saldo o sin canal libre.
429	Más de 60 peticiones en el 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
}

// error, siempre en este formato
{
  "erro": "NAO_AUTORIZADO",
  "mensagem": "Chave de API inválida."
}

Crear llamada

POST /v1/ligacoes. Usa un agente del panel (agente_id) o envía el guion en la petición (prompt, modo y voz). La API verifica saldo y canales, reserva la llamada y responde 202 al instante.

telefone

Solo dígitos, de 10 a 15, con el código de país. Obligatorio.

agente_id

Id del agente del panel. Él o prompt.

prompt

Guion inline. Acepta {{variavel}}.

modo

super (voz de Super IA), ia (voz lista, por el nombre) o flex (IA Flex: consume la mitad del minuto). Con prompt.

voz

{codigo, velocidade}. Super IA: bossa, tempo. IA: el nombre de una de las voces listas, como {"codigo": "Cristina"}. IA Flex: faber-medium, nova-medium, cadu-medium.

variaveis

Objeto clave y valor. Hasta 30; valor hasta 500 caracteres.

ferramentas

{url, timeout_ms, headers, lista[]}. Mira Herramientas.

audio_fundo

Solo en modo IA. Sonido ambiente bajo durante toda la llamada: audio1 (personas conversando) o audio2 (alguien tecleando). Sin el campo, la llamada sale sin fondo.

webhook_url

Adónde llega el resultado de esta llamada. Sin ella, no se envía nada: el resultado queda disponible en el panel y por la API hasta 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
}

lo mismo, con el guion en la petición

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

con una de las voces listas, elegida por el nombre, y sonido de fondo (solo en 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" }
}

Voces femeninas: Carla, Cristina, Fernanda, Sheila, Thayane, Greta, Isabela, Mariane, Raquel. Masculinas: Rogerio, Cicerao, Eduardo, Carlos, Bruno, Vinicius, Gabriel. En voz.codigo va el nombre de la voz.

Consultar

GET /v1/ligacoes/{id} devuelve el estado en status: na_fila, em_andamento, concluida, falhou o cancelada. Con la llamada concluida vienen costo, resumen, transcripción y el enlace firmado de la grabación, válido por 1 hora.

GET /v1/ligacoes?de=2026-10-05&ate=2026-10-05&pagina=1 lista el período (hasta 31 días), 100 por página, sin transcripción.

DELETE /v1/ligacoes/{id} saca de la cola (cancelada) o cuelga la llamada en curso (encerrando). El resultado llega al webhook igual.

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

Cuando termina la llamada, hacemos un POST JSON a la webhook_url que vino en la petición, con las cabeceras X-Respondendo-Event y X-Entrega-Id. Responde 2xx en hasta 5 segundos.

Es un solo intento. Cada entrega queda registrada con lo que se envió, el status y el cuerpo que respondiste: en el panel, en Webhook, y en GET /v1/webhook-entregas?ligacao_id=512. El reenvío es manual, por el panel, y genera una entrega nueva. transferencia trae la transferencia a un humano (celular, atendida_em, segundos, custo) o null: los segundos de la llamada ya incluyen ese tiempo, y el tramo del celular se cobra aparte como segunda llamada, ya sumado en custo.

resultado	Significa
entregue	Respondiste 2xx.
erro	Otro código. Status y cuerpo guardados.
sem_resposta	Sin respuesta en 5 segundos.

POST a tu 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 tus agentes. POST /v1/agentes crea uno, con los mismos campos del panel: nome, prompt, modo, voz, ferramentas, transferencia. GET /v1/agentes/{id} devuelve uno. transferencia (opcional) pasa la llamada a un humano: {quando, celulares[], frase_aguarde, frase_ninguem}. La IA sigue en la línea y llama a los celulares en rotación (hasta 20, con código de área); quien contesta recibe a la persona, y el tiempo con el humano se cobra como el resto de la llamada. Nadie contestó: la IA dice la frase_ninguem y sigue la conversación.

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

el mismo agente con voz lista (Carla) y sonido de fondo

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