Acciones

Define lo que tu Agente de IA puede hacer durante la conversación: desde responder con datos de API en tiempo real y recopilar leads hasta ejecutar tareas personalizadas.

Los Agentes de Quickchat AI tienen dos tipos de acción.

Las Quickchat AI Actions vienen integradas, así que solo tiene que activarlas y configurarlas:

• Human Handoff pasa la conversación a una persona.
• Recopilación inteligente de datos recoge leads y otra información durante el chat.

Las acciones personalizadas salen fuera de Quickchat AI:

• Las acciones API llaman a cualquier endpoint HTTP. Se explican en esta página.
• Las acciones MCP conectan un servidor MCP entero de una vez.
• Google Sheets es un atajo que configura una acción de registro por usted con un clic.

Cualquier acción puede leer datos en vivo de la conversación mediante AI Action Variables, y el ejemplo de Jira construye una de principio a fin.

Acciones personalizadas

Permiten que tu IA llame APIs externas durante el chat. Úsalas para buscar en herramientas internas, crear tickets, disparar alertas o traer datos actualizados fuera de la Base de Conocimiento. Están en Actions & MCPs → Custom Actions.

Cómo funcionan

1. Elige un tipo de acción: Acción API, MCP, Acción HubSpot, Acción de Discord, Google Sheets o Shopify MCP. Configura la conexión y las instrucciones que necesita la IA.
2. Durante un chat, la IA normalmente usa la descripción de la acción y los detalles disponibles de la herramienta o los parámetros para decidir cuándo ejecutarla. Como alternativa, una Acción de API puede configurarse para ejecutarse automáticamente antes de la primera respuesta.
3. Quickchat ejecuta la llamada y devuelve el resultado a la IA. La IA lee la respuesta y contesta al usuario en lenguaje natural.
4. Prueba o conecta la acción desde su editor antes de usarla en conversaciones.

Consejo

Escribe la descripción como una instrucción para la IA: cuándo usarla, qué devuelve y límites.

Crear una Acción de API

1. Abre Actions & MCPs.
2. Haz clic en + en Custom Actions y elige API Action.
3. Completa Details:
   • Name: claro y descriptivo
   • Description: cuándo usarla y qué incluir en parámetros
4. En Cuándo ejecutar, elige La IA decide o Antes de la primera respuesta.
5. Configura Connection:
   • Action Type: GET o POST
   • Action endpoint URL: URL completa
   • Headers: cabeceras necesarias (Authorization, content-type: application/json, etc.)
6. Define Parameters: para cada parámetro, name, location (query, body o header) y description guiando a la IA sobre cómo componer el valor. Los valores de ruta (path) no son una location de parámetro; insértalos directamente en la URL del endpoint mediante plantillas {{placeholder}}.
7. Test request, verifica y Done.

Más allá de la petición en sí, una API Action tiene tres ajustes opcionales que conviene conocer: Guardar en memoria, Ejecutar solo cuando y Response filter.

Elegir cuándo se ejecuta una Acción de API

Usa Cuándo ejecutar para seleccionar uno de estos dos modos:

• La IA decide: es el modo predeterminado. La IA lee la descripción de la Action y decide si necesita ejecutarla para responder a la petición del visitante. Úsalo cuando la Action solo deba ejecutarse para determinadas preguntas o después de que la IA recopile información del visitante.
• Antes de la primera respuesta: Quickchat ejecuta la Action una vez después de que el visitante envíe su primer mensaje y antes de que la IA escriba su primera respuesta. La respuesta normal de la IA recibe la respuesta de la API y cualquier valor guardado con Guardar en memoria. La IA ya no puede elegir esta Action como herramienta, así que solo se ejecuta en el primer turno y no de nuevo más adelante en la conversación. Úsalo para identificar al cliente, consultar el contexto de su cuenta, comprobar sus permisos u obtener otros datos iniciales que necesite toda conversación real.

