respondendo.app

Cómo declarar

El bloque ferramentas va en la petición de la llamada o en el agente. Una url recibe todas las llamadas, con el nombre de la función y los parámetros que la IA extrajo del habla. Respondes un JSON y vuelve a la IA como contexto.

url
Adónde enviamos el POST. Puede ser una por función.
timeout_ms
De 300 a 3000. Pasado eso, la IA sigue sin el dato y se lo dice a la persona.
headers
Cabeceras fijas, como el token de tu sistema.
lista[]
Lista:

"ferramentas" en el agente o en la petición

{
  "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 la llamada

Qué pasa en 400 ms

  1. AntônioQuería saber de mi pedido, el 48213.

  2. IAUn momento, voy a revisar tu pedido.

  3. POSTa tu url: {"ferramenta": "consultar_pedido", "argumentos": {"numero_pedido": "48213"}}

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

  5. IAAquí lo tengo. Tu pedido ya está en transporte y la entrega está prevista para el jueves.

Reglas

Límites

Funciones por agente
20
Llamadas por conversación
15
Respuesta de tu URL
hasta 8.000 caracteres
Tiempo de espera
300 a 3000 ms
Registro
cada llamada en el resultado

Ejemplos

Las herramientas más usadas

El nombre y la descripción le dicen a la IA cuándo usarla. Los parámetros son lo que saca de lo que dice la persona. La respuesta es lo que usa para seguir.

consultar_horarios

Muestra los horarios libres de tu agenda para que la IA los ofrezca a la persona.

Parámetros: data

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

agendar

Guarda en tu agenda el horario que eligió la persona y devuelve la confirmación.

Parámetros: data, hora

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

registrar_interesse

Crea o actualiza el contacto en tu CRM con lo que la persona contó en la llamada.

Parámetros: produto, melhor_horario

{"ok": true}

segunda_via

Tu sistema genera la boleta o el Pix y lo envía por WhatsApp o correo mientras la IA sigue en la línea.

Parámetros: forma

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

De tu lado

Qué llega y qué responder

Cada llamada es un POST con JSON en tu URL. Responde 200 con un JSON corto: la IA lo lee y habla con sus propias palabras.

Lo que llega a tu URL

{
  "event": "tool.call",
  "call_id": "…",
  "tool_call_id": "…",
  "numero_destino": "5511988888888",
  "ferramenta": "consultar_pedido",
  "argumentos": { "numero_pedido": "48213" }
}
  • Envía solo los datos que la IA va a usar. El límite es de 8.000 caracteres.
  • Una respuesta 4xx con cuerpo, como {"erro": "pedido não encontrado"}, va a la IA, que confirma el dato con la persona y vuelve a intentar.
  • Error 5xx o demora mayor que timeout_ms: la IA avisa que el sistema está tardando y sigue la conversación.
  • numero_destino dice con quién está hablando la IA, sin pedir el teléfono otra vez.
  • frase_espera es lo que dice la IA mientras espera tu respuesta, para que la línea no quede en silencio.

Un endpoint para varias funcionesPHP

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