respondendo.app

Como declarar

O bloco ferramentas vai no pedido da ligação ou no agente. Uma url recebe todas as chamadas, com o nome da função e os parâmetros que a IA extraiu da fala. Você responde um JSON e ele volta para a IA como contexto.

url
Para onde mandamos o POST. Pode ser uma por função.
timeout_ms
De 300 a 3000. Passou disso, a IA segue sem o dado e avisa a pessoa.
headers
Cabeçalhos fixos, como o token do seu sistema.
lista[]
Lista:

"ferramentas" no agente ou no pedido

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

Durante a ligação

O que acontece em 400 ms

  1. AntônioQueria saber do meu pedido, o 48213.

  2. IASó um instante, vou olhar o seu pedido.

  3. POSTna sua url: {"ferramenta": "consultar_pedido", "argumentos": {"numero_pedido": "48213"}}

  4. 200você responde: {"situacao": "em transporte", "previsao": "quinta-feira"}

  5. IAEncontrei aqui. O seu pedido já está em transporte e a previsão de entrega é quinta-feira.

Regras

Limites

Funções por agente
20
Chamadas por ligação
15
Resposta da sua URL
até 8.000 caracteres
Tempo de espera
300 a 3000 ms
Registro
cada chamada no resultado

Exemplos

Ferramentas que mais aparecem

O nome e a descrição dizem à IA quando usar. Os parâmetros são o que ela tira da fala da pessoa. A resposta é o que ela usa para continuar.

consultar_horarios

Mostra os horários livres da sua agenda para a IA oferecer à pessoa.

Parâmetros: data

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

agendar

Grava na sua agenda o horário que a pessoa escolheu e devolve a confirmação.

Parâmetros: data, hora

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

registrar_interesse

Cria ou atualiza o contato no seu CRM com o que a pessoa contou na ligação.

Parâmetros: produto, melhor_horario

{"ok": true}

segunda_via

Seu sistema gera o boleto ou o Pix e manda por WhatsApp ou e-mail enquanto a IA ainda está na linha.

Parâmetros: forma

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

Do seu lado

O que chega e o que responder

Cada chamada é um POST com JSON na sua URL. Responda 200 com um JSON curto: a IA lê e fala com as próprias palavras.

O que chega na sua URL

{
  "event": "tool.call",
  "call_id": "…",
  "tool_call_id": "…",
  "numero_destino": "5511988888888",
  "ferramenta": "consultar_pedido",
  "argumentos": { "numero_pedido": "48213" }
}
  • Mande só os dados que a IA vai usar. O limite é de 8.000 caracteres.
  • Resposta 4xx com corpo, como {"erro": "pedido não encontrado"}, vai para a IA, que confirma o dado com a pessoa e tenta de novo.
  • Erro 5xx ou demora acima do timeout_ms: a IA avisa que o sistema está demorando e segue a conversa.
  • numero_destino diz com quem a IA está falando, sem precisar pedir o telefone de novo.
  • frase_espera é o que a IA fala enquanto espera a sua resposta, para a linha não ficar muda.

Um endpoint para várias funçõesPHP

<?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;
}