Variables de AI Actions

En cualquier campo donde puedas escribir un valor en una API Action (URL, headers, body o query parameters) puedes inyectar valores dinámicos con la sintaxis {{...}}. Quickchat sustituye estos marcadores en el momento de la petición, justo antes de llamar a tu endpoint.

Haz clic en el botón + Add AI Data junto a cualquier campo de valor para explorar todas las variables disponibles en el escenario actual.

El botón + Add AI Data está disponible junto a cada campo de valor: la URL del endpoint, el valor de cada header, los campos del body y los query parameters.

Tres categorías de variables

Categoría	Sintaxis	Cuándo se rellena
Parámetros de IA. Valores que tu Agente de IA extrae de la conversación. Los defines en la sección Parameters de cada Action.	{{order_number}}, {{customer_email}}	El Agente de IA los rellena en el momento de la llamada, según las reglas que escribas en la descripción de cada parámetro.
Variables integradas. Contexto de la conversación que Quickchat inyecta automáticamente.	{{scenario_id}}, {{conversation_id}}, {{language}}, {{country}}, …	Siempre disponibles. Quickchat las sustituye en cada petición.
Metadatos de conversación. Pares clave-valor personalizados asociados a la conversación.	{{metadata_<key>}}	Cuando la clave correspondiente existe en la conversación (establecida por el widget, una integración de canal, Smart Data Gathering o la API).

Consejo

Cada variable se muestra como un pill de color dentro del editor. Azul significa que es un parámetro de IA o una variable integrada. Naranja significa que es una variable de metadatos o un system token. Rojo significa que el nombre no coincide con nada que Quickchat conozca (normalmente un error de tipeo).

El dropdown ”+ Add AI Data”

El dropdown lista todas las variables disponibles para el escenario actual, agrupadas en cinco secciones:

1. Parameters: los parámetros de IA que definiste en esta Action.
2. Visitor: cuatro claves de metadatos auto-capturadas para cada visitante, cuando su canal las proporciona.
3. Metadata (used in recent conversations): claves de metadatos personalizadas vistas en las últimas 20 conversaciones de este escenario, con un valor de ejemplo para cada una.
4. Built-in: las seis variables de conversación que siempre están disponibles, con su valor actual o uno de ejemplo mostrado en línea.
5. System Tokens: credenciales proporcionadas por una integración conectada (p. ej. HubSpot). Solo aparece si la integración está conectada.

El dropdown agrupa las variables en secciones. Las filas Built-in muestran el valor en vivo cuando ya se conoce (scenario_id) y ejemplos e.g. … para el resto. El grupo Metadata (used in recent conversations) se reconstruye por escenario a partir de conversaciones reales recientes. La sección System Tokens (no mostrada aquí) aparece solo cuando hay una integración conectada.

Nota

La lista Metadata (used in recent conversations) se reconstruye a partir de las 20 conversaciones más recientes de tu escenario y se cachea 5 minutos por Agente de IA. Una clave de metadatos establecida en una conversación recién creada puede tardar hasta 5 minutos en aparecer en esta sección. Siempre puedes escribir {{metadata_<your_key>}} directamente: Quickchat no requiere que la clave aparezca en el dropdown para que la sustitución funcione.

Variables integradas

Estas seis variables siempre están disponibles. El dropdown + Add AI Data muestra el valor en vivo (cuando ya se conoce) o un valor de ejemplo junto a cada fila.

Variable	Ejemplo	Qué es
{{scenario_id}}	abc123xyz	ID del Agente de IA al que pertenece la conversación.
{{conversation_id}}	conv-d8a8…	Identificador único de la conversación.
{{conversation_url}}	https://app.quickchat.ai/.../conv-d8a8…	Enlace directo en la Bandeja de entrada (Inbox) a esta conversación.
{{conversation_channel}}	widget, telegram, slack, whatsapp, …	Canal en el que está ocurriendo la conversación.
{{language}}	en, nl, de, fr, …	Código ISO 639-1 en minúsculas del idioma de la conversación.
{{country}}	US, GB, NL, DE, …	Código de país ISO 3166-1 alpha-2 en mayúsculas.

