Documentación
Agentes de Voz.md

Funciones con tu API (webhook)

Conecta tu agente de voz con tu propia API para consultar o registrar datos durante la llamada.

Una función con webhook hace que tu agente de voz llame a tu propia API durante la conversación: consultar el estado de un pedido, verificar un cliente, crear una reserva en tu sistema… El agente decide cuándo usarla, le pasa los datos que necesita y usa tu respuesta para seguir hablando.

💡 Si no tienes un servidor propio, puedes escribir la lógica en JavaScript dentro de Anunzi con una función de código (agentes ⚡ VPower).

Crear una función con webhook

En la ficha del agente: Funciones → + Agregar función → Funciones propias → Con tu API (webhook).

Campo Qué poner
Nombre Sin espacios, por ejemplo consultarPedido.
Descripción Cuándo debe usarla el agente. Es lo que el agente lee para decidir.
URL La dirección de tu API, por ejemplo https://api.miempresa.com/pedidos/estado.
Método POST (recomendado) o GET.
Parámetros (esquema JSON) Qué datos le pasa el agente.

Parámetros

Igual que en las funciones de código, se definen con un esquema JSON:

{
  "type": "object",
  "properties": {
    "numero_pedido": { "type": "string", "description": "Número de pedido que dice la persona" }
  },
  "required": ["numero_pedido"]
}

Variables en la URL, los parámetros y las cabeceras

Puedes usar variables entre llaves dobles, que se reemplazan en cada llamada:

  • {{telefono}} o {{user_number}}: el teléfono de la persona.
  • {{agent_number}}: el número del agente.
  • {{call_id}}: el identificador de la llamada.
  • Las variables dinámicas que mandes al crear la llamada, y los parámetros de la función.

Ejemplo: https://api.miempresa.com/clientes?telefono={{telefono}}.

Qué recibe tu API

Con POST, tu API recibe un JSON con los parámetros en la raíz y los datos de la llamada:

{
  "numero_pedido": "A-1234",
  "name": "consultarPedido",
  "args": { "numero_pedido": "A-1234" },
  "call": {
    "call_id": "...",
    "agent_id": "...",
    "direction": "inbound",
    "from_number": "+5491100000000",
    "to_number": "+5491100000001",
    "retell_llm_dynamic_variables": { }
  }
}

Con GET, los parámetros llegan en la URL (?numero_pedido=A-1234).

Qué tiene que responder

Responde con un JSON (o texto) con lo que el agente necesita saber. Por ejemplo:

{ "estado": "en camino", "llega": "mañana entre 9 y 13 h", "mensaje": "Contarle a la persona que el pedido llega mañana por la mañana." }
  • Responde rápido: el agente espera tu respuesta mientras la persona está en la llamada.
  • Si algo falla, responde con un error explicado. Un código HTTP 400 o 500 hace que el agente sepa que la función falló y ofrezca otra alternativa.

Probar tus funciones

En la ficha, Probar en texto muestra cada función que ejecuta el agente, con los datos que le mandó y lo que respondió tu API. Así puedes verificar que todo funcione antes de publicar.

Esc