Antes de la primera respuesta está vinculado al primer mensaje del visitante, no a la creación de la conversación. Abrir un chat o recibir un mensaje de bienvenida no lo ejecuta, por lo que los chats abandonados no generan ninguna solicitud. Quickchat registra la ejecución antes de llamar al endpoint, así que no se vuelve a intentar en la misma conversación aunque falle la solicitud o su resultado sea incierto.

La primera respuesta espera a que termine la solicitud, por lo que este modo puede añadir latencia. Si varias Actions usan este modo, se ejecutan una tras otra y sus tiempos de solicitud se acumulan. Si faltan metadatos obligatorios, el endpoint no está disponible o falla una solicitud, la IA responde igualmente. Abre Registro de solicitudes en la Action para ver qué ocurrió.

Como la Action se ejecuta antes de que la IA pueda elegir los valores de los parámetros, cada parámetro de IA que utilice debe tener un valor predeterminado. Los metadatos y las variables integradas pueden insertarse directamente en la URL, las cabeceras, la consulta o el cuerpo.

Identificar por email o teléfono

En los canales que pueden proporcionar un email o un número de teléfono, crea una Action de búsqueda para cada identificador. Configura ambas como Antes de la primera respuesta y añade una condición de Ejecutar solo cuando correspondiente, como visitor_email exists o visitor_phone_number exists. Quickchat solo envía la solicitud cuyo metadato está presente.

Acciones de Discord

Acción Discord abre una galería de Acciones de API preconfiguradas y editables:

• Soporte y tickets: Abrir ticket de soporte te pide que selecciones un servidor y un canal de texto. Opcionalmente, puedes seleccionar un rol de soporte mencionable. Crea tres Actions que abren un hilo privado, añaden al solicitante actual y publican un resumen con la mención opcional del rol.
• Moderación: Timeout de miembro, Expulsar miembro, Banear miembro, Quitar baneo, Asignar rol, Configurar slowmode y Enviar anuncio. Cada plantilla se instala con un clic y utiliza el servidor, miembro, rol o canal de la petición actual de Discord.

Quickchat crea en el backend el método HTTP, la URL, las cabeceras, el cuerpo, los parámetros, la descripción, los ajustes de respuesta y las condiciones de ejecución. Las tarjetas resultantes son Actions normales de petición HTTP. Puedes revisar y editar todos los campos.

Las siete plantillas de moderación incluyen author_is_admin is true en Ejecutar solo cuando. Discord calcula el permiso Administrator del autor actual, el gateway de Discord proporciona ese valor y Quickchat lo comprueba antes de enviar la petición. El chat público y los metadatos de la API no pueden establecer esta clave. Prueba las Actions de moderación en Discord con una cuenta de administrador y otra que no lo sea; AI Preview no proporciona un remitente autorizado de Discord.

Precaución

Las Actions de moderación son editables. Eliminar o debilitar la condición author_is_admin is true elimina la barrera de autorización proporcionada. Expulsar miembro y Banear miembro no piden confirmación antes de ejecutarse.

El bot también necesita el permiso de Discord correspondiente a cada petición:

Acción	Permiso o acceso del bot
Timeout de miembro	Moderate Members
Expulsar miembro	Kick Members
Banear miembro, Quitar baneo	Ban Members
Asignar rol	Manage Roles
Configurar slowmode	Manage Channels
Enviar anuncio	View Channels y Send Messages

Discord también aplica la jerarquía de roles. Coloca el rol del bot por encima de los miembros y roles que deba administrar. La plantilla no realiza una comprobación adicional de jerarquía ni de permisos concretos para el administrador que hace la petición.

Configurar slowmode y Enviar anuncio aceptan un parámetro de ID de canal. Sin un destino fijo adicional, la plantilla no verifica que el canal pertenezca al servidor desde el que el administrador envió la petición. Si el mismo bot pertenece a varios servidores, edita estas Actions para usar un ID de canal fijo o separa los servidores entre distintos Agents y credenciales de bot.

