Conversation Metadata

Conversation Metadata te permite adjuntar datos clave-valor personalizados a las conversaciones, creando un potente puente entre tus sistemas y tu Agente de IA. Los metadatos fluyen por todo tu flujo de trabajo de Quickchat:

• Alimentar vía API — Usa estos endpoints para adjuntar metadatos de forma programática a cualquier conversación (p. ej., desde tu CRM, helpdesk o backend)
• Alimentar vía widget/embed — Pasa metadatos como parámetros de inicialización al cargar el widget, o inyéctalos dinámicamente durante una conversación activa usando el SDK de JavaScript
• Visibles en el Dashboard: los metadatos personalizados aparecen en los detalles de la conversación en la Bandeja de entrada. Las claves internas se filtran, y los datos de contacto capturados y la memoria de las Actions tienen su propia presentación
• Incluidos en las exportaciones — Los metadatos se incluyen cuando exportas conversaciones desde el Dashboard, lo que los hace disponibles para análisis sin conexión
• Usados en AI Actions — Los valores de metadatos pueden inyectarse directamente como marcadores {{metadata_<key>}} en las AI Actions. Consulta AI Action Variables para la referencia completa de marcadores disponibles
• Disponibles para el Agente de IA cuando está permitido: el contexto del modelo utiliza un subconjunto filtrado de los metadatos. Almacenar una clave no garantiza que el modelo la reciba o la mencione

Usa los metadatos para referencias de clientes, contexto de la cuenta, analítica y datos de entrada para las Actions. El almacenamiento, la visualización en la Bandeja de entrada, la sustitución en las Actions y el contexto del modelo son usos distintos de los mismos datos.

Los metadatos se validan contra un esquema JSON si hay uno configurado en el Dashboard.

Contexto del modelo y autorización

En los canales controlados por el visitante, como el Widget y el Embed del sitio web, el contexto del modelo admite las claves de contacto del visitante (visitor_name, visitor_email, visitor_phone_number) y las claves permitidas que las Actions activas referencian o capturan. Los valores internos y reservados se filtran; también se aplican límites de configuración y tamaño. Otras integraciones tienen reglas de contexto específicas para cada canal. Una clave personalizada como customer_tier o customer_id no es automáticamente visible para el modelo por el mero hecho de enviarla.

Una Action puede sustituir {{metadata_<key>}} al construir su petición sin pedir a la IA que genere ese valor. Esto no convierte los metadatos normales en secretos: un valor permitido puede entrar por separado en el contexto del modelo o aparecer en la respuesta de una Action. No almacenes claves API ni contraseñas en los metadatos personalizados.

Los metadatos enviados desde el navegador no son una prueba de identidad ni de permisos. El servicio que los recibe debe autenticar y autorizar el acceso a los registros privados; no basta con un ID de cliente o un nivel de plan enviado desde el navegador. Prueba tanto la petición resultante de la Action como la respuesta del Agente con tu configuración.

Get Metadata

Scope: read_all

GET https://app.quickchat.ai/v1/api_core/conversations/{conv_id}/metadata

Shell

curl https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Response 200 OK

{
  "metadata": {
    "ticket_id": "T-1234",
    "priority": "high"
  }
}

Set Metadata

Crea o actualiza los metadatos de una conversación.

Scope: write_all

POST https://app.quickchat.ai/v1/api_core/conversations/{conv_id}/metadata

Request Body

Parameter	Description
metadata object, required	Metadatos clave-valor que almacenar

Shell

curl -X POST https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "metadata": {
    "ticket_id": "T-1234",
    "priority": "high"
  }
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/metadata",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "metadata": {"ticket_id": "T-1234", "priority": "high"}
    },
)
data = response.json()

Response 200 OK

{
  "metadata": {
    "ticket_id": "T-1234",
    "priority": "high"
  }
}

---