respondendo.app

Petición

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

Respuesta

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

Webhook

{
  "event": "call.completed",
  "ligacao_id": 512,
  "telefone": "5511988888888",
  "atendida": true,
  "caixa_postal": false,
  "segundos": 102,
  "custo": 0.933,
  "caracteres_voz": 318,
  "classificacao": "visita_confirmada",
  "objetivo_atingido": "9",
  "resumo": "Visita confirmada.",
  "transcricao": { "conversa": [ … ] },
  "gravacao_url": "…/gravacoes/512"
}

Los campos

Qué va en la petición

Solo el teléfono es obligatorio siempre. Agente o guion: uno de los dos. El resto es opcional.

telefone
Código de área y número, solo dígitos, con el 55 adelante.
agente_id
Agente creado en el panel, con guion, modo, voz y herramientas.
prompt
Guion inline, en lugar del agente. Acepta {{variavel}}.
modo · voz
Con prompt: super (voz de Super IA), ia (voz lista, por el nombre) o flex (IA Flex: consume la mitad del minuto).
variaveis
Hasta 30 pares clave y valor que entran en el guion.
ferramentas
Funciones que la IA puede llamar. Mira Herramientas.
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.

En tu lenguaje

El mismo pedido en PHP, Node y Python

Es un POST común con JSON y tu clave en el encabezado. No necesitas ninguna biblioteca nuestra.

PHPPOST /v1/ligacoes

<?php
$ch = curl_init('https://api-homologacao.respondendo.app/v1/ligacoes');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer rsp_sua_chave', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'telefone' => '5511988888888',
        'agente_id' => 12,
        'variaveis' => ['primeiro_nome' => 'Antônio', 'visita' => 'quinta às 15h'],
        'webhook_url' => 'https://seu-sistema.com/webhook/ligacoes',
    ]),
]);
$ligacao = json_decode(curl_exec($ch), true);
echo $ligacao['id'];

Node.jsPOST /v1/ligacoes

const resposta = await fetch('https://api-homologacao.respondendo.app/v1/ligacoes', {
  method: 'POST',
  headers: { Authorization: 'Bearer rsp_sua_chave', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    telefone: '5511988888888',
    agente_id: 12,
    variaveis: { primeiro_nome: 'Antônio', visita: 'quinta às 15h' },
    webhook_url: 'https://seu-sistema.com/webhook/ligacoes'
  })
});
const ligacao = await resposta.json();
console.log(ligacao.id);

PythonPOST /v1/ligacoes

import requests

resposta = requests.post(
    'https://api-homologacao.respondendo.app/v1/ligacoes',
    headers={'Authorization': 'Bearer rsp_sua_chave'},
    json={
        'telefone': '5511988888888',
        'agente_id': 12,
        'variaveis': {'primeiro_nome': 'Antônio', 'visita': 'quinta às 15h'},
        'webhook_url': 'https://seu-sistema.com/webhook/ligacoes',
    },
)
print(resposta.json()['id'])

Webhook

Recibir el resultado

Cuando la llamada termina, el resultado llega como POST en la webhook_url del pedido. Guárdalo y responde 200.

Recibir en tu URLPHP

<?php
$ligacao = json_decode(file_get_contents('php://input'), true);

if ($ligacao['event'] === 'call.completed' && $ligacao['atendida']) {
    salvarResultado(
        $ligacao['ligacao_id'],
        $ligacao['classificacao'],
        $ligacao['resumo'],
        $ligacao['variaveis']
    );
}

http_response_code(200);
  • Responde 2xx en hasta 5 segundos. Si necesitas un proceso lento, guarda primero y procesa después.
  • Es un solo intento. Si tu sistema estaba caído, reenvía desde el panel, en Webhook.
  • Usa el ligacao_id para no guardar la misma llamada dos veces: el reenvío llega con otro X-Entrega-Id.
  • call.failed quiere decir que la llamada no llegó a ocurrir. El motivo viene en erro.
atendida
true cuando la persona contestó y hubo conversación.
caixa_postal
true cuando cayó en el buzón de voz.
segundos
Duración de la conversación, en segundos.
caracteres_voz
Caracteres que la IA mandó generar en la voz (las voces del modo IA se miden por carácter). null en Super IA.
classificacao
Etiqueta corta del resultado, sin tildes y con guion bajo, como tu guion pide clasificar.
objetivo_atingido
Nota de 0 a 10 de cuánto se cumplió el objetivo del guion.
resumo
Una o dos frases con lo que se decidió.
transcricao
La conversación turno a turno, con quién habló y el segundo de cada turno.
gravacao_url
Enlace del audio, mientras la grabación esté guardada.
erro
El motivo, cuando la llamada falló. Vacío cuando salió bien.
variaveis
Las mismas que enviaste en el pedido, para vincular el resultado a tu registro.

Errores

Cuando el pedido no pasa

La llamada no sale y la respuesta dice el motivo, con el código HTTP correcto.

402POST /v1/ligacoes

{
  "erro": "SEM_CREDITO_OU_CANAL",
  "mensagem": "…"
}
  • erro es un código fijo, para que tu sistema decida qué hacer. mensagem es el texto para que lo lea una persona.
  • SEM_CREDITO_OU_CANAL: sin saldo o con todos los canales en uso. Intenta de nuevo cuando termine una llamada.
  • VARIAVEL_FALTANDO: el guion usa una variable que no vino en el pedido.
  • La lista completa está en la Documentación.