respondendo.app

How to declare

The ferramentas block goes in the call request or in the agent. One url receives every call, with the function name and the parameters the AI extracted from speech. You respond with a JSON and it goes back to the AI as context.

url
Where we send the POST. Can be one per function.
timeout_ms
From 300 to 3000. Past that, the AI moves on without the data and tells the person.
headers
Fixed headers, like your system's token.
lista[]
List:

"ferramentas" in the agent or in the request

{
  "url": "https://loja.exemplo.com/ia/ferramentas",
  "timeout_ms": 1500,
  "headers": { "X-Token": "seu-token" },
  "lista": [
    {
      "nome": "consultar_pedido",
      "descricao": "Situação e previsão de entrega de um pedido pelo número",
      "frase_espera": "Só um instante, vou olhar o seu pedido.",
      "parametros": {
        "numero_pedido": { "tipo": "string", "obrigatorio": true, "descricao": "Só dígitos" }
      }
    },
    {
      "nome": "consultar_cep",
      "url": "https://brasilapi.com.br/api/cep/v1/{cep}",
      "metodo": "GET",
      "descricao": "Endereço de um CEP",
      "parametros": { "cep": { "tipo": "string", "obrigatorio": true } }
    }
  ]
}

During the call

What happens in 400 ms

  1. AntônioI wanted to check on my order, number 48213.

  2. AIOne moment, let me look up your order.

  3. POSTto your url: {"ferramenta": "consultar_pedido", "argumentos": {"numero_pedido": "48213"}}

  4. 200you respond: {"situacao": "em transporte", "previsao": "quinta-feira"}

  5. AIFound it. Your order is already in transit and the expected delivery is Thursday.

Rules

Limits

Functions per agent
20
Calls per phone call
15
Response from your URL
up to 8,000 characters
Timeout
300 to 3000 ms
Logging
every call in the result

Examples

The most common tools

The name and description tell the AI when to use it. The parameters are what it takes from what the person says. The response is what it uses to go on.

consultar_horarios

Shows the free slots in your calendar so the AI can offer them to the person.

Parameters: data

{"horarios": ["09:00", "10:30", "15:00"]}

agendar

Books the slot the person chose in your calendar and returns the confirmation.

Parameters: data, hora

{"ok": true, "protocolo": "A-2291"}

registrar_interesse

Creates or updates the contact in your CRM with what the person said on the call.

Parameters: produto, melhor_horario

{"ok": true}

segunda_via

Your system creates the bill or the Pix and sends it by WhatsApp or email while the AI is still on the line.

Parameters: forma

{"enviado": true, "canal": "whatsapp"}

On your side

What arrives and what to answer

Each call is a POST with JSON to your URL. Answer 200 with a short JSON: the AI reads it and speaks in its own words.

What arrives at your URL

{
  "event": "tool.call",
  "call_id": "…",
  "tool_call_id": "…",
  "numero_destino": "5511988888888",
  "ferramenta": "consultar_pedido",
  "argumentos": { "numero_pedido": "48213" }
}
  • Send only the data the AI will use. The limit is 8,000 characters.
  • A 4xx response with a body, such as {"erro": "pedido não encontrado"}, goes to the AI, which checks the data with the person and tries again.
  • A 5xx error or a delay over timeout_ms: the AI says the system is slow and goes on with the conversation.
  • numero_destino tells you who the AI is talking to, without asking for the phone number again.
  • frase_espera is what the AI says while it waits for your response, so the line is not silent.

One endpoint for several functionsPHP

<?php
$chamada = json_decode(file_get_contents('php://input'), true);
$args = $chamada['argumentos'];
header('Content-Type: application/json');

switch ($chamada['ferramenta']) {
    case 'consultar_pedido':
        $pedido = buscarPedido($args['numero_pedido']);
        if (!$pedido) {
            http_response_code(404);
            echo json_encode(['erro' => 'pedido não encontrado']);
            break;
        }
        echo json_encode(['situacao' => $pedido['situacao'], 'previsao' => $pedido['previsao']]);
        break;
    case 'consultar_horarios':
        echo json_encode(['horarios' => horariosLivres($args['data'])]);
        break;
}