Qué aprenderás

Qué son las API de Customer Agent, qué hace cada grupo de punto de conexión y cómo empezar a llamarlas. Las API te permiten configurar tu Customer Agent, leer lo que está haciendo en producción y ejecutarlo mediante programación, directamente a través de HTTP, junto con el resto de la API pública de Klaviyo.

Nota: Las API de Customer Agent están en fase beta. Los punto de conexión y los esquemas pueden cambiar antes de la disponibilidad general. Las API beta no están diseñadas para su uso en producción (consulta la política de versionado y retirada de versiones de Klaviyo para obtener más información).

Qué te permiten hacer las API

Las API de Customer Agent cubren 4 tareas:

  1. Configura el agente: lee o actualiza el agente en sí, además de sus habilidades, herramientas, fuentes de conocimiento y secretos.
  2. Lee conversaciones de producción: enumera e inspecciona las conversaciones de los Customer Agent.
  3. Informa sobre el rendimiento: volumen de extracción, tasa de resolución y métricas por habilidad.
  4. Ejecuta el agente durante un turno: envía un turno de conversación y recupera la respuesta del agente. Esta es la primitiva sin cabeza, útil para incrustar el agente en tu propia superficie.

Como estos cuatro trabajos están detrás de una sola API, puedes conectarlos en un bucle de entrenamiento continuo: extraer lo que ocurrió, diagnosticar lo que funcionó y lo que no, y después aplicar los cambios de configuración. Con una integración de API o una conexión MCP configurada de forma segura, un asistente de IA como Claude o ChatGPT puede ayudar a leer conversaciones, encontrar patrones en los fallos y proponer cambios en tus habilidades, herramientas, conocimientos y orientación.

Autenticación y acceso

Usa una clave de API privada de Klaviyo con el ámbito agents para llamar a estos punto de conexión. Customer Agent ya debe estar habilitado para tu cuenta.

Cuando creas la clave, eliges el nivel de acceso para el ámbito agents:

Nivel de acceso

Subvenciones

Acceso de lectura

agents:read (puntos de conexión GET para configuración y conversaciones, además de puntos de conexión POST para informes). No se devuelven los valores secretos.

Acceso completo

agents:read y agents:write: todo lo anterior, además de cambios de configuración compatibles, creación y actualizaciones de conversaciones, y ejecución del agente para un turno.

Elige la opción de solo lectura si solo necesitas observar al agente (por ejemplo, un panel de informes). Elige lectura/escritura si necesita configurar el agente o ejecutar turnos de conversación.

  1. Ve a Configuración > claves de API y haz clic en Crear clave de API privada.
  2. Introduce un nombre de clave de API privada y selecciona Clave personalizada.
  3. En la fila Agentes, selecciona Acceso de lectura o Acceso completo para la integración, usando la tabla anterior.
  4. Haz clic en Crear y, a continuación, haz clic en el icono de copiar y guarda la clave de forma segura. No puedes volver a ver la clave después de salir de la página de confirmación.

Para obtener más información, consulta cómo crear o clonar una clave de API privada.

Envía solicitudes de API desde el servidor a https://a.klaviyo.com e incluye este encabezado de autorización. Mantén la clave privada fuera del código del navegador y de las aplicaciones orientadas a compradores:

Authorization: Klaviyo-API-Key your-private-api-key

Cada solicitud también debe incluir el encabezado de la revisión beta:

revision: 2026-10-15.pre

Sin el encabezado de la revisión beta, la solicitud se rechazará.

Límites de la tasa

Los límites de tasa dependen del grupo de puntos de conexión:

  • Agente, habilidades, herramientas, conocimientos, secretos y respuestas: límite de ráfaga de 10 solicitudes por segundo y límite sostenido de 150 solicitudes por minuto.
  • Conversaciones, mensajes de conversación e informes: límite de ráfaga de 3 solicitudes por segundo y límite constante de 60 solicitudes por minuto.

Formato de la solicitud

