# Funciones personalizadas

Las funciones personalizadas permiten que su bot de IA se conecte a otros sistemas durante conversaciones en vivo. En lugar de decir "Lo comprobaré y le responderé", el bot puede buscar el estado de un pedido, verificar el inventario o crear un registro en su CRM (sistema de gestión de relaciones con los clientes: el software que utiliza para realizar un seguimiento de clientes potenciales y clientes, como HubSpot o Salesforce), todo en tiempo real, mientras el cliente espera.


---

## Funciones personalizadas frente a Webhooks

Este es el punto de confusión más común, por lo que vale la pena aclararlo antes de construir nada.

| | Webhooks | Funciones personalizadas |
|---|----------|------------------|
| **Dirección** | Unidireccional (enviar y olvidar) | Bidireccional (llamar y esperar) |
| **Qué hace el bot** | Envía una notificación cuando ocurre algo y luego continúa. | Llama, **hace una pausa, espera la respuesta** y utiliza lo que recibe para continuar la conversación. |
| **Visibilidad de la conversación** | El resultado posterior es invisible para el bot; nunca ve lo que sucedió. | La respuesta se devuelve directamente a la IA, por lo que el bot puede citarla, razonar sobre ella y responder al cliente con ella. |
| **Ideal para** | Registrar eventos, sincronizar datos con un CRM, activar automatizaciones externas (Zapier, Make, n8n). | Cualquier cosa en la que el bot necesite una **respuesta** antes de poder responder: búsquedas en vivo, precios en tiempo real, generación de contenido al vuelo. |

**Cuándo elegir cuál:** Si solo necesita *informar* a otro sistema de que algo sucedió, use un webhook: un mensaje automatizado unidireccional enviado a otro sistema (consulte **Configuración → Integraciones → Webhooks**). Si el bot necesita *aprender* algo de otro sistema antes de continuar la conversación, use una función personalizada.

---

## Ejemplos de lo que desbloquean las funciones personalizadas

Debido a que la respuesta se retroalimenta en la conversación, las funciones personalizadas permiten hacer cosas que los webhooks simplemente no pueden:

- **Consulta de inventario en vivo de Shopify o WooCommerce** — Antes de dar un presupuesto a un cliente, el bot verifica el stock en tiempo real y responde "Sí, tenemos 12 en talla M" en lugar de "déjeme comprobarlo y le respondo".
- **Precios dinámicos desde una hoja de cálculo de Google** — Su equipo de ventas actualiza los precios en una hoja; el bot lee la última fila a mitad de la conversación y cita el precio actual sin que nadie toque la configuración de la IA.
- **Agente de devolución de llamada de IA de voz** — Cuando el bot califica a un cliente potencial, activa un agente de voz (por ejemplo, uno basado en ElevenLabs) para que llame al cliente potencial en cuestión de minutos y le confirme: "genial, espere una llamada en los próximos 5 minutos".
- **PDF de presupuesto personalizado, generado y enviado por correo electrónico a mitad del chat** — El bot recopila los requisitos, llama a su generador de presupuestos, obtiene una URL de PDF y le dice al cliente: "Acabo de enviar su presupuesto por correo electrónico, revise su bandeja de entrada".

---

## ¿Qué pueden hacer las funciones personalizadas?

Piense en las funciones personalizadas como si le dieran a su bot superpoderes más allá de simplemente chatear. Aquí hay ejemplos del mundo real:

- **Seguimiento de pedidos** - Un cliente pregunta "¿Dónde está mi pedido?" y el bot consulta su sistema de comercio electrónico y responde con el estado del envío y el enlace de seguimiento
- **Verificación de inventario** - "¿Tiene esto en talla 10?" El bot verifica su sistema de stock y da una respuesta en tiempo real
- **Actualizaciones de CRM** - Cuando el bot califica a un cliente potencial, crea o actualiza automáticamente un registro en HubSpot, Salesforce o cualquier otro CRM
- **Generación de presupuestos** - El bot recopila los requisitos del cliente y genera un presupuesto personalizado desde su sistema de precios
- **Reservas** - El bot crea una cita en su sistema de reservas externo
- **Verificación de descuentos** - "¿Es válido este código de cupón?" El bot lo verifica y confirma
- **Consulta de cuenta** - Se reconoce automáticamente a un cliente recurrente y se obtienen los detalles de su cuenta

**El cliente nunca ve lo que sucede detrás de escena.** Simplemente experimenta un bot que puede responder a sus preguntas con información real y actualizada.

---

## Cómo funcionan las funciones personalizadas (la versión simple)

Esto es lo que sucede cuando se activa una función personalizada durante una conversación:

1. **El cliente pregunta algo** que requiere datos en tiempo real (p. ej., "¿Dónde está mi pedido?")
2. **El bot reconoce** que necesita usar una función personalizada para responder
3. **El bot recopila** cualquier información faltante del cliente (p. ej., "¿Cuál es su número de pedido?")
4. **La plataforma envía una solicitud** a su sistema (su sitio web, CRM o cualquier otra herramienta) con los detalles relevantes
5. **Su sistema responde** con los datos (p. ej., estado del pedido, número de seguimiento, fecha de entrega)
6. **El bot lee la respuesta** y redacta una respuesta natural: "¡Su pedido ORD-4582 ha sido enviado y debería llegar el viernes!"

### Cuánto cuesta una llamada a una función personalizada

Cada llamada a una función personalizada se factura según el nivel de Calidad de IA de su Agente:

| Nivel de Calidad de IA | Créditos por llamada a función personalizada | Con su propia clave de Anthropic (BYOK) conectada |
|---|---|---|
| Pro | 1 crédito | 0 créditos: se ejecuta con su clave |
| Economy (en desuso) | 0.5 créditos | 0 créditos: se ejecuta con su clave |
| Max | 0.25 créditos | sigue siendo 0.25 créditos, se factura incluso con su propia clave conectada, porque Max se ejecuta en nuestro propio modelo |
| Mini | 0.15 créditos | sigue siendo 0.15 créditos, se factura incluso con su propia clave conectada, porque Mini se ejecuta en nuestro propio modelo |

