respondendo.app

Request

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

Response

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

The fields

What goes in the request

Only the phone is always required. Agent or script: one of the two. The rest is optional.

telefone
Area code and number, digits only, with 55 in front.
agente_id
Agent created in the dashboard, with script, mode, voice and tools.
prompt
Inline script, instead of the agent. Accepts {{variavel}}.
modo · voz
With prompt: super (Super AI voice), ia (ready voice, by name) or flex (AI Flex: uses half the minute).
variaveis
Up to 30 key-value pairs that go into the script.
ferramentas
Functions the AI can call. See Tools.
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.

In your language

The same request in PHP, Node and Python

It is a plain POST with JSON and your key in the header. No library of ours is needed.

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

Receiving the result

When the call ends, the result arrives as a POST to the webhook_url of the request. Store it and answer 200.

Receiving at your 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);
  • Answer 2xx within 5 seconds. If you need slow processing, store first and process later.
  • There is only one attempt. If your system was down, resend it from the dashboard, under Webhook.
  • Use ligacao_id to avoid storing the same call twice: a resend comes with another X-Entrega-Id.
  • call.failed means the call never happened. The reason comes in erro.
atendida
true when the person answered and there was a conversation.
caixa_postal
true when it went to voicemail.
segundos
Length of the conversation, in seconds.
caracteres_voz
Characters the AI sent to the voice (AI-mode voices are measured per character). null on Super AI.
classificacao
Short label of the result, without accents and with underscores, as your script asks to classify.
objetivo_atingido
Score from 0 to 10 of how much of the script goal was met.
resumo
One or two sentences with what was decided.
transcricao
The conversation turn by turn, with who spoke and the second of each turn.
gravacao_url
Link to the audio, while the recording is kept.
erro
The reason, when the call failed. Empty when it worked.
variaveis
The same ones you sent in the request, to link the result to your record.

Errors

When the request does not go through

The call does not go out and the response tells why, with the right HTTP code.

402POST /v1/ligacoes

{
  "erro": "SEM_CREDITO_OU_CANAL",
  "mensagem": "…"
}
  • erro is a fixed code, so your system can decide what to do. mensagem is the text for a person to read.
  • SEM_CREDITO_OU_CANAL: no balance or all channels in use. Try again when a call ends.
  • VARIAVEL_FALTANDO: the script uses a variable that was not in the request.
  • The full list is in the Documentation.