Algunas notas útiles:

• {{scenario_id}} también es visible en la URL del navegador mientras editas la Action. El dropdown + Add AI Data muestra el ID en vivo del escenario que estás editando, no un ejemplo.
• {{conversation_url}} es útil para publicar enlaces clicables en Slack, Jira o cualquier otra herramienta que se beneficie de un salto directo de regreso a la Bandeja de entrada.
• {{language}} se deriva de (en este orden): el prefijo de URL de la página (para Shopify Markets), los metadatos de la conversación, y luego el idioma configurado de tu Agente de IA.
• {{country}} se deriva de (en este orden): el prefijo de URL de la página, el TLD del host de la URL, y luego un fallback de idioma a país.

Metadatos de conversación

El prefijo metadata_ es obligatorio. Quickchat busca <key> en los metadatos de la conversación y sustituye su valor en la petición.

{{metadata_order_id}}      →   ord_8a4f3…
{{metadata_customer_tier}} →   gold

Claves de metadatos del visitante

Estas cuatro claves describen la sesión del visitante y tienen su propia sección Visitor en el dropdown. Se capturan automáticamente desde el canal, la integración, el widget/embed o la API. No necesitas enviarlas tú mismo.

Variable	Capturada automáticamente por
{{metadata_fullPathURL}}	Widget de sitio web, embed de sitio web o integraciones de canal de chat que incluyen su propio widget (HubSpot, Intercom, etc.).
{{metadata_visitor_name}}	Perfil del canal de chat (Telegram, Slack, etc.), integraciones de canal, Smart Data Gathering, tu widget/embed o la API de Quickchat.
{{metadata_visitor_email}}	Perfil del canal de chat, integraciones de canal, Smart Data Gathering, tu widget/embed o la API de Quickchat.
{{metadata_visitor_phone_number}}	WhatsApp y otros canales que conocen el teléfono, integraciones de canal, Smart Data Gathering, tu widget/embed o la API de Quickchat.

Claves de metadatos personalizadas

Puedes adjuntar pares clave-valor arbitrarios a una conversación y referenciarlos como {{metadata_<key>}}.

Desde el widget o embed del sitio web

Pasa custom_params al inicializar el widget. Consulta la sección Canal Website: Advanced Features: Custom Parameters para el fragmento completo.

<script>
  _quickchat("custom_params", {
    "order_id": "ord_8a4f3",
    "customer_tier": "gold"
  });
</script>

Referéncialos en cualquier Action como {{metadata_order_id}} y {{metadata_customer_tier}}.

Precaución

Las claves de metadatos deben coincidir con ^[a-zA-Z0-9_]+$ (letras, dígitos, guiones bajos). Las claves con espacios u otra puntuación no pueden referenciarse como {{metadata_<key>}}. Seguirán apareciendo en la vista de metadatos de la conversación en la Bandeja de entrada, pero la sustitución en la Action las omitirá. Mantente con nombres snake_case cuando pienses usarlos en Actions.

Desde Smart Data Gathering

Cada nombre de campo que configures en una campaña de Smart Data Gathering se convierte en una clave de metadatos con el mismo nombre. Si tu campaña recopila delivery_address, puedes usar {{metadata_delivery_address}} inmediatamente en cualquier API Action posterior.

Desde integraciones de canal

HubSpot, Intercom, Telegram, Slack, WhatsApp e integraciones similares envían sus propios metadatos a la conversación (nombre del visitante, email, URL de la página, propiedades de la cuenta, etc.). Cualquier cosa visible en la vista de metadatos de la conversación en la Bandeja de entrada se puede referenciar mediante {{metadata_<key>}}.

Desde la API de Quickchat

Usa POST /v1/api_core/conversations/{conv_id}/metadata para adjuntar metadatos programáticamente. Consulta Conversation Metadata en la referencia de la API.

Colores de los pills en el editor

Cada referencia {{...}} se muestra como un pill de color para que sepas de un vistazo si Quickchat reconoce la variable.

Los pills funcionan en cualquier campo de valor. Arriba: un pill naranja {{metadata_user_type}} en la URL del endpoint, y un pill azul {{language}} en el valor de un header.