---

## Configuración de una función personalizada (paso a paso)

1. En la barra lateral principal, bajo **AI Studio**, haga clic en **Custom Functions**.


2. Haga clic en el botón verde **+ Add Function** (o **New function**) en la parte superior derecha.


La lista de funciones personalizadas muestra una tabla con las siguientes columnas:

| Columna | Qué muestra |
|--------|--------------|
| **Name** | El nombre de la función (p. ej., `check_order_status`) |
| **Description** | Un breve resumen de lo que hace la función (truncado a 50 caracteres en la tabla) |
| **Method** | El método HTTP utilizado, mostrado como una insignia de color: GET (azul), POST (verde), PUT (naranja), DELETE (rojo) |
| **Created** | La fecha en que se creó la función |

Esto facilita el escaneo de sus funciones de un vistazo y encontrar la que necesita.

### Paso 1: Asígnele un nombre y una descripción


| Campo | Qué ingresar | Ejemplo |
|-------|--------------|---------|
| **Name** | Un nombre corto usando letras, números y guiones bajos | `check_order_status` |
| **Description** | Explique qué hace esta función (la IA lee esto para decidir cuándo usarla) | "Busca el estado actual del pedido de un cliente usando su número de pedido" |
| **Purpose (AI Action)** | Dígale a la IA exactamente cuándo y cómo usar esta función | "Úsela cuando un cliente pregunte sobre el estado de su pedido, envío o entrega. Pídale primero su número de pedido." |

**Consejo:** Sea muy específico en la descripción y el propósito. Cuanto más claro sea sobre cuándo debe usarse la función, con mayor fiabilidad la usará el bot en el momento adecuado.

### Paso 2: Configure la conexión

Debe indicarle a la aplicación a dónde enviar la solicitud:

| Campo | Qué ingresar | Ejemplo |
|-------|--------------|---------|
| **URL** | La dirección web del punto final de su sistema (la dirección específica en su sistema que recibe la solicitud y devuelve datos) | `https://api.yourstore.com/v1/orders/status` |
| **Método** | El tipo de solicitud a enviar | Ver opciones a continuación |

**Qué método elegir:**

| Método | Cuándo usarlo |
|--------|---------------|
| **GET** | Buscar información (estado del pedido, inventario, detalles de la cuenta) |
| **POST** | Crear nuevos registros (tickets de soporte, leads, reservas) o búsquedas complejas |
| **PUT** | Actualizar un registro existente por completo |
| **PATCH** | Actualizar parte de un registro existente |
| **DELETE** | Eliminar un registro |

Si no está seguro de cuál usar, consulte con su desarrollador o con la documentación del sistema al que se está conectando. **GET** (para búsquedas) y **POST** (para crear registros) son los más comunes.

### Paso 3: Añadir encabezados de autenticación

La mayoría de los sistemas requieren autenticación para aceptar solicitudes. Añada los encabezados necesarios:

| Encabezado | Valor de ejemplo |
|--------|--------------|
| `Authorization` | `Bearer your-api-key-here` |
| `Content-Type` | `application/json` |

**Consejo de seguridad:** Utilice una clave de API dedicada con permisos limitados. No utilice credenciales de nivel de administrador.

**Dónde encontrar las claves de API:** Consulte la sección de configuración o de desarrolladores del sistema al que se está conectando (por ejemplo, su CRM, plataforma de comercio electrónico o herramienta de reservas).

### Paso 4: Definir la entrada (lo que envía el bot)

Los parámetros de entrada son las piezas de información que el bot recopila de la conversación y envía a su sistema.

Para cada parámetro, debe especificar:

| Propiedad | Qué significa |
|----------|--------------|
| **Nombre** | El nombre del parámetro (debe coincidir con lo que espera su sistema) |
| **Tipo** | Qué tipo de datos es (texto, número, verdadero/falso, etc.) |
| **Descripción** | Indique a la IA qué es esta información y dónde encontrarla en la conversación |
| **Obligatorio** | Si se establece en Sí, el bot solicitará esta información al cliente antes de continuar |

**Tipos de parámetros disponibles:**

| Tipo | Qué significa |
|------|--------------|
| **string** | Texto (nombres, números de pedido, direcciones) |
| **number** | Un valor numérico (cantidad, precio) |
| **boolean** | Verdadero o falso (valores sí/no) |
| **array** | Una lista de elementos. Se envía como una lista JSON real; en **Ejecutar prueba** puedes escribirla como `[8624]`, `["a", "b"]` o simplemente separada por comas (`8624, 8625`) y se convertirá automáticamente. Si tu API es estricta con respecto a lo que contiene la lista (por ejemplo, solo números), establece el **Tipo de elemento** opcional junto al tipo y cada valor de la lista se convertirá a él. |
| **query_param** | Texto que se envía como un parámetro de URL en lugar de en el cuerpo de la solicitud. Úsalo cuando tu API espere datos en la URL (por ejemplo, `?order_id=123`). |

Cada parámetro también tiene un campo opcional de **Ruta del cuerpo de la solicitud** (Request body path). Normalmente, un parámetro se envía como un campo de nivel superior en el cuerpo de la solicitud (o como un valor de cadena de consulta, para el tipo `query_param`). Si su endpoint espera que esté anidado —por ejemplo, `{"order": {"id": "ORD-123"}}`—, establezca la ruta en `order.id` y la plataforma anidará el valor allí por usted.


**Ejemplo: Para una búsqueda de estado de pedido, podría definir:**

- **order_number** (string, obligatorio): "El número de pedido del cliente. Suele empezar por ORD- seguido de dígitos. Pídale esto al cliente si no lo ha mencionado."
- **email** (string, opcional): "La dirección de correo electrónico del cliente para una verificación adicional. Solo es necesario si el número de pedido por sí solo no encuentra una coincidencia."