La instalación de Soporte y tickets utiliza las funciones existentes de las Actions para transferir los datos:

1. open_support_ticket crea un hilo privado en el canal seleccionado, captura $.id y lo guarda en la memoria de la conversación como discord_ticket_thread_id. Requiere discord_message is true, solo se ejecuta en el servidor seleccionado y solo se ejecuta mientras esa clave de memoria no exista.
2. add_ticket_requester lee {{metadata_discord_ticket_thread_id}} y el valor {{metadata_discord_author_id}} que proporciona Discord. Requiere discord_message is true y solo se ejecuta en el servidor seleccionado después de que exista el ID del hilo.
3. post_in_ticket lee el mismo ID del hilo guardado, publica el resumen de una línea del Agent sobre el problema y menciona al solicitante. Si seleccionaste un rol de soporte, también lo menciona. Tiene las mismas condiciones de mensaje de Discord, servidor e hilo guardado. Su cuerpo allowed_mentions de Discord se limita al solicitante y, si se ha configurado, a ese rol.

Las descripciones y el prompt de tu Agent deben indicarle que ejecute esas Actions en ese orden. No hay ninguna capa independiente de estado del flujo, bloqueo, confirmación, reintento, recuperación, conciliación ni protección frente a repeticiones. Si el resultado es incierto, revisa Discord y el registro de la Action antes de reintentarlo, porque Discord podría haber completado ya la petición.

discord_ticket_thread_id no se borra automáticamente. Por tanto, la plantilla admite un ticket por conversación de Quickchat. Inicia una nueva conversación o hilo de Discord para otro ticket, o edita las Actions para añadir el ciclo de vida de memoria que necesites.

Para Soporte y tickets, concede al bot View Channels, Send Messages, Read Message History, Create Private Threads, Send Messages in Threads y Manage Threads en el canal de tickets seleccionado. Deja Avisar a un rol (opcional) configurado como No avisar a ningún rol si no debe mencionarse ningún rol. Si seleccionas un rol, debe ser mencionable y sus miembros necesitan acceso a los hilos privados. Si no hay roles mencionables disponibles, los tickets se siguen abriendo con normalidad sin avisar a ningún rol. La galería muestra canales de texto y roles mencionables, pero no valida todas las sobrescrituras de permisos del canal.

Precaución

Las Actions de Discord necesitan el token de tu propia app de Discord en Aplicaciones externas → Discord → Configuración avanzada. El bot compartido de un clic no puede proporcionar ese token por sí solo. Consulta Discord.

La galería es un atajo de configuración, no una capa de políticas adicional. Si editas una Action generada o creas una Acción de API personalizada para Discord, revisa sus credenciales, destinos, parámetros, exposición de la respuesta y condiciones de Ejecutar solo cuando antes de activarla.

Guardar en memoria

Captura un valor de la respuesta de la API y guárdalo en la memoria de la conversación bajo una clave que tú elijas. Acciones posteriores pueden reutilizarlo como {{metadata_<key>}}, y aparece en los detalles de la conversación (Inbox, la API y las exportaciones).

Recurre a esto cuando una Action produce algo que una Action posterior necesita. Una Action de búsqueda puede guardar un customer_id de su respuesta; una Action de seguimiento envía después {{metadata_customer_id}} sin que la IA tenga que copiar el valor de una a otra.

En la sección Guardar en memoria del editor de la API Action, asigna a la valor capturado una memory key y apúntala a la parte de la respuesta que quieras conservar. A partir de ahí es una variable de metadatos como cualquier otra.

Las memory keys se comparten con las herramientas Remote MCP del agente. Si una herramienta MCP ya guarda en la misma clave, el campo memory key avisa del conflicto al guardar, así que elige otra clave.

Consejo

