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.

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:

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:

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 #

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:

Qué método elegir:

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:

Los valores de los encabezados que contienen una clave o contraseña, como Authorization o X-API-Key, se muestran como puntos una vez escritos. Haga clic en el ojo junto al valor para verlo.

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:

Tipos de parámetros disponibles:

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:

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

Cuando una comprobación de seguimiento llama a su función (consulte Enviar solo cuando una comprobación sea correcta), la solicitud es diferente de una llamada dentro de una conversación: no tiene parámetros de entrada y el campo system solo contiene system.contact (con su id) además de un bloque system.follow_up (type, cycle_number, follow_up_number, reason, campaign_id, agent_id). No contiene ningún objeto campaign. Omitir datos del sistema también se aplica a esa llamada.

¿No necesitas los datos del sistema? Activa el interruptor Omitir datos del sistema en el generador de funciones. El bot enviará solo los parámetros de entrada que definiste, sin datos de contacto ni del agente. Úsalo si tu endpoint rechaza campos inesperados o si simplemente deseas 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. Abre el Agente en AI Studio → AI Agents.
2. Ve a su pestaña AI Abilities.
3. Verás una lista de todas las funciones personalizadas que has creado. Activa cada función que quieras que el bot de este agente pueda llamar.
4. Haz clic en Save changes 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 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, por ejemplo debido a credenciales incorrectas, un endpoint que no funciona o un 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 Try Out del agente como en las conversaciones reales en Chats. Haz clic en el marcador para ver los detalles: el código de estado que devolvió tu endpoint y su cuerpo de respuesta, lo cual suele ser suficiente para saber exactamente qué corregir (un 401 con un mensaje de “no autorizado” significa que el encabezado de autenticación es incorrecto, un tiempo de espera agotado significa que tu endpoint tardó más de 30 segundos; para un trabajo que requiere más tiempo, consulta Trabajos de larga duración).

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.

Cuando una herramienta sigue fallando en conversaciones reales #

Si la misma función personalizada falla 3 veces en un periodo de 24 horas mientras tu agente de IA está chateando, recibirás una alerta al día: por correo electrónico, en la campana de notificaciones y como notificación push si la has activado. La alerta indica el nombre de la herramienta, muestra el último error y enlaza a los chats afectados, ya que el agente habrá informado a esos contactos de que ha encontrado un problema técnico. La fila de la función en Ajustes muestra una línea de Error con el recuento de errores y el último error hasta que la herramienta vuelva a funcionar; una llamada exitosa lo borrará. Puedes desactivar estas alertas en Ajustes → Notificaciones → Errores de herramientas.

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).

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, 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 Your AI Connector. 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). Esta es la razón más común por la que una función correctamente construida nunca se dispara.

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. Si su firewall necesita una lista de permitidos de IP, cada llamada a función personalizada (y cada comprobación de seguimiento) se envía desde una dirección IPv4 fija, la misma que utilizan nuestros webhooks; sin rangos, sin IPv6, sin rotación. Póngase en contacto con el soporte técnico y le facilitaremos la dirección. Active la firma de solicitudes y verifique la firma como su comprobación de confianza real, y trate la IP como un filtro adicional.

9. Utilice una URL pública final. La URL de su función debe ser una dirección web pública (HTTP/HTTPS). Las direcciones internas, de localhost y de redes privadas se rechazan por seguridad, y la plataforma no sigue redirecciones: apunte la función directamente a la URL final, no a una que redirija a ella.

Trabajos de larga duración: obtener el resultado más tarde #

Normalmente, una función personalizada debe responder en un plazo de 30 segundos, mientras el contacto espera la respuesta. Algunos trabajos tardan más: renderizar un vídeo, realizar una verificación de crédito, esperar a que una persona de tu equipo apruebe algo. Para estos casos, activa El resultado llega más tarde (larga duración). La llamada de la IA solo inicia el trabajo. Tu servicio responde de inmediato, la IA le comunica al contacto que el resultado está en camino y continúa con la conversación, y tu servicio envía el resultado a un enlace de callback cuando termina.

Cuándo utilizarlo #