### Lo que su sistema recibe automáticamente

Además de los parámetros de entrada que usted define, la plataforma incluye automáticamente datos del sistema con cada solicitud. Su endpoint recibe esto en un campo `system`:

| Campo del sistema | Qué contiene |
|-------------|----------------|
| `system.contactId` | El ID de plataforma del contacto en la conversación |
| `system.campaignId` | El ID de campaña al que pertenece la conversación |
| `system.userId` | Su ID de usuario |
| `system.channel` | El canal de mensajería (p. ej., `"whatsapp"`, `"instagram"`) |
| `system.contact` | El registro de contacto completo (nombre, teléfono, correo electrónico, etiquetas, etc.) |
| `system.campaign` | La configuración de la campaña |
| `system.test` | `true` si es una prueba de Try Out, `false` para conversaciones en vivo |

Esto es útil si su sistema necesita identificar al contacto, verificar qué campaña activó la función o comportarse de manera diferente durante las pruebas.

> **¿No necesita los datos del sistema?** Active el interruptor **Omitir datos del sistema** en el generador de funciones. El bot enviará entonces solo los parámetros de entrada que usted definió, sin datos de contacto o de campaña. Utilice esto si su endpoint rechaza campos inesperados o si simplemente desea una carga útil más ligera.

### Paso 5: Pruébelo y luego deje que el bot lea la respuesta

Normalmente no necesita asignar los campos de respuesta en absoluto. Una vez que su endpoint responde, el bot lee toda la respuesta JSON y utiliza la **Descripción** y el **Propósito (Acción de IA)** de su función —además de la descripción propia de cada parámetro— para determinar qué es importante y presentarlo de forma natural. Una descripción clara en la propia función ("Recupera el estado actual de un pedido de cliente, incluida la información de envío y el seguimiento") hace más trabajo aquí que una asignación campo por campo.

Si su endpoint devuelve una respuesta grande y solo desea que el bot vea unos pocos valores específicos, abra la sección **Asignación de respuesta** (Response mapping) (contraída de forma predeterminada, justo encima de Probar). Cada fila selecciona un campo de nivel superior de la respuesta: **Campo de respuesta** es el nombre del campo en la respuesta JSON de su API, y **Campo de salida** es el nombre con el que el bot lo recibe. Con al menos una fila completada, el bot solo recibe sus valores asignados en lugar del cuerpo completo de la respuesta. Deje la sección vacía para mantener el comportamiento predeterminado de respuesta completa.


Antes de guardar, utilice la sección **Prueba** (Test) en la parte inferior del generador para ejecutar la solicitud exactamente como está configurada y ver la respuesta real, sin salir de la aplicación:


La respuesta que ve aquí es la respuesta sin procesar del endpoint. Si ha configurado el **Mapeo de respuesta** anteriormente, el bot en un chat real solo recibe esos campos mapeados; la prueba siempre muestra la respuesta completa sin procesar para que pueda ver qué está disponible para mapear. Si algo parece incorrecto (nombres de campo inesperados, anidamiento adicional), corríjalo en su endpoint o ajuste su mapeo.

---

## Asignación de funciones a un agente

Después de crear una función personalizada, debe indicar a cada agente qué funciones puede utilizar:

1. Abra el [Agente](../ai-agents/ai-agents.md) en **AI Studio → Agentes de IA**.
2. Vaya a su pestaña **Habilidades de IA** (AI Abilities). (Para una campaña que aún mantiene sus propios ajustes de IA directamente en lugar de a través de un Agente separado, la misma lista aparece en el paso **Habilidades de IA** de esa campaña).
3. Verá una lista de todas las funciones personalizadas que ha creado. Active cada función que desee que el bot de este Agente pueda llamar.
4. Haga clic en **Guardar cambios** en la parte inferior. Las selecciones solo se aplican una vez guardadas.


Solo las funciones asignadas están disponibles para el bot de ese agente. Esto evita que el bot utilice accidentalmente funciones que no son relevantes.

---

## Prueba de sus funciones personalizadas

Antes de ponerlas en funcionamiento, realice pruebas exhaustivas:

1. **Ejecute la prueba integrada** - Utilice la sección **Prueba** dentro del generador de funciones (ver arriba) para una verificación rápida sin salir de la aplicación: introduzca valores realistas y haga clic en Ejecutar prueba.
2. **Pruebe el endpoint de su sistema directamente** - Para la lista de verificación completa a continuación, una herramienta dedicada como Postman (o su desarrollador) profundiza más que una simple Ejecución de prueba.
3. **Pruebe en Probar** - Simule una conversación donde el cliente pregunte algo que debería activar la función.
4. **Verifique la respuesta** - Asegúrese de que el bot lea y presente los datos correctamente.
5. **Pruebe escenarios de error** - ¿Qué sucede si el cliente proporciona un número de pedido no válido? ¿Qué pasa si su sistema está temporalmente fuera de servicio?

### Cuando la prueba devuelve un 401 o 403

Un 401 o 403 significa que su endpoint recibió la solicitud y la rechazó. La pista es que **no aparece nada en sus propios registros**: la mayoría de las herramientas rechazan una llamada no autorizada antes de iniciar el flujo de trabajo, por lo que no hay nada que ver de su lado y parece que la solicitud nunca llegó.

