# Funciones con tu API (webhook)

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](funciones-de-codigo.md) (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**:

```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:

```json
{
  "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:

```json
{ "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.