Utiliza las convenciones de solicitud JSON:API de Klaviyo, con un formato independiente para las cargas de archivos:

  • Tipo de contenido: application/vnd.api+json para solicitudes JSON. Usa multipart/form-data para POST /api/agent-knowledge-files.
  • Las colecciones paginadas usan page[cursor] y page[size] (por defecto 50, máximo 100, solo hacia adelante). Sigue links.next hasta que esté vacío para recuperar las páginas restantes.
  • El filtrado utiliza los campos y los operadores compatibles que se enumeran en la referencia de cada punto de conexión. El orden de clasificación es específico del punto de conexión: las conversaciones van de la más reciente a la más antigua, los mensajes van del más antiguo al más reciente, y las habilidades y las herramientas se clasifican por ID.

Grupos de punto de conexión

Agente

Hay como máximo 1 Customer Agent por empresa. Llama a GET /API/Customer Agent para encontrar su ID y, a continuación, usa ese ID en la URL de GET o PATCH. La lista está vacía si Customer Agent no está habilitado para la cuenta.

Método

Ruta

Qué hace

GET

/api/customer-agents

Encuentra el agente y su ID

GET

/api/customer-agents/{id}

Recupera el nombre del agente, el tono de voz, las reglas de escalado y los estilos de comunicación

PATCH

/api/customer-agents/{id}

Actualiza los campos de nivel superior del agente.

Habilidades de los agentes

Puedes leer las habilidades que quedan en la cuenta, incluidas las habilidades personalizadas y los valores predeterminados personalizados anteriormente. Se han eliminado las habilidades predeterminadas sin modificar y la biblioteca de plantillas de habilidades predeterminadas. Solo las habilidades personalizadas se pueden actualizar o eliminar a través de estos puntos de conexión. Establece el status de una habilidad personalizada en draft para ponerla en fase de preparación o pausarla, o en live para activarla.

Método

Ruta

Qué hace

GET

/api/agent-skills

Enumera todas las habilidades

POST

/api/agent-skills

Crear una habilidad

GET

/api/agent-skills/{id}

Consigue una habilidad

PATCH

/api/agent-skills/{id}

Actualizar una habilidad

DELETE

/api/agent-skills/{id}

Eliminar una habilidad

Herramientas del agente

Solo las herramientas personalizadas se pueden actualizar o eliminar. Para usar una herramienta dentro de una habilidad personalizada, vincúlala mediante la relación agent-tools de la habilidad. El uso directo se controla mediante los permisos de la herramienta en Customer Agent > Conectores; una herramienta no necesita una habilidad cuando se configura en Permitir siempre. Una herramienta configurada en Solo en habilidades debe incluirse en una habilidad, y Bloqueado evita el uso por cualquiera de las dos vías.

Para consultar el comportamiento de los permisos de herramientas, consulta Información sobre las herramientas.

Método

Ruta

Qué hace

GET

/api/agent-tools

Herramientas de lista visibles para la empresa

POST

/api/agent-tools

Crear una herramienta HTTP externa

GET

/api/agent-tools/{id}

Consigue una herramienta

PATCH

/api/agent-tools/{id}

Actualizar una herramienta

DELETE

/api/agent-tools/{id}

Eliminar una herramienta

Conocimientos del agente

Crea fragmentos de texto, páginas web, pares de preguntas y respuestas o carpetas configurando source.source_type como snippet, webpage, qa o folder. Para añadir un file, usa el punto de conexión de carga de archivos independiente.

Método

Ruta

Qué hace

GET

/api/agent-knowledge

Enumera los elementos de conocimiento de nivel superior, del más reciente al más antiguo; filtra por folder_id para enumerar el contenido de una carpeta

POST

/api/agent-knowledge

Crear un fragmento, una página web, un par de Q&A o una carpeta

POST

/api/agent-knowledge-files

Subir un archivo como fuente de conocimiento (varias partes)

GET

/api/agent-knowledge/{id}

Obtén una fuente de conocimientos

PATCH

/api/agent-knowledge/{id}

Actualiza el título o el contenido de un fragmento, o la pregunta o la respuesta de un par de preguntas y respuestas

DELETE

/api/agent-knowledge/{id}

Eliminar una fuente de conocimientos

Secretos del agente

Secretos cifrados que usan las herramientas personalizadas. El punto de conexión de la lista solo devuelve metadatos seguros; el valor secreto en sí nunca se devuelve.

Método

Ruta

Qué hace

GET

/api/agent-secrets

Lista secreta (solo metadatos)

POST

/api/agent-secrets

Crear un secreto

PATCH

/api/agent-secrets/{id}

Actualizar un secreto

DELETE

/api/agent-secrets/{id}

Eliminar un secreto

Conversaciones

Lee las conversaciones que el agente ha tenido con los compradores o crea una conversación para ejecutarla a través de la API. Una conversación puede abarcar muchos mensajes durante un periodo largo. La lista puede incluir conversaciones en directo y de vista previa; usa filter=equals(mode,"live") para limitarla a conversaciones en directo.

Método

Ruta

Qué hace

GET

/api/customer-agent-conversations

Enumerar conversaciones

GET

/api/customer-agent-conversations/{id}

Obtener una conversación por ID, incluidas las referencias a sus mensajes

GET

/api/customer-agent-conversations/{id}/customer-agent-messages

Leer el contenido del mensaje, de más antiguo a más reciente, con paginación

POST

/api/customer-agent-conversations

Crea una conversación vacía antes de ejecutar el agente.

Informes

Métricas agregadas, limitadas a la empresa solicitante. Ambos informes que aparecen a continuación son puntos de conexión POST: pasa los parámetros del informe en el cuerpo. Requieren agents:read, así que una clave de solo lectura puede ejecutarlos.

Método

Ruta

Qué hace

POST

/api/customer-agent-values-reports

Métricas de nivel de conversación: volumen y tasa de resolución

POST

/api/customer-agent-skill-values-reports

Informe de volumen por habilidad

Ejecuta el agente

Método

Ruta

Qué hace

POST

/api/customer-agent-responses

Ejecuta el Customer Agent durante un turno de conversación: pasa la entrada del comprador y recupera la respuesta del agente.

Este es el método primitivo para integrar el Customer Agent en tu propia superficie (tu aplicación, tu centro de ayuda, un panel de asistencia diseñado por socios).

Crea una conversación abierta con POST /api/customer-agent-conversations antes de ejecutar un turno. El punto de conexión de respuesta solo acepta conversaciones creadas mediante la API. Una conversación cerrada, o una que ya se ha asignado a tu equipo, no puede aceptar más respuestas.

Qué sigue requiriendo la interfaz de usuario de Klaviyo

Algunos pasos de configuración aún no están activos en el API:

  • Configuración de canales (chat web, correo electrónico, SMS, WhatsApp): la configuración de canales se lleva a cabo en la configuración de la Plataforma Klaviyo.
  • Activación en cada canal: el interruptor de encendido/apagado por canal permanece en la interfaz de usuario.
  • Selección de Helpdesk (en Customer Agent, abre un canal en Channels y configura la sección Transferencia). Consulta Gestionar la configuración de Customer Agent para obtener más información.

Flujos de trabajo típicos

Configura una vez y luego mantén

  1. Crea una clave de API privada con el alcance agents y acceso de lectura y escritura en Klaviyo.
  2. Extrae el estado actual (GET /api/customer-agents para encontrar el ID del agente) y, a continuación, recupera el agente y las listas de habilidades, herramientas y conocimientos. Sigue los enlaces de paginación para leer todas las páginas.
  3. Realiza cambios (crea o actualiza habilidades, herramientas, conocimientos y secretos personalizados según sea necesario). Revisa los permisos de la herramienta en Conectores. Vincula las herramientas a cualquier habilidad personalizada que las use y establece esas habilidades en estado: activo cuando estés listo para activarlas.
  4. Comprueba la producción: enumera las conversaciones recientes y extrae un informe de valores para ver cómo está funcionando el agente.
  5. Iterar

Entrena a tus agentes en un bucle

Las APIs están diseñadas para cerrar el bucle entre lo que tu agente hizo en producción y cómo está configurado. Un bucle típico:

  1. Extrae conversaciones recientes (OBTÉN conversaciones filtradas por created_at y status, añadiendo equals(mode,"live") al filtro para conversaciones de producción). Obtén los Customer Agent-messages de cada conversación y sigue links.next para leer todas las páginas.
  2. Diagnosticar: clasifica cada conversación como un éxito o un fracaso. Buscar patrones: ¿las escalas se agrupan en torno a un tema? ¿Se están desviando ciertas habilidades cuando no deberían? ¿El agente no tiene los conocimientos que necesita?
  3. Métricas extraídas: informes de valores para el volumen y la tasa de resolución, además de informes de valores de habilidades para desgloses por habilidad. Confirma que los patrones se mantengan en conjunto.
  4. Propón cambios: en función de los patrones de fallos, decide qué cambiar: edita las instrucciones de una habilidad, añade un fragmento de conocimiento, crea una nueva herramienta personalizada, ajusta una regla de tono, añade un activador de escalada.
  5. Aplicar cambios: PARCHAR las habilidades afectadas, PUBLICAR nuevas fuentes de conocimiento, etc.
  6. Loop Se repite en la siguiente ventana de conversaciones.

Puedes usar un asistente de IA como Claude, ChatGPT o Cursor para extraer conversaciones, detectar carencias, proponer ediciones específicas y aplicar cambios con tu aprobación. Conéctalo a través del servidor MCP de Klaviyo o de tu propia integración de API y mantén la clave de API privada en una configuración segura en lugar de incluirla en prompts. El servidor MCP admite muchas de estas tareas, pero crear o actualizar secretos y subir archivos de conocimiento requieren llamadas directas a la API.

Inserta el agente en tu propia superficie

Usa mode: preview para hacer pruebas sin facturación ni métricas de producción. mode: live es para interacciones reales de compradores y cuenta para la facturación y las métricas de producción. La advertencia anterior sobre el uso beta sigue aplicándose.

  1. Crea una clave con el alcance de los agentes (lectura/escritura).
  2. Crea una conversación (desde tu servidor, envía una solicitud POST a /api/customer-agent-conversations con el mode seleccionado). Guarda el ID de conversación devuelto.
  3. Abre una conversación en tu interfaz de usuario: recopila la entrada del comprador.
  4. Ejecuta un turno (desde el servidor, envía una solicitud POST a /api/customer-agent-responses con mode, messages y el ID guardado en data.relationships.conversation.data.id). Usa el tipo de relación customer-agent-conversation. Incluye el historial de la conversación en messages y termina con el mensaje más reciente del comprador con role: user.
  5. Renderiza la respuesta (procesa los eventos devueltos en orden y muestra los mensajes del agente y cualquier dato estructurado compatible en tu interfaz). Gestiona los eventos de transferencia en tus integraciones. La API devuelve eventos juntos sin streaming; no los entrega a través de un canal.
  6. Repite en cada turno con el mismo ID de conversación y modo mientras la conversación esté abierta. Después de una transferencia difícil o silenciosa, deja de solicitar respuestas del agente y redirige al comprador al equipo de soporte.

PREGUNTAS FRECUENTES

¿Hay algún servidor MCP?

Sí. El servidor MCP de Klaviyo alojado de forma remota incluye herramientas de Customer Agent para habilidades, herramientas, conocimientos, metadatos secretos, conversaciones, informes y la ejecución del agente. Crear una conversación, crear o actualizar secretos y cargar archivos de conocimiento requiere llamadas directas a la API. Consulta Servidor MCP de Klaviyo.

¿Es esto lo suficientemente estable como para seguir avanzando?

La versión beta significa que el esquema puede cambiar. Los puntos de conexión son perfectamente definibles, pero aún no nos comprometemos a lograr una estabilidad a largo plazo. No envíes integraciones críticas para la producción en comparación con la revisión beta.

¿Dónde encuentro el esquema completo?

La referencia completa está disponible en el portal de desarrolladores de Klaviyo en https://developers.klaviyo.com/en/reference/. Los puntos de conexión de Customer Agent aparecen en las API beta en la revisión 2026-10-15.pre.

Artículos relacionados

Learn more about Klaviyo APIs, authentication, and beta features.

¿Te ha resultado útil este artículo?
Utiliza este formulario solo para enviar comentarios sobre el artículo. Más información sobre cómo contactar con el servicio de asistencia.

Descubre más sobre Klaviyo

Klaviyo Community
Conecta con compañeros, socios y expertos de Klaviyo para encontrar ideas, compartir información y resolver todas tus dudas.
Socios
Contrata a un experto certificado por Klaviyo para ayudarte con una tarea específica o para la gestión continua de marketing.
Asistencia

Accede al servicio de asistencia a través de tu cuenta.

Asistencia por correo electrónico (prueba gratuita y cuentas de pago) Disponible 24/7

Asistencia por chat/virtual
La disponibilidad varía según la ubicación y el tipo de plan