respondendo.app

Requisição

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

Resposta

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

Os campos

O que vai no pedido

Só o telefone é obrigatório sempre. Agente ou roteiro: um dos dois. O resto é opcional.

telefone
DDD e número, só dígitos, com o 55 na frente.
agente_id
Agente criado no painel, com roteiro, modo, voz e ferramentas.
prompt
Roteiro inline, no lugar do agente. Aceita {{variavel}}.
modo · voz
Com prompt: super (voz da Super IA), ia (voz pronta, pelo nome) ou flex (IA Flex: consome metade do minuto).
variaveis
Até 30 pares chave e valor que entram no roteiro.
ferramentas
Funções que a IA pode chamar. Veja Ferramentas.
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.

Na sua linguagem

O mesmo pedido em PHP, Node e Python

É um POST comum com JSON e a sua chave no cabeçalho. Não precisa de biblioteca nossa.

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

Receber o resultado

Quando a ligação termina, o resultado chega como POST na webhook_url do pedido. Grave e responda 200.

Receber na sua 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);
  • Responda 2xx em até 5 segundos. Se precisar processar algo demorado, grave primeiro e processe depois.
  • É uma tentativa só. Se o seu sistema estava fora do ar, reenvie pelo painel, em Webhook.
  • Use o ligacao_id para não gravar a mesma ligação duas vezes: o reenvio chega com outro X-Entrega-Id.
  • call.failed quer dizer que a ligação não chegou a acontecer. O motivo vem em erro.
atendida
true quando a pessoa atendeu e houve conversa.
caixa_postal
true quando caiu na caixa postal.
segundos
Duração da conversa, em segundos.
caracteres_voz
Caracteres que a IA mandou gerar na voz (as vozes do modo IA são medidas por caractere). null na Super IA.
classificacao
Rótulo curto do resultado, sem acento e com sublinhado, como o seu roteiro pede para classificar.
objetivo_atingido
Nota de 0 a 10 de quanto o objetivo do roteiro foi cumprido.
resumo
Uma ou duas frases com o que ficou decidido.
transcricao
A conversa fala a fala, com quem falou e o segundo de cada fala.
gravacao_url
Link do áudio, enquanto a gravação estiver guardada.
erro
Motivo, quando a ligação falhou. Vazio quando deu certo.
variaveis
As mesmas que você mandou no pedido, para ligar o resultado ao seu registro.

Erros

Quando o pedido não passa

A ligação não sai e a resposta diz o motivo, com o código HTTP certo.

402POST /v1/ligacoes

{
  "erro": "SEM_CREDITO_OU_CANAL",
  "mensagem": "…"
}
  • erro é um código fixo, para o seu sistema decidir o que fazer. mensagem é o texto para uma pessoa ler.
  • SEM_CREDITO_OU_CANAL: sem saldo ou com todos os canais em uso. Tente de novo quando uma ligação terminar.
  • VARIAVEL_FALTANDO: o roteiro usa uma variável que não veio no pedido.
  • A lista completa está na Documentação.