Casi siempre se trata de un error de coincidencia en la autenticación: su endpoint requiere un tipo de credencial y la función está enviando una diferente. Compruebe que la cabecera que añadió en el [Paso 3](#step-3-add-authentication-headers) sea exactamente la que espera su sistema.

La versión más común de esto es un webhook protegido con **Autenticación básica** (n8n, Make y la mayoría de las herramientas autohospedadas ofrecen esto como una casilla de verificación en el propio webhook), mientras que la función envía una cabecera secreta personalizada como `X-My-Secret`. La Autenticación básica solo acepta una cabecera `Authorization`, por lo que se ignora la cabecera personalizada y se rechaza la llamada. Tiene dos opciones:

- **Desactive la Autenticación básica** en el webhook y, en su lugar, verifique su cabecera personalizada dentro del flujo de trabajo.
- **Mantenga la Autenticación básica activada** y añada una cabecera `Authorization` a la función cuyo valor sea la palabra `Basic` seguida de su `username:password` codificado en base64.

Cualquiera de las dos funciona; solo asegúrese de que ambas partes coincidan.

### Cuando la prueba devuelve un 404

La URL del endpoint es incorrecta o el flujo de trabajo no está publicado. En n8n específicamente, cada webhook tiene una URL de **Prueba** y una URL de **Producción** independientes, y la de prueba solo escucha mientras tiene el editor abierto. Copie la URL de producción y asegúrese de que el flujo de trabajo esté activo.

### Ver fallos en Probar y Chats

Cuando la IA llama a una función personalizada durante una conversación y la llamada falla (credenciales incorrectas, punto de conexión inactivo, tiempo de espera agotado), la conversación ahora lo muestra: aparece un marcador rojo **"(nombre de la función) falló"** en el hilo, tanto en la pestaña **Probar** del agente como en las conversaciones reales en **Chats**. Haga clic en el marcador para expandir los detalles: el código de estado que devolvió su punto de conexión y el cuerpo de su respuesta, lo cual suele ser suficiente para indicarle exactamente qué debe corregir (un `401` con un mensaje de "no autorizado" significa que el encabezado de autenticación, un tiempo de espera agotado significa que su punto de conexión tardó más de 30 segundos).

Las llamadas exitosas también muestran un marcador; haga clic en él para ver lo que realmente devolvió su punto de conexión. Esta es la forma más rápida de depurar una integración de extremo a extremo: realice la conversación de prueba en Probar y, a continuación, haga clic en el marcador de la función para ver el resultado real de la solicitud sin salir de la página.

---

## Ejemplo completo: Búsqueda del estado del pedido

Aquí tienes un ejemplo totalmente configurado que puedes usar como plantilla:

**Información básica:**
- **Nombre:** `check_order_status`
- **Descripción:** "Recupera el estado actual de un pedido de cliente, incluyendo información de envío y seguimiento"
- **Acción de IA:** "Llama a esto cuando un cliente pregunte por el estado de su pedido, dónde está su paquete o cuándo llegará. Pide siempre primero el número de pedido."

**Conexión:**
- **URL:** `https://api.mystore.com/orders/lookup`
- **Método:** POST

**Cabeceras:**
- `Authorization`: `Bearer sk_live_abc123`
- `Content-Type`: `application/json`

**Parámetros de entrada:**
- `order_number` (texto, obligatorio): "El número de pedido proporcionado por el cliente"
- `customer_email` (texto, opcional): "Correo electrónico del cliente para verificación adicional"

**No se necesita asignación de respuesta**: con una Descripción y una Acción de IA claras ya establecidas anteriormente, el bot lee cualquier JSON que devuelva su endpoint (estado, número de seguimiento, fecha de entrega, artículos) y determina cómo hablar sobre ello.

**Cómo se ve la conversación:**

> **Cliente:** Hola, ¿dónde está mi pedido?
>
> **Bot:** ¡Hola! Estaré encantado de comprobar tu pedido. ¿Podrías compartir conmigo tu número de pedido?
>
> **Cliente:** Es ORD-78234
>
> **Bot:** Déjame buscar eso por ti...
>
> ¡Tu pedido ORD-78234 ha sido enviado y está en camino! La fecha estimada de entrega es el 10 de marzo. Puedes rastrear tu paquete aquí: https://tracking.example.com/1Z999AA1
>
> ¿Hay algo más en lo que pueda ayudarte?

---

## Ejemplo completo: Estado del pedido en Shopify

Si la tienda funciona con Shopify, no necesitas un desarrollador para crear un endpoint de búsqueda; el propio sistema de Shopify puede responder directamente a las preguntas sobre pedidos. (Para preguntas sobre productos y existencias en una tienda Shopify, no necesitas ninguna función personalizada: conecta el servidor integrado de la tienda en su lugar; consulta [Conectar una tienda Shopify](mcp-servers.md#ready-made-example-connect-a-shopify-store)).

**Primero, crea un token de acceso en Shopify.** Shopify cambió esto durante 2026: las aplicaciones ya no pueden crearse dentro del panel de administración de Shopify, y la nueva pantalla de aplicaciones te proporciona un **ID de cliente** y un **Secreto de cliente** en lugar de un token ya preparado. Los pasos a continuación convierten esos datos en un token permanente. Reserva unos diez minutos, una vez por tienda. (Si la tienda ya tiene una aplicación antigua creada de la forma anterior, su token existente seguirá funcionando; salta directamente a la función personalizada a continuación).
1. Vaya al Panel de control de desarrolladores de Shopify en [dev.shopify.com](https://dev.shopify.com), abra su organización y haga clic en **Apps → Create app**. Asígnele un nombre como `Order lookup`.
2. Otorgue a la aplicación el permiso **read_orders**, publique una versión e instale la aplicación en la tienda.
3. Abra la **Configuración** de la aplicación y añada la dirección web de la tienda (por ejemplo, `https://www.yourstore.com/`) a las URLs de redirección permitidas. Guarde.
4. Todavía en **Configuración**, copie el **Client ID** y el **Client secret**.
5. En un navegador donde haya iniciado sesión en el administrador de Shopify de esa tienda, abra la dirección a continuación, reemplazando el nombre de la tienda, el ID de cliente y la dirección de redirección con los suyos:
   `https://YOUR-STORE.myshopify.com/admin/oauth/authorize?client_id=YOUR-CLIENT-ID&scope=read_orders&redirect_uri=https://www.yourstore.com/&state=12345`
   Apruebe la pantalla que aparece. El navegador llegará a su dirección de redirección y la barra de direcciones ahora contendrá `code=` seguido de un valor largo; copie ese valor. Solo es válido por un par de minutos, así que vaya directamente al siguiente paso.
6. Intercambie ese código por el token, lo cual puede hacer dentro de <span data-t="appName">Your AI Connector</span>. En el generador de funciones personalizadas, establezca **Method** en POST y **URL** en `https://YOUR-STORE.myshopify.com/admin/oauth/access_token`, añada tres parámetros de entrada de texto llamados `client_id`, `client_secret` y `code`, luego haga clic en **Test**, complete los tres valores y ejecútelo. La respuesta contiene `access_token` — ese es su token permanente. Cópielo en un lugar seguro, luego limpie el generador y configure la función real a continuación.

**Luego, configura la función personalizada:**

**Información básica:**
- **Nombre:** `check_shopify_order`
- **Descripción:** "Busca un pedido en el sistema Shopify de la tienda y devuelve su estado, seguimiento y artículos"
- **Acción de IA:** "Llama a esto cuando un cliente pregunte por el estado de su pedido o la entrega. Pide siempre el número de pedido primero."

**Conexión:**
- **URL:** `https://YOUR-STORE.myshopify.com/admin/api/2026-01/orders.json?status=any` — reemplaza `YOUR-STORE` con el nombre `.myshopify.com` de la tienda (esta dirección utiliza el dominio técnico de Shopify, no el dominio personalizado de la tienda)
- **Método:** GET

**Encabezados:**
- `X-Shopify-Access-Token`: `shpat_...` (el token de arriba)

**Parámetros de entrada:**
- `name` (query_param, obligatorio): "El número de pedido del cliente exactamente como aparece en su confirmación de pedido, incluido el signo #; por ejemplo, #1001. Pídeselo al cliente si no lo ha mencionado."

**No se necesita mapeo de respuesta**: el bot lee el pedido devuelto (estado de pago, estado de cumplimiento, seguimiento, artículos) y responde de forma natural.

**Es bueno saberlo:** un token creado de esta manera puede ver los pedidos de los **últimos 60 días**; suficiente para las preguntas de soporte diarias, pero no para un historial completo de pedidos.

---

## Ejemplo completo: Reservar una cita

**Información básica:**
- **Nombre:** `create_booking`
- **Descripción:** "Crea una nueva cita en nuestro sistema de reservas"
- **Acción de IA:** "Usa esto después de confirmar la fecha, la hora y los datos de contacto con el cliente. No llames hasta que el cliente confirme explícitamente que desea reservar."

**Conexión:**
- **URL:** `https://booking.mycompany.com/api/appointments`
- **Método:** POST

**Parámetros de entrada:**
- `date` (texto, obligatorio): "Fecha de la cita en formato AAAA-MM-DD"
- `time` (texto, obligatorio): "Hora de la cita en formato HH:MM"
- `name` (texto, obligatorio): "Nombre completo del cliente"
- `phone` (texto, obligatorio): "Número de teléfono del cliente"
- `service_type` (texto, obligatorio): "El tipo de servicio que se está reservando"

---

## Ejemplo completo: Añadir un suscriptor al boletín en su CRM

Un patrón muy común: el bot termina de responder, ofrece su boletín, el contacto responde con su dirección de correo electrónico y esa dirección debe llegar directamente a su herramienta de correo electrónico. La mayoría de los CRM (FluentCRM, ActiveCampaign, MailerLite, Brevo y otros) aceptan un simple POST para esto exactamente, por lo que no se necesita ninguna plataforma de automatización intermedia.

Este ejemplo utiliza **FluentCRM** en WordPress. La estructura es la misma para cualquier otra herramienta que le proporcione un "webhook entrante" o un endpoint de "crear suscriptor".

**Primero, obtenga la URL de su CRM.** En WordPress, abra **FluentCRM → Settings → Incoming Webhooks** y cree un webhook. Elija la lista, las etiquetas y el estado de suscripción que deben recibir los nuevos contactos, luego copie la URL del webhook que genera. Todo lo que configure aquí se aplica automáticamente, por lo que el bot solo tiene que enviar la dirección de correo electrónico.

**Luego, configura la función personalizada:**

**Información básica:**
- **Nombre:** `add_newsletter_subscriber`
- **Descripción:** "Añade a alguien a nuestra lista de boletines usando la dirección de correo electrónico que proporcionó en el chat"
- **Acción de IA:** "Utilice esto en el momento en que el contacto acepte suscribirse al boletín y proporcione su dirección de correo electrónico. No lo llame antes de que realmente hayan dado una dirección, y no lo llame dos veces para la misma persona."

**Conexión:**
- **URL:** la URL del webhook que copió de su CRM
- **Método:** POST

**Parámetros de entrada:**
- `email` (cadena, obligatorio): "La dirección de correo electrónico que el contacto proporcionó en la conversación"
- `first_name` (cadena, opcional): "El nombre del contacto, si lo mencionó"

**Omitir datos del sistema:** active esta opción. Su CRM solo necesita los campos anteriores, y una carga útil más ligera evita errores de herramientas que rechazan campos inesperados.

**Mapeo de respuesta:** no es necesario aquí. No tiene que volver nada para que el bot continúe.

**No olvide activar la función para el Agente que ejecuta la conversación** (consulte [Asignación de funciones a un agente](#assigning-functions-to-an-agent)). Esta es la razón más común por la que una función correctamente construida nunca se dispara.

::: tip
**Consejo:** el bot también tiene una herramienta integrada de **Actualizar correo electrónico del contacto**, que guarda la dirección en el registro del contacto dentro de la plataforma. Eso es independiente de esta función y útil junto a ella: la herramienta integrada mantiene completo su propio registro de contactos, la función personalizada envía la dirección a su CRM.
:::


---

## Consejos para funciones personalizadas fiables

1. **Asegúrate de que las solicitudes repetidas sean seguras.** Si la misma solicitud se envía accidentalmente dos veces, no debería crear registros duplicados. Los problemas de red pueden causar esto ocasionalmente.

2. **Devuelve mensajes de error claros.** Si algo sale mal por parte de tu sistema, devuelve un error legible para los humanos. El bot lo transmitirá al cliente de forma elegante.

3. **Mantén los tiempos de respuesta por debajo de los 10 segundos.** Si tu sistema tarda más, considera devolver primero un reconocimiento rápido.

4. **Gestiona las credenciales caducadas o no válidas.** Si tu clave de API caduca, asegúrate de que el mensaje de error sea claro para que el bot sepa que debe avisar a un humano en lugar de volver a intentarlo.

5. **Escribe descripciones detalladas.** La IA utiliza tus descripciones para determinar cuándo llamar a la función y cómo extraer la información correcta de la conversación. Las descripciones vagas conducen a errores.

6. **Pruebe con conversaciones reales.** Try Out es excelente para las pruebas iniciales, pero supervise sus primeras conversaciones en vivo para asegurarse de que todo funcione con las consultas reales de los clientes.

7. **Mantén registros (logs) por tu parte.** Pide a tu desarrollador que registre las solicitudes que provienen de la aplicación para que puedas depurar rápidamente cualquier problema.

8. **Utiliza una URL final pública.** La URL de tu función debe ser una dirección web pública (HTTP/HTTPS). Las direcciones internas, localhost y de red privada se rechazan por seguridad, y la plataforma no sigue redirecciones; apunta la función directamente a la URL final, no a una que redirija a ella.

---

## Límites de ejecución

Cada función personalizada tiene una sección opcional de **Límites de ejecución** en la parte inferior del editor. Controla con qué frecuencia la IA puede ejecutar la función y si se puede reutilizar un resultado anterior. Todo aquí es opcional: déjelo todo vacío y la función se comportará exactamente igual que antes.


**Función de solo lectura.** Active esto si su función solo *lee* datos (una búsqueda de acciones, una verificación de precios, una búsqueda de estado de pedido) y nunca crea ni cambia nada. Cuando un problema temporal de red interrumpe a la IA a mitad de la respuesta, la plataforma puede volver a intentar el turno de la conversación de forma segura en lugar de dejar al cliente sin respuesta. Solo habilítelo si la función realmente nunca escribe nada: una función que crea registros debe permanecer desactivada, para que un reintento nunca pueda ejecutarla dos veces accidentalmente.

**Servir resultado en caché en llamadas repetidas.** Cuando la IA llama a la función de nuevo con las mismas entradas (por ejemplo, el cliente hace la misma pregunta dos veces), se reutiliza el resultado anterior en lugar de llamar a su endpoint de nuevo. Los resultados en caché se mantienen hasta por 24 horas, y una llamada con entradas *diferentes* siempre se dirige a su endpoint de forma nueva.

**Máximo de ejecuciones por conversación.** Un límite estricto sobre cuántas veces puede ejecutarse la función dentro de una conversación. Establézcalo en 1 para funciones que solo deberían activarse una vez por chat: generar una cotización, activar una devolución de llamada, iniciar una automatización. Cuando se alcanza el límite, se le informa a la IA que la función ya se ejecutó y se le proporciona el resultado más reciente, por lo que aún puede responder al cliente en lugar de quedarse en silencio.

**Máximo de ejecuciones por ventana de tiempo.** Un límite de frecuencia a lo largo del tiempo: por ejemplo, como máximo 5 ejecuciones en 60 minutos. Útil para funciones que llaman a servicios de terceros de pago o activan automatizaciones más pesadas. Ambos cuadros deben completarse juntos (un número de ejecuciones y una ventana en minutos, hasta 7 días).

Un par de cosas que debe saber:

- Los límites cuentan solo las ejecuciones **exitosas**. Una llamada que falló en el lado de su endpoint no consume el presupuesto.
- Cuando una ejecución es bloqueada por un límite, el cliente nunca se queda esperando: se le informa a la IA el motivo y trabaja con la información que ya tiene.
- Los límites se aplican dondequiera que se ejecute la función: chats regulares en todos los canales y funciones gestionadas por una automatización. Las conversaciones de prueba en Probar no se cuentan ni se limitan.

---

## Herramientas integradas del bot

Además de las funciones personalizadas que tú mismo creas, la plataforma incluye una biblioteca de herramientas preconfiguradas que el bot de IA puede utilizar durante una conversación. Estas cubren las tareas más comunes que necesita realizar un bot (alertar a un compañero de equipo, reservar una cita, etiquetar a un contacto, buscar en tu sitio web, programar un seguimiento y más), por lo que no tienes que configurarlas desde cero.

**El bot decide cuándo usar cada herramienta** según lo que sucede en la conversación y cómo está configurado su agente (y su campaña vinculada). La mayoría de estas herramientas se activan automáticamente cuando se habilita la función relacionada (por ejemplo, las herramientas de reserva solo están disponibles una vez que conecta un calendario y habilita las reservas).

**Costo en créditos:** Cada llamada a una herramienta se factura según el nivel de Calidad de IA de su Agente, y las funciones personalizadas que usted mismo crea se facturan de la misma manera:

| Nivel de Calidad de IA | Créditos por llamada a herramienta | Con su propia clave de Anthropic (BYOK) conectada |
|---|---|---|
| Pro | 1 crédito | 0 créditos: se ejecuta con su clave |
| Economy (en desuso) | 0.5 créditos | 0 créditos: se ejecuta con su clave |
| Max | 0.25 créditos | sigue siendo 0.25 créditos, se factura incluso con su propia clave conectada, porque Max se ejecuta en nuestro propio modelo |
| Mini | 0.15 créditos | sigue siendo 0.15 créditos, se factura incluso con su propia clave conectada, porque Mini se ejecuta en nuestro propio modelo |

### Herramientas de equipo y tareas

| Herramienta | Qué hace | Cuándo la usa el bot |
|------|--------------|----------------------|
| **Alertar a un miembro del equipo** | Pausa el bot para este contacto y envía un correo electrónico a su equipo indicando que se necesita una persona. El chat se marca para que un compañero pueda atenderlo. | Cuando el cliente solicita una persona, está frustrado o pregunta algo que el bot no tiene permitido o no puede responder. |
| **Crear una tarea** | Crea una nueva tarea en su tablero de tareas, vinculada opcionalmente al contacto y la conversación. El bot sigue respondiendo normalmente; la tarea es solo una nota para que su equipo haga un seguimiento. | Para elementos no urgentes como una solicitud de función, una oportunidad de venta adicional o una devolución de llamada que el equipo deba manejar más tarde. |
| **Sugerir una actualización de preguntas frecuentes** | Cuando el bot encuentra una pregunta que no puede responder bien, crea una tarea pidiendo a su equipo que agregue una respuesta a la base de conocimientos. | Cuando un contacto pregunta algo que no está cubierto por sus preguntas frecuentes existentes, para que la brecha se solucione la próxima vez. |
| **Agregar contexto a una sugerencia de preguntas frecuentes** | Si otro contacto pregunta más tarde algo similar con un enfoque diferente, el bot agrega ese contexto a la sugerencia de preguntas frecuentes existente en lugar de crear una tarea duplicada. | Automático: mantiene su lista de tareas limpia cuando varias personas plantean la misma brecha de conocimiento. |

### Herramientas de contacto

| Herramienta | Qué hace | Cuándo la utiliza el bot |
|------|--------------|----------------------|
| **Etiquetado** | Se ejecuta automáticamente después de cada respuesta del bot; no es una herramienta que el bot de cara al cliente decida llamar. El sistema revisa la conversación reciente y aplica las etiquetas relevantes, reutilizando tus etiquetas existentes siempre que sea posible (y creando una nueva solo cuando sea necesario). | Automático: siempre que la conversación revele algo que valga la pena segmentar, como interés, intención, calidad del cliente potencial o idioma. |
| **Actualizar nombre de contacto** | Guarda el nombre y/o apellido del contacto cuando lo comparte. | Cuando el cliente se presenta o corrige un nombre. |
| **Actualizar correo electrónico de contacto** | Guarda la dirección de correo electrónico del contacto cuando la comparte. | Cuando el cliente proporciona un correo electrónico, para boletines, recibos, consultas de cuenta, etc. |

### Herramientas de citas y reservas

Estas herramientas solo están disponibles cuando las reservas están habilitadas en la campaña vinculada a su agente y se ha configurado un tipo de evento de calendario.

| Herramienta | Qué hace | Cuándo la usa el bot |
|------|--------------|----------------------|
| **Comprobar franjas horarias disponibles** | Busca qué horarios están libres en tu calendario conectado para una fecha o rango de fechas determinado. | Cuando el cliente quiere reservar y el bot necesita ofrecer disponibilidad real. |
| **Reservar una cita** | Crea la cita en tu calendario y confirma la reserva al cliente. | Después de que el cliente confirme una fecha y hora específicas. |
| **Mover una cita** | Reprograma una cita existente a una nueva fecha y hora. | Cuando el cliente solicita reprogramar. |
| **Cancelar una cita** | Cancela una cita existente. | Cuando el cliente solicita cancelar. |
| **Buscar citas** | Recupera las citas existentes de un contacto para que el bot sepa qué hay ya programado. | Cuando el cliente pregunta "¿cuándo es mi cita?" o antes de ofrecer reprogramar. |

### Herramientas de conocimiento y web

| Herramienta | Qué hace | Cuándo la usa el bot |
|------|--------------|----------------------|
| **Buscar en su sitio web** | Escanea las URL que ha añadido a la lista de URL dinámicas de la campaña para encontrar páginas de productos, artículos u otro contenido que responda a la pregunta del cliente. Disponible solo cuando la **Búsqueda web con IA** está activada y ha añadido al menos una URL dinámica. Si la Búsqueda web con IA está desactivada, el bot no puede leer páginas ni enlaces, ni siquiera los que el cliente pega en el chat. | Cuando el cliente pregunta sobre algo que probablemente esté en su sitio web: productos, precios, ubicaciones, políticas. |
| **Comprobar un enlace** | Lee el contenido de una URL específica para que el bot pueda responder preguntas sobre esa página. Disponible solo cuando la **Búsqueda web con IA** está activada y ha añadido al menos una URL dinámica. Si la Búsqueda web con IA está desactivada, el bot no puede leer páginas ni enlaces, ni siquiera los que el cliente pega en el chat. | Cuando el cliente comparte un enlace o pregunta sobre una página específica de su sitio. |
| **Buscar en la web** | Realiza una búsqueda pública en Google y devuelve los mejores resultados, para que el bot pueda responder preguntas fuera de su propio contenido. | Cuando el cliente pregunta sobre algo general (p. ej., direcciones, información pública) que no está en su base de conocimientos. Solo se utiliza si la búsqueda web está habilitada. |

### Herramientas de seguimiento

Estas herramientas requieren que los seguimientos estén habilitados en la campaña vinculada a su Agente.

| Herramienta | Qué hace | Cuándo la usa el bot |
|------|--------------|----------------------|
| **Programar un seguimiento inteligente** | Programa un mensaje de seguimiento inteligente utilizando su secuencia de seguimiento; elige la plantilla y el momento adecuados según la conversación. | Cuando el cliente se queda en silencio o le pide al bot que "vuelva a consultar más tarde". |
| **Programar un seguimiento** | Programa un seguimiento básico en un momento específico. | Cuando el bot necesita impulsar la conversación en un momento determinado. |

### Ejecutor de funciones personalizadas

| Herramienta | Qué hace | Cuándo la usa el bot |
|------|--------------|----------------------|
| **Ejecutar una función personalizada** | Ejecuta una de las funciones personalizadas que ha creado y asignado al Agente (consulte el resto de esta página). | Cuando la solicitud del cliente coincide con el propósito de una de sus funciones personalizadas. |

### Herramientas de reserva de restaurantes (Zenchef y Formitable)

Estas herramientas solo están disponibles cuando hay una integración con Zenchef o Formitable conectada. Permiten que el bot gestione las reservas de restaurantes de principio a fin.

| Herramienta | Qué hace | Cuándo la usa el bot |
|------|--------------|----------------------|
| **Comprobar disponibilidad del restaurante** | Busca franjas de reserva abiertas para una fecha, número de personas y (opcionalmente) zona de asientos determinada. | Cuando un cliente solicita reservar una mesa. |
| **Crear una reserva de restaurante** | Crea una nueva reserva. | Después de que el cliente confirme una franja específica. |
| **Actualizar una reserva de restaurante** | Cambia la fecha, hora, número de personas o notas de una reserva existente. | Cuando el cliente solicita modificar su reserva. |
| **Cancelar o cambiar el estado de la reserva** | Cancela una reserva o actualiza su estado (por ejemplo, confirmada, no presentado). | Cuando el cliente cancela, o cuando el bot necesita marcar un cambio de estado. |
| **Buscar reservas** | Encuentra reservas existentes que coincidan con criterios como nombre, correo electrónico o fecha. | Cuando un cliente recurrente pregunta sobre una reserva existente. |
| **Actualizar perfil del cliente** | Actualiza el perfil del cliente en el sistema del restaurante (preferencias, notas, información de contacto). | Cuando el cliente comparte preferencias dietéticas, un nuevo número de teléfono u otra información a nivel de perfil. |
| **Listar productos del restaurante** | Obtiene la lista de menús, menús cerrados o complementos disponibles para reservar. | Cuando el cliente pregunta "¿qué menús cerrados tienen?" o el bot necesita adjuntar un menú a una reserva. |

### Activación y desactivación de herramientas

La mayoría de las herramientas se controlan en la pestaña **Habilidades de IA** del Agente (o en el paso **Habilidades de IA** de la campaña, si está trabajando desde una campaña aún clásica):

- Las **herramientas de reserva** se activan cuando habilita las reservas y conecta un calendario; esto sigue siendo una configuración por campaña por ahora, con un enlace directo al paso de esa campaña desde la propia pestaña Habilidades de IA del Agente
- Las **herramientas de seguimiento** se activan cuando habilita los seguimientos
- Las **herramientas para restaurantes** se activan cuando conecta una cuenta de Zenchef o Formitable
- La **búsqueda web** tiene su propio interruptor en la pestaña **Preguntas frecuentes y conocimientos**
- Las **herramientas de tareas** se pueden desactivar por Agente con el interruptor **Permitir que la IA cree tareas** (están activadas de forma predeterminada; el interruptor de Tareas para toda la cuenta en **Configuración → Perfil → Funciones** desactiva todo el sistema de tareas en todas partes)
- Las **herramientas de actualización de contactos** se controlan en la misma pestaña **Habilidades de IA**: si la IA puede cambiar el nombre de los contactos o guardar información adicional recopilada sobre ellos
- Las **herramientas de alerta** están siempre disponibles; el **etiquetado** se ejecuta automáticamente después de cada respuesta del bot (no es una herramienta que el bot elija llamar)

Si desea que el bot deje de usar una herramienta integrada específica, la forma más limpia es deshabilitar la función subyacente (por ejemplo, desactive las reservas para deshabilitar todas las herramientas de reserva).

---

## Funciones gestionadas por una automatización

Algunas entradas en su página de Funciones personalizadas pueden llevar una insignia de **Gestionada por automatización**. Estas no se crearon aquí; provienen de una automatización con un activador de **Función de agente de IA**, que le otorga a su agente una capacidad cuyos pasos usted construye visualmente en el lienzo de automatización en lugar de apuntar a una dirección web externa.

Una función gestionada se mantiene por usted: su nombre, descripción y campos siempre siguen lo establecido en el activador de la automatización, por lo que no se puede editar ni eliminar desde esta página; utilice su enlace **Abrir automatización** y cambie la automatización en sí. No obstante, puede seguir eligiendo qué agentes la tienen de la forma habitual: en la pestaña **Habilidades de IA** de un agente, aparece junto a las otras habilidades del agente con un interruptor de encendido/apagado normal (si su automatización está en pausa, la fila lo indica; la habilidad se activa cuando se enciende la automatización). Todo lo demás se comporta como cualquier otra función personalizada: la IA decide cuándo llamarla, recopila los detalles que usted definió y puede utilizar la respuesta de la automatización en la misma conversación.

Si está decidiendo entre ambas opciones: apunte una función personalizada normal a un sistema que ya tenga una dirección a la que llamar; cree una automatización con un activador de Función de Agente de IA cuando el trabajo sea algo que prefiera ensamblar a partir de pasos (buscar algo en una hoja de cálculo o base de datos, ramificar según una condición, crear registros) sin tener que ejecutar su propio servidor. Consulte [Automatizaciones](../automations/automations.md#letting-your-ai-agent-call-an-automation).

---

## Requisitos del plan

Las funciones personalizadas están disponibles en los planes que incluyen la característica de funciones personalizadas. Consulta tu suscripción para confirmar la disponibilidad.

---

## Próximos pasos

- [Conectar servidores MCP a su bot](mcp-servers.md): un paquete de herramientas listo para usar en lugar de una función a la vez.
- [Agentes de IA](../ai-agents/ai-agents.md): la página principal del grupo de AI Studio donde residen las Funciones personalizadas y donde se asignan las funciones personalizadas a un bot.