Usa claves en snake_case (letras, dígitos, guiones bajos). Una clave como customer_id se puede referenciar como {{metadata_customer_id}}; las claves con espacios u otra puntuación no pueden usarse en marcadores. Consulta Metadatos de conversación para saber cómo funcionan las variables de metadatos.

Ejecutar solo cuando

Restringe una Action para que se ejecute solo cuando se cumplen condiciones sobre los metadatos de la conversación. Las condiciones se comprueban de nuestro lado, en el momento de la llamada, después de que la IA haya decidido llamar a la Action pero antes de enviar ninguna petición, de modo que no se pueden sortear desde el chat.

Esta es la herramienta adecuada para Actions privilegiadas o irreversibles (banear a un miembro, emitir un reembolso, eliminar un registro). Una línea en tu prompt que diga “solo los administradores pueden hacer esto” es una instrucción útil, pero no es una barrera de seguridad: un usuario decidido puede discutir con el modelo o intentar una inyección de prompt. Una condición de ejecución es determinista y vive fuera del prompt, así que se mantiene independientemente de lo que diga la conversación.

• La condición de ejecución es la barrera. Se evalúa del lado del servidor y no forma parte del prompt que lee el modelo. Esto es lo que realmente impide que la Action se ejecute.
• La regla del prompt es la experiencia de usuario. Mantén también una línea en tu prompt, para que la IA rechace con educación y explique por qué en lugar de quedarse en silencio.

Añade condiciones en la sección Ejecutar solo cuando del editor de la Action. Haz clic en Add condition, elige una clave de metadatos (por ejemplo telegram_sender_is_admin) y elige cómo compararla:

Condición	Pasa cuando el valor del metadato…
is true	es truthy
is false	es falsy
exists	está presente en la conversación
does not exist	está ausente
equals	coincide con un valor que especifiques
does not equal	difiere de un valor que especifiques

La Action se ejecuta solo cuando todas las condiciones se cumplen. Una condición sobre una clave que no está establecida en la conversación no pasa.

Cuando una condición falla, no se envía ninguna petición y la IA le dice al usuario que no puede hacer eso. Abajo, la misma petición de baneo se bloquea para un no-administrador y se permite para un administrador, sin cambiar nada salvo quién lo pide:

Precaución

Aplica condiciones solo sobre metadatos que Quickchat establece (como un flag telegram_sender_is_admin verificado por el canal), no sobre valores que el visitante pueda influir. Consulta Metadatos de conversación para saber de dónde viene cada clave.

Response filter

Por defecto, la IA ve la respuesta completa de la API. Añade expresiones JSONPath en la sección Response filter para limitar la IA a partes específicas de ella.

Dos motivos habituales para filtrar:

• Ocultar campos sensibles. Mantén los correos de los clientes, los datos de pago o los ids internos fuera del contexto del modelo cuando el endpoint devuelve más de lo que la IA necesita.
• Reducir el prompt. Las APIs muy verbosas pueden devolver payloads grandes; filtrar a los pocos campos que importan mantiene la respuesta pequeña y la IA enfocada.

Añade una o más expresiones JSONPath y la IA recibirá solo las partes que coincidan. Por ejemplo, $.data.items[*].name conserva solo los nombres de los elementos de una respuesta más grande.

Consejo

Usa el panel Test Response para ver exactamente qué recibirá la IA tras el filtrado antes de confiar en él. Consulta Probar tu Action.

Precaución

Un JSONPath que no coincide con nada deja a la IA con una respuesta vacía. Empieza sin filtro, confirma que la llamada funciona y luego ajústalo.

Buenas prácticas

• Sé explícito: cuándo usar y cómo completar parámetros.
• Alcance mínimo: solo cabeceras y tokens necesarios.
• Prueba antes del despliegue: revisa códigos y payloads.

Tutoriales

• Buscar tickets de Jira en una conversación de IA
• Enviar una notificación de Slack con una Acción de IA