Las mismas reglas de color se aplican dentro de un body JSON de petición. Variables integradas como {{country}} se muestran en azul, y variables de metadatos como {{metadata_fullPathURL}} en naranja.

• 🔵 Azul: una variable integrada o un parámetro de IA que definiste.
• 🟠 Naranja: una variable de metadatos ({{metadata_*}}) o un System Token de una integración conectada.
• 🔴 Rojo: Quickchat no reconoce este nombre. Casi siempre es un error de tipeo. Corrige la ortografía, defínelo como parámetro de IA o (si realmente es una clave de metadatos) asegúrate de que empiece con metadata_.

Consejo

Escribir {{metadata_anything}} directamente siempre es válido, incluso si la clave nunca ha aparecido en una conversación. El pill será naranja, no rojo. Esta es la forma correcta de conectar claves que tú mismo defines desde un script de widget o Smart Data Gathering antes de que ocurra la primera conversación.

Probar tu Action

El panel Test Response (junto a Done en el editor de Action) te permite enviar una petición HTTP real sin pasar por un chat. Para cada variable referenciada en la Action, verás una fila de entrada para rellenar el valor que Quickchat sustituirá.

Dos rellenos previos útiles:

• {{language}} por defecto es en
• {{country}} por defecto es US

Sobrescribe cualquiera de los dos campos para probar una locale diferente. Todas las demás variables (tus parámetros de IA, claves {{metadata_*}} y el resto de built-ins) empiezan en blanco. Escribe cualquier valor para simular lo que ocurriría en una conversación en vivo.

FAQ

¿Por qué mi variable aparece en rojo? El editor no reconoce el nombre. O es un error de tipeo, o no coincide con ningún parámetro de IA que hayas definido, o no es una variable integrada, o es una clave de metadatos a la que le falta el prefijo metadata_.

¿Puedo inyectar {{language}} o {{country}} aunque nunca los establezca? Sí. Quickchat siempre deriva ambos del contexto de la conversación (URL de la página, locale del navegador o el idioma configurado de tu Agente de IA). Siempre obtendrás un valor, incluso si recae en en / US.

¿Cuál es la diferencia entre {{language}} y {{metadata_locale}}?

• {{language}} es la variable integrada. Siempre disponible, siempre en formato en / nl / de … Úsala el 99 % del tiempo.
• {{metadata_locale}} solo existe si una integración de canal o tu widget estableció explícitamente una clave locale en los metadatos de la conversación, a menudo en formato xx_YY (p. ej. en_GB). Recurre a ella solo cuando necesites la cadena exacta de locale al pie de la letra.

¿Hay un límite en el número de parámetros de IA por Action? Sí, 30 por Action. Si realmente necesitas más, contacta con soporte.

¿Se envían los valores integrados y de metadatos a la IA? No. Se inyectan en la petición HTTP después de que la IA haya decidido llamar a la Action. La IA no los ve y no se le pide que los rellene. Por eso no necesitan definirse como parámetros de IA.

¿Con qué frecuencia se refresca la lista “Metadata (used in recent conversations)”? Se cachea 5 minutos por Agente de IA. Una clave de metadatos establecida en una conversación recién creada puede tardar hasta 5 minutos en aparecer en el dropdown, pero siempre puedes escribir {{metadata_<your_key>}} directamente sin esperar.

¿Son sensibles a mayúsculas y minúsculas los nombres de claves de metadatos? Sí. {{metadata_orderId}} y {{metadata_orderid}} son claves distintas. Usa exactamente las mismas mayúsculas/minúsculas que pusiste en el widget, la integración o el lado de la API.

¿El panel Test Response conoce estas variables? Sí. Cuando tu Action referencia {{language}} o {{country}}, el panel Test Response los rellena con en y US respectivamente. Todas las demás variables empiezan en blanco. Escribe cualquier valor para simular una llamada en vivo.

Relacionado

• Custom Actions: cómo crear y configurar una API Action.
• Canal Website: Custom Parameters: cómo enviar metadatos desde tu sitio web.
• API: Conversation Metadata: cómo enviar metadatos programáticamente.