Utilízalo cuando tu servicio no pueda responder de forma fiable en menos de 30 segundos. Déjalo desactivado para consultas rápidas (estado de un pedido, comprobación de existencias, precio): son más sencillas como una llamada normal, ya que la IA responde con el resultado en la misma respuesta.

La configuración en el editor #

Encontrarás esto en el editor de funciones personalizadas, junto a Omitir datos del sistema.

Qué recibe tu servicio #

Con el interruptor activado, cada llamada lleva el enlace de callback en tres lugares, además de todo lo descrito anteriormente (tus parámetros de entrada, el bloque system y los encabezados de firma):

El enlace es único para cada llamada, pertenece a ese contacto y a esa llamada, funciona una sola vez y caduca después de Esperar hasta. No necesitas una clave API para usarlo: el enlace en sí es el permiso. Trátalo como una contraseña y nunca lo escribas en un registro público.

Envío del resultado #

Cuando el trabajo haya terminado, envía un POST al enlace de callback:

POST https://api.<your host>/v1/custom-functions/callback/d3f9...
Content-Type: application/json

{
  "result": { "video_url": "https://cdn.example.com/spring-offer.mp4", "duration_seconds": 42 },
  "message": "Your video is ready: https://cdn.example.com/spring-offer.mp4"
}

• result es lo que lee la IA. Puede ser texto o un objeto JSON.
• message es opcional. Con Enviar el texto tal cual, el contacto recibe message cuando envías uno; de lo contrario, recibe result cuando es texto.
• media_url es opcional: un enlace https a un archivo (imagen, vídeo, audio o documento) que el contacto recibe como un archivo adjunto real, no como un enlace. Consulta Enviar un archivo a continuación.
• También puedes enviar un cuerpo de texto sin formato con Content-Type: text/plain. Se trata como result.
• El cuerpo puede tener hasta 64 KB.

Lo que responde el enlace de callback:

Un ejemplo completo: un vídeo que tarda tres minutos #

1. La IA llama a tu función. Recibes (abreviado):

POST https://api.example.com/render
X-Callback-Url: https://api.<your host>/v1/custom-functions/callback/d3f9...
Content-Type: application/json

{
  "video_title": "Spring offer",
  "callback_url": "https://api.<your host>/v1/custom-functions/callback/d3f9...",
  "system": {
    "contactId": "...",
    "callback_url": "https://api.<your host>/v1/custom-functions/callback/d3f9...",
    "callback_expires_at": "2026-10-20T19:15:00.000Z"
  }
}

2. Tu servicio inicia el renderizado y responde inmediatamente:

{ "status": "started" }

3. La IA le dice al contacto que el vídeo se está creando y continúa chateando.
4. Tres minutos después, tu servicio publica el resultado en el enlace de callback:

{ "result": { "video_url": "https://cdn.example.com/spring-offer.mp4", "duration_seconds": 42 } }

5. La IA escribe el siguiente mensaje con sus propias palabras, por ejemplo “Tu vídeo está listo: https://cdn.example.com/spring-offer.mp4”.

¿Usas Zapier o Make? Deja que el webhook del disparador reciba la llamada y haz que el último paso del flujo sea un POST a callback_url con los datos del disparador.

Qué sucede en el chat #

El resultado se guarda en la conversación como una entrada de función, por lo que lo verás en la bandeja de entrada como cualquier otra llamada de función personalizada. Luego, dependiendo de Cuando llega el resultado, la IA escribe y envía el siguiente mensaje (esto cuesta una respuesta de la IA, como cualquier mensaje de IA), o tu texto se envía tal cual. Con Enviar el texto tal cual, se envía el campo message cuando incluyes uno; de lo contrario, se envía result cuando es texto plano. Si solo publicas un objeto sin texto, la IA escribe el mensaje en su lugar.

Si la IA está desactivada para ese contacto cuando llega el resultado (un miembro del equipo tomó el control, la IA estaba en pausa, el agente está desconectado o sin créditos), el resultado se guarda en la conversación, pero no se envía ningún mensaje. Tampoco se envía más tarde cuando la IA se vuelve a activar. El miembro del equipo ve el resultado en el chat y puede utilizarlo.

En la pestaña Probar del agente, todo el flujo también funciona: el resultado llega al chat de prueba.

Enviar un archivo (vídeo, imagen, PDF) #

Un resultado que es un archivo, por ejemplo, un vídeo que tu servicio generó en segundo plano, llega al contacto como un archivo adjunto que puede abrir en el chat, en ambos modos. La plataforma encuentra el archivo en tu callback de la siguiente manera:

1. media_url en el cuerpo, cuando envías uno.
2. De lo contrario, un campo de archivo en el objeto result: file_url, video_url, image_url, pdf_url, document_url, audio_url, attachment_url o download_url.
3. De lo contrario, el primer enlace https en el texto que termina en una extensión de archivo como .mp4, .jpg, .png o .pdf.

Con La IA escribe el siguiente mensaje, la IA escribe el texto y el archivo se adjunta a ese mensaje (se le indica a la IA que no pegue el enlace). Con Enviar el texto tal cual, tu message es el pie de foto del archivo adjunto.

{
  "result": { "status": "done", "title": "Spring offer" },
  "message": "Your video is ready.",
  "media_url": "https://cdn.example.com/spring-offer.mp4"
}

Los archivos pueden tener hasta 16 MB y deben ser accesibles a través de https. Cada canal admite diferentes tipos: por ejemplo, el correo electrónico y los canales de WhatsApp admiten vídeo, imágenes, audio y documentos; los SMS no admiten archivos. Cuando un canal no puede recibir el archivo, o el archivo es demasiado grande, el contacto recibe el mensaje de todos modos, con el enlace al archivo añadido al final.

Cuando el resultado nunca llega #

Si no se publica nada antes de que se agote el tiempo de Esperar hasta, se le informa a la IA que el resultado nunca llegó, para que pueda avisar al contacto. Aparece una entrada con el código APP-3103 en Configuración → Registro de errores y recibirás una notificación de error de herramienta.

Límites de un vistazo #

• Un resultado por enlace de callback. Las publicaciones posteriores al mismo enlace se responden como duplicados y no cambian nada.
• Hasta 64 KB por resultado.
• Un archivo por resultado, hasta 16 MB, a través de https.
• Hasta 20 publicaciones por minuto a un enlace.
• Esperar hasta de 1 a 168 horas.
• Tu servicio sigue teniendo 30 segundos para responder a la primera llamada.

Verificación de que una llamada proviene realmente de nosotros #

Cualquiera que conozca la URL de su función podría enviarle una solicitud falsa. Un secreto largo en un encabezado de autenticación ayuda, pero es el mismo valor en cada llamada, por lo que cualquiera que vea una solicitud (en un registro o una captura de pantalla) puede reutilizarlo. La firma de solicitudes soluciona esto: cada llamada lleva una firma que solo alguien que posea su secreto puede producir, y que caduca después de unos minutos.

La firma es opcional y está desactivada de forma predeterminada, y es una configuración para toda su cuenta: un único secreto firma cada función personalizada.

Activación de la firma #

1. Abra Funciones personalizadas.
2. Debajo de su lista de funciones, busque la tarjeta Firma de solicitudes y haga clic en Activar firma.
3. Haga clic en Mostrar, copie el secreto (comienza con whsec_) y guárdelo en el sistema que recibe las llamadas. Trátelo como una contraseña.

Desde la misma tarjeta puede volver a copiar el secreto, Rotarlo (el anterior deja de funcionar inmediatamente) o Desactivar la firma.

Lo que enviamos #

Una vez activada la firma, cada llamada que realiza una función personalizada lleva dos encabezados adicionales: las llamadas de la IA durante un chat, las condiciones de envío de seguimiento y el botón Ejecutar prueba en el editor.

Cada llamada, firmada o no, también lleva User-Agent: Custom-Function/1.0 a menos que establezca su propio encabezado User-Agent.

Los encabezados y la firma funcionan exactamente igual que los webhooks firmados, por lo que si ya verifica nuestros webhooks, el mismo código funciona aquí. Solo el secreto es diferente.

Cómo verificar #

La firma es un HMAC-SHA256 de la cadena <timestamp>.<raw request body>, utilizando su secreto de firma como clave. Compruébela con el cuerpo sin procesar (raw), los bytes exactos que recibió: analizar el JSON y volver a convertirlo en texto puede cambiar los bytes, y la firma no coincidirá.

Una función que utiliza GET (o un POST sin nada que enviar) no tiene cuerpo, por lo que la cadena firmada es simplemente <timestamp>. con un cuerpo vacío. La firma entonces demuestra que la llamada proviene de nosotros y es reciente, pero no cubre la cadena de consulta.

Ejemplo en Node.js:

const crypto = require("crypto");

function verify(rawBody, headers, secret) {
  const timestamp = headers["x-webhook-timestamp"];
  const signature = headers["x-webhook-signature"] || ""; // "v1=<hex>"

  // Reject anything older than 5 minutes so a captured request can't be replayed later.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const received = signature.replace("v1=", "");

  return received.length === expected.length && crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}

Ejemplo en Python:

import hashlib, hmac, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers.get("X-Webhook-Timestamp", "")
    signature = headers.get("X-Webhook-Signature", "").replace("v1=", "")
    if not timestamp or abs(time.time() - int(timestamp)) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, expected)

Pruébelo con Ejecutar prueba en el editor: una vez activada la firma, la llamada de prueba se firma exactamente igual que una real, por lo que una función que pase la prueba también pasará su comprobación durante los chats reales.

¿Utiliza la API? El mismo secreto se puede leer, generar, rotar y eliminar con GET, POST y DELETE en /v1/custom-functions/signing-secret.

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. Actívela si su función solo lee datos (una consulta 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 reintentar el turno de la conversación de forma segura en lugar de dejar al cliente sin respuesta. Solo actívela 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 por accidente. Las funciones que utilizan el método GET se tratan automáticamente como de solo lectura, ya que las solicitudes GET están destinadas únicamente a obtener datos; las funciones POST, PUT, PATCH y DELETE necesitan el interruptor.

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).

Envío de ofertas, contratos o facturas en LinkedIn. Cuando la IA responde en LinkedIn, lo hace desde la propia bandeja de entrada del propietario de la cuenta, por lo que no debe enviar una oferta, contrato, presupuesto, factura, enlace de pago o acceso en nombre del propietario a menos que este lo haya indicado. Con Automático (la opción predeterminada), una función cuyo nombre o descripción indique que envía uno de estos elementos no se ejecutará en LinkedIn: se le informa a la IA que no se envió nada y se le comunica a la persona que el propietario se encargará de ello. Elija Permitido para permitir que la función se ejecute en LinkedIn de todos modos, o Nunca en LinkedIn para restringir una función que la verificación automática pasaría por alto. Otros canales no se ven afectados y, a diferencia de los límites anteriores, esta configuración también se aplica en Probar. 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 tu agente. 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 conectas un calendario y habilitas 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:

Herramientas de equipo y tareas #

Herramientas de contacto #

Herramientas de citas y reservas #

Estas herramientas solo están disponibles cuando las reservas están habilitadas en tu agente y se ha configurado un tipo de evento de calendario.

Herramientas de conocimiento y web #

Herramientas de seguimiento #

Estas herramientas requieren que los seguimientos (follow-ups) estén habilitados en tu agente.

Ejecutor de 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.

Activación y desactivación de herramientas #

La mayoría de las herramientas se controlan en la pestaña AI Abilities del agente:

• Las herramientas de reserva se activan cuando habilitas las reservas y conectas un calendario, en la tarjeta Bookings en la misma pestaña AI Abilities
• Las herramientas de seguimiento se activan cuando habilitas los seguimientos
• Las herramientas de restaurante se activan cuando conectas una cuenta de Zenchef o Formitable
• La búsqueda web tiene su propio interruptor en la pestaña FAQs & Knowledge
• Las herramientas de tareas se pueden desactivar por agente con el interruptor Allow AI to create tasks (están activadas de forma predeterminada; el interruptor de tareas para toda la cuenta en Settings → Profile → Features desactiva todo el sistema de tareas en todas partes)
• Las herramientas de actualización de contactos se controlan en la misma pestaña AI Abilities, ya sea que la IA pueda renombrar 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.

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: un paquete de herramientas listo para usar en lugar de una función a la vez.
• Agentes de IA: la página principal del grupo de AI Studio donde residen las Funciones personalizadas y donde se asignan las funciones personalizadas a un bot.