zendesk-sunshine-conversations-user-data-ai-agents
eesel Team
Last edited 20 febrero 2026
{
"title": "Cómo acceder y utilizar los datos de usuario en Zendesk Sunshine Conversations para agentes de IA",
"slug": "zendesk-sunshine-conversations-user-data-ai-agents",
"locale": "es",
"date": "2026-02-20",
"updated": "2026-02-20",
"template": "default",
"excerpt": "Una guía técnica para acceder a los datos de usuario en Zendesk Sunshine Conversations, que abarca la API de usuario, la API de clientes, la transferencia de metadatos y los patrones de implementación prácticos para agentes de IA.",
"categories": [
"Blog Writer AI"
],
"tags": [
"Zendesk",
"Sunshine Conversations",
"AI agents",
"user data",
"API integration"
],
"readTime": 14,
"author": 16,
"reviewer": 14,
"seo": {
"title": "Cómo acceder y utilizar los datos de usuario en Zendesk Sunshine Conversations para agentes de IA",
"description": "Una guía técnica para acceder a los datos de usuario en Zendesk Sunshine Conversations, que abarca la API de usuario, la API de clientes, la transferencia de metadatos y los patrones de implementación prácticos para agentes de IA.",
"image": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-621a5d12-46fe-402d-a6be-1b4486953e76"
},
"coverImage": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-621a5d12-46fe-402d-a6be-1b4486953e76",
"coverImageAlt": "Imagen de banner para Cómo acceder y utilizar los datos de usuario en Zendesk Sunshine Conversations para agentes de IA",
"coverImageWidth": 1920,
"coverImageHeight": 1080,
"faqs": {
"heading": "Preguntas Frecuentes",
"type": "blog",
"answerType": "html",
"faqs": [
{
"question": "¿Qué plan de Zendesk necesito para acceder a los datos de usuario en Sunshine Conversations para agentes de IA?",
"answer": "Necesita Zendesk Suite Professional o superior, además del complemento Advanced de agentes de IA. El plan Suite Professional incluye acceso a la API de Conversations, mientras que el complemento Advanced desbloquea el Integration Builder donde configura las llamadas a la API."
},
{
"question": "¿Puedo acceder a los datos de usuario sin utilizar el Integration Builder?",
"answer": "Sí, puede realizar llamadas a la API directamente a Sunshine Conversations desde sus propios servidores o aplicaciones. El Integration Builder es la interfaz sin código de Zendesk para las mismas API subyacentes. Si prefiere escribir código, puede utilizar la API REST directamente con las mismas credenciales de autenticación."
},
{
"question": "¿Están seguros los datos del cliente cuando se utilizan estas API?",
"answer": "Sunshine Conversations cifra los datos en tránsito y en reposo. Las llamadas a la API utilizan HTTPS y la autenticación requiere su clave secreta. Siga las mejores prácticas de seguridad: almacene las credenciales en variables de entorno, rote las claves periódicamente y utilice claves separadas para los entornos de desarrollo y producción."
},
{
"question": "¿Qué ocurre si un usuario no ha proporcionado su nombre u otra información de perfil?",
"answer": "Los campos de la API devolverán valores nulos o vacíos. Siempre incorpore lógica de reserva en sus diálogos. Compruebe si existe {{givenName}} antes de utilizarlo en los saludos, y tenga mensajes alternativos preparados para cuando los datos del perfil estén incompletos."
},
{
"question": "¿Puedo actualizar la información del perfil de usuario a través de la API?",
"answer": "Son posibles actualizaciones limitadas. Puede actualizar los metadatos de la conversación y algunas propiedades del usuario, pero los campos principales del perfil, como surname y givenName, suelen ser de solo lectura una vez establecidos. Para actualizar la información del usuario, es posible que tenga que utilizar la API principal de usuarios de Zendesk en lugar de la API de Sunshine Conversations."
}
],
"supportLink": null
}
}
---
Las experiencias personalizadas del cliente comienzan con saber con quién está hablando. Cuando un cliente se pone en contacto con su agente de IA, espera algo más que respuestas genéricas. Quieren que sepa su nombre, que entienda su historial y que tenga contexto sobre su problema. Los datos de usuario en [Zendesk Sunshine Conversations](https://developer.zendesk.com/api-reference/conversations/) lo hacen posible.
Sunshine Conversations sirve como la capa de mensajería debajo de los agentes de IA de Zendesk, manejando todo, desde mensajes de WhatsApp hasta chat web. Pero acceder a los datos de usuario almacenados dentro de él requiere comprender la [arquitectura de la API](https://developer.zendesk.com/documentation/conversations/how-to-guides/messaging-user-data-ai-agents-advanced/) y saber qué endpoints (puntos de conexión) llamar. Esta guía le explica exactamente cómo recuperar y utilizar los datos del cliente para crear experiencias de agente de IA más personalizadas.
Si está buscando un enfoque más sencillo que no requiera la creación de integraciones de API personalizadas, ofrecemos una alternativa. Nuestra plataforma se conecta directamente a Zendesk y gestiona el acceso a los datos de usuario automáticamente. Pero si está creando soluciones personalizadas o necesita un control total sobre el flujo de datos, esta guía técnica le mostrará exactamente lo que necesita saber.
## Comprender la arquitectura de datos de Sunshine Conversations
Sunshine Conversations (anteriormente Smooch.io) opera como la capa de datos subyacente para todas las interacciones de mensajería en Zendesk. Originalmente un producto independiente, ahora está totalmente integrado en Zendesk Suite y se encarga del trabajo pesado de enrutar mensajes entre clientes, agentes de IA y agentes humanos. La plataforma proporciona una [API de mensajería unificada](https://developer.zendesk.com/api-reference/conversations/) que conecta múltiples canales a una única interfaz de conversación.
Así es como fluyen los datos: cuando un cliente envía un mensaje a través de WhatsApp, un widget web o cualquier otro canal, Sunshine Conversations recibe ese mensaje, identifica al usuario y lo enruta al gestor adecuado. Su agente de IA interactúa entonces con Sunshine Conversations para acceder a los perfiles de usuario, el historial de conversaciones y los metadatos.
La plataforma almacena los datos del usuario en varias ubicaciones distintas:
**Objeto User (Usuario)**: Contiene información básica del perfil, incluyendo el ID del usuario, el nombre (profile.surname y profile.givenName), la dirección de correo electrónico, las preferencias de idioma, el estado de autenticación y cuándo se registró por primera vez (signedUpAt). El *endpoint* de la API de User le da acceso a todo esto.
**Objeto Clients (Clientes)**: Cada usuario puede tener múltiples "clientes" que representan diferentes canales que utilizan. Un cliente podría tener un cliente de WhatsApp, un cliente de SMS y un cliente de chat web. Cada cliente almacena datos específicos del canal, incluyendo números de teléfono para usuarios de WhatsApp y SMS.
**Metadatos de la conversación**: Son datos contextuales que se pasan desde su sitio web o aplicación, como las URL de las páginas, los ID de los pedidos o los campos personalizados. Se almacenan a nivel de conversación y se puede acceder a ellos o actualizarlos durante el chat.
**Participants (Participantes)**: Cada conversación tiene participantes, y este enlace es cómo se conecta un ID de conversación a un ID de usuario específico.
Para trabajar con estos datos, necesitará algunos requisitos previos: una licencia de Sunshine Conversations (incluida con Zendesk Suite Professional y superior), [claves de API creadas en el Centro de administración](https://support.zendesk.com/hc/en-us/articles/4576088682266) y el complemento Advanced de agentes de IA para las funciones del Integration Builder.
## Configurar el acceso API a los datos de usuario
Antes de poder recuperar cualquier información del usuario, debe configurar la autenticación. Sunshine Conversations utiliza un sistema de dos credenciales para el acceso a la API que deberá configurar una vez y referenciar en todas sus llamadas a la API.
Diríjase al Centro de administración, luego navegue a Aplicaciones e integraciones, seleccione API y haga clic en API de Conversations. Si no ve esta opción, verifique que está en Suite Professional o superior y que Agent Workspace está habilitado. Encontrará instrucciones de configuración detalladas en la [documentación de la API de Conversations](https://support.zendesk.com/hc/en-us/articles/4576088682266).
Haga clic en "Crear clave de API" y asígnele un nombre descriptivo como "Acceso a datos de usuario del agente de IA". El sistema generará tres datos:
- **App ID (ID de la aplicación)**: Identifica su cuenta de Zendesk y aparece en la mayoría de las URL de la API
- **Key ID (ID de la clave)**: Sirve como nombre de usuario para la autenticación básica
- **Secret Key (Clave secreta)**: Sirve como contraseña. Cópiela inmediatamente, solo aparece una vez
Para las integraciones de API en el Integration Builder, utilizará la autenticación básica con el ID de la clave como nombre de usuario y la clave secreta como contraseña. El ID de la aplicación se incrusta en las URL de los *endpoints* de la API. Necesitará las tres credenciales para cada llamada a la API.
Aquí tiene un consejo rápido: cree claves de API separadas para los entornos de desarrollo y producción. El Integration Builder admite múltiples entornos, por lo que puede configurar diferentes credenciales para las pruebas frente al uso en vivo. Puede almacenar hasta 10 claves, por lo que hay espacio para organizarlas por caso de uso. Vale la pena configurarlo pronto para no modificar accidentalmente los datos en vivo durante las pruebas.
## Recuperar datos del perfil de usuario
Obtener datos de usuario requiere un proceso de API de dos pasos debido a cómo Sunshine Conversations estructura su modelo de datos. Primero, necesita encontrar el ID de usuario asociado con la conversación actual. Luego, utiliza ese ID de usuario para obtener el perfil completo.
### Paso 1: Listar los participantes para obtener el ID de usuario
Cada conversación tiene un ID único que se genera automáticamente cuando se inicia el chat. En AI agents Advanced, esto está disponible como un parámetro del sistema llamado `platformConversationId`. Lo utiliza para llamar al *endpoint* List Participants (Listar participantes).
Cree una [integración de API en el Integration Builder](https://support.zendesk.com/hc/en-us/articles/8357756844442) con esta configuración:
- Tipo de método: GET
- URL: `https://YOUR_DOMAIN.zendesk.com/sc/v2/apps/YOUR_APP_ID/conversations/{{platformConversationId}}/participants`
La respuesta incluye una matriz de participantes. Para una conversación típica con un cliente, obtendrá un objeto participante que contiene el userId que necesita. Utilice esta consulta JSONata para extraerlo: `data.participants.userId`
### Paso 2: Obtener los detalles del usuario de la API de User
Ahora que tiene el userId, cree una segunda integración de API para obtener el perfil completo del usuario:
- Tipo de método: GET
- URL: `https://YOUR_DOMAIN.zendesk.com/sc/v2/apps/YOUR_APP_ID/users/{{userId}}`
La respuesta contiene un objeto de usuario completo. Estos son los campos clave que puede extraer con las consultas JSONata:
| Campo | Consulta JSONata | Valor de ejemplo |
|-------|---------------|---------------|
| Nombre | `data.user.profile.givenName` | "Sarah" |
| Apellido | `data.user.profile.surname` | "Johnson" |
| Correo electrónico | `data.user.profile.email` | "sarah@example.com" |
| Localización | `data.user.profile.locale` | "en-US" |
| Estado de autenticación | `data.user.authenticated` | true/false |
| ID de usuario de Zendesk | `data.user.zendeskId` | "35104420567444" |
### Paso 3: Utilizar los datos en los flujos de su bot
Almacene estos valores como parámetros de sesión en el Integration Builder, luego haga referencia a ellos en su diálogo utilizando dobles llaves como `{{givenName}}`. También puede utilizarlos en la lógica condicional, por ejemplo, comprobando `{{authenticated}}` para mostrar diferentes flujos para los usuarios autenticados frente a los invitados.
Un patrón que funciona bien: cree una acción de evento "Chat Started" (Chat iniciado) que ejecute ambas llamadas a la API automáticamente cada vez que comience una conversación. Esto asegura que los datos del usuario estén disponibles antes de que el cliente envíe su primer mensaje, permitiendo saludos personalizados desde el principio.
## Acceder a datos específicos del canal (WhatsApp, SMS y más)
El objeto de usuario le proporciona información del perfil, pero ¿qué pasa con los detalles específicos del canal, como los números de teléfono? Ahí es donde entra en juego la API de Clients. Este *endpoint* revela a través de qué canales está conectado un usuario y proporciona identificadores específicos del canal.
### Por qué es importante la API de Clients
Si un cliente se pone en contacto con usted a través de WhatsApp, su número de teléfono no se almacena en el objeto de usuario principal. En cambio, reside en la matriz de clientes como parte de su registro de cliente de WhatsApp. Esto es fundamental para casos de uso como:
- Buscar pedidos de clientes por número de teléfono en su CRM
- Enviar mensajes SMS de seguimiento
- Identificar a los clientes que regresan a través de diferentes números de teléfono
- Verificar la identidad del usuario a través de la coincidencia de teléfonos
### Recuperar datos del cliente
Cree una integración de API que llame a:
- Tipo de método: GET
- URL: `https://YOUR_DOMAIN.zendesk.com/sc/v2/apps/YOUR_APP_ID/users/{{userId}}/clients`
La respuesta incluye una matriz de objetos de cliente, cada uno representando una conexión de canal diferente. Para los usuarios de WhatsApp, verá algo como esto:
```json
{
"type": "whatsapp",
"externalId": "1234567890",
"displayName": "Sarah Johnson",
"raw": {
"from": "+15551234567"
},
"linkedAt": "2024-01-15T10:30:00.000Z"
}
Extraer el número de teléfono de WhatsApp
Utilice esta consulta JSONata para obtener el número de teléfono: data.clients[type="whatsapp"].raw.from
Puede adaptar este patrón para otros canales. Para los usuarios de SMS, cambie el filtro de tipo: data.clients[type="sms"].raw.from
Una aplicación práctica: almacene este número de teléfono como un parámetro de sesión, luego utilícelo en una llamada API posterior a su CRM para buscar el historial de pedidos del cliente. Cuando el agente de IA los saluda por su nombre y dice "Veo que tiene un pedido de la semana pasada", la experiencia se siente genuinamente personal.
Pasar datos personalizados a través de los metadatos de la conversación
A veces necesita pasar información de su sitio web o aplicación a la conversación. Tal vez sea la URL de la página donde el cliente hizo clic en ayuda, su ID de pedido del flujo de pago o su nivel de suscripción. Sunshine Conversations gestiona esto a través de los metadatos.
Pasar datos desde el Web Widget
Si está utilizando el Web Widget de Zendesk, puede adjuntar datos personalizados cuando comience la conversación:
zE("messenger:set", "conversationFields", [
{ id: "7662882404114", value: "Premium Plan" }
])
Estos datos aparecen en los metadatos de la conversación con una clave con el formato zen:ticket_field:7662882404114, donde el número es su ID de campo personalizado. El requisito clave: el campo personalizado debe ser editable por el usuario final en Zendesk.
Recuperar metadatos en agentes de IA
En el Integration Builder, cree una Acción utilizando las acciones de CRM con:
- Objetivo: Sunshine Conversations
- Tarea: Obtener metadatos de la conversación
- Recupere el objeto de metadatos y extraiga claves específicas
Haga referencia al nombre completo de la clave, incluyendo el prefijo zen:ticket_field:, al configurar su asignación de parámetros. El valor que pasó desde el widget ahora está disponible como un parámetro de sesión en su diálogo.
Establecer metadatos desde agentes de IA
También puede actualizar los metadatos durante la conversación. Esto es útil cuando el agente de IA recopila información que debería aparecer en el ticket de Zendesk cuando se escala a un agente humano.
Cree una Acción con la Tarea establecida en "Update conversation metadata" (Actualizar metadatos de la conversación). Utilice el mismo formato de clave (zen:ticket_field:FIELD_ID) y pase su parámetro como valor. Cuando la conversación se escale a Agent Workspace, ese campo personalizado se rellenará previamente.
Algunas cosas a tener en cuenta: para los campos desplegables, pase el valor de la etiqueta en lugar del nombre para mostrar. Para los campos de búsqueda, pase el ID del registro relacionado. Los campos del sistema como el asunto o el estado no se pueden actualizar a través de este método, solo los campos personalizados.
Ejemplos prácticos de implementación
Pongamos esto en práctica con algunos escenarios del mundo real.
Saludo personalizado con reserva
Configure su evento "Chat Started" para activar una integración de API que obtenga el nombre del usuario. Almacénelo como {{givenName}}. En su mensaje de bienvenida, escriba: "Hola {{givenName}}, ¿cómo puedo ayudarle hoy?".
Pero, ¿qué pasa si falta el nombre? Añada una comprobación condicional. Si {{givenName}} está vacío, ramifique a un mensaje que diga "Hola, ¿cómo puedo ayudarle hoy?". Esto evita espacios en blanco incómodos en sus saludos.
Búsqueda en el CRM del historial de pedidos
Combine la API de Clients con su propia API de CRM. Primero, obtenga el número de WhatsApp utilizando data.clients[type="whatsapp"].raw.from. Luego, cree una segunda integración de API que llame al endpoint de búsqueda de su CRM, pasando ese número de teléfono como parámetro.
Cuando el CRM devuelve los datos del pedido, extraiga los detalles clave como el número de pedido reciente y el estado. Ahora su agente de IA puede decir "Veo que tiene el pedido #12345 de ayer. ¿Está llamando por eso?".
Flujos de usuarios autenticados
Utilice el campo authenticated de la API de User para mostrar diferentes experiencias. Los usuarios autenticados podrían tener acceso a acciones específicas de la cuenta como "Comprobar el estado de mi pedido" o "Actualizar mi suscripción". Los usuarios invitados ven un menú más limitado centrado en temas de ayuda general.
El estado de autenticación es especialmente útil para acciones sensibles a la seguridad. Antes de procesar un reembolso o un cambio de cuenta, verifique que {{authenticated}} sea igual a true y que el nivel de verificación de identidad del correo electrónico cumpla con sus requisitos.
Solución de problemas comunes
Incluso con la configuración correcta, las cosas no siempre funcionan a la perfección. Estos son los problemas más comunes y cómo resolverlos.
ID de usuario no encontrado: Si su llamada a List Participants devuelve vacío, verifique que platformConversationId se esté pasando realmente. Compruebe su panel de pruebas del Integration Builder para ver qué valores están disponibles en tiempo de ejecución. La conversación necesita existir antes de que pueda listar a sus participantes.
Fallos de autenticación de la API: Compruebe el formato de su encabezado de autenticación básica. Debe ser KeyID:Secret codificado en Base64. Un error común es intercambiar el ID de la clave y el ID de la aplicación, u olvidar incluir el ID de la aplicación en la ruta de la URL.
Faltan datos del cliente: No todos los canales rellenan la matriz de clientes con los mismos campos. WhatsApp normalmente incluye números de teléfono, pero los clientes de chat web podrían no hacerlo. Consulte la documentación específica del canal para comprender lo que está disponible.
Los metadatos no aparecen en Agent Workspace: Asegúrese de que su campo personalizado sea editable por el usuario final. También verifique el formato exacto del nombre de la clave, debe ser zen:ticket_field:12345 sin espacios ni variaciones adicionales. El ID del campo debe coincidir exactamente.
Parámetros de sesión vacíos: Compruebe el orden de las operaciones en su diálogo. Las integraciones de la API deben ejecutarse antes de que intente utilizar sus parámetros de salida. Si está utilizando parámetros de una llamada a la API en una llamada posterior, verifique que la primera se esté completando con éxito.
Limitación de velocidad: Sunshine Conversations tiene límites de velocidad por cuenta. Si está recibiendo errores 429, implemente una retirada exponencial en su lógica de reintento o almacene en caché los datos del usuario para reducir las búsquedas repetidas para la misma conversación.
Simplificar el acceso a los datos de usuario con eesel AI
Todo lo que hemos cubierto funciona bien si tiene recursos de desarrollador y tiempo para crear integraciones personalizadas. Pero no todos los equipos lo hacen. Si necesita soporte impulsado por IA sin la sobrecarga de ingeniería, hay un camino más simple.
Construimos eesel AI específicamente para equipos que desean capacidades sofisticadas de agentes de IA sin crear integraciones de API personalizadas. En lugar de crear flujos de trabajo de Integration Builder y administrar las credenciales de la API, conecta eesel directamente a su cuenta de Zendesk a través de un simple flujo de OAuth.
Aquí está la diferencia en el enfoque. Con el método de la API de Sunshine Conversations, está construyendo la infraestructura: creando claves de API, escribiendo consultas JSONata, manejando escenarios de error y manteniendo la integración a lo largo del tiempo. Con nuestro enfoque, esa infraestructura ya está construida. Usted se enfoca en configurar el comportamiento de la IA mientras nosotros manejamos la fontanería de datos.
Cuando conecta eesel a Zendesk, accedemos automáticamente a los perfiles de usuario, el historial de tickets y los campos personalizados sin requerir que cree llamadas API separadas. Define las reglas de escalamiento en inglés sencillo como "Si el cliente menciona un problema de facturación, páselo al equipo de finanzas" en lugar de construir una lógica condicional compleja en el Integration Builder.
| Caso de uso | API de Sunshine Conversations | eesel AI |
|---|---|---|
| Tiempo de configuración | Días a semanas | Minutos |
| Requisitos técnicos | Recursos de desarrollador | Ninguno |
| Integraciones de canales personalizados | Flexibilidad total | Canales estándar |
| Orquestación de API de varios pasos | Control total | Pre-construido |
| Sobrecarga de mantenimiento | En curso | Mínima |
Si está construyendo soluciones altamente personalizadas con requisitos de canal únicos u orquestación compleja de múltiples sistemas, el enfoque de la API de Sunshine Conversations le brinda la flexibilidad que necesita. Pero si su objetivo es implementar soporte al cliente impulsado por IA rápidamente sin recursos de ingeniería, nuestra integración de Zendesk maneja la complejidad por usted.
Comience a construir experiencias personalizadas de agentes de IA
Ahora tiene la imagen completa para acceder a los datos de usuario en Zendesk Sunshine Conversations. La arquitectura involucra tres fuentes de datos principales: la API de User para la información del perfil, la API de Clients para los detalles específicos del canal como los números de teléfono y los metadatos de la conversación para el contexto personalizado de sus aplicaciones.
El patrón de implementación es consistente en todos los casos de uso: cree integraciones de API en el Integration Builder, utilice JSONata para extraer los campos que necesita, almacénelos como parámetros de sesión y haga referencia a esos parámetros en sus flujos de diálogo. Con el proceso de dos pasos de obtener primero los participantes y luego los detalles del usuario, puede acceder a todo, desde nombres básicos hasta números de teléfono de WhatsApp.
Antes de comenzar a construir, audite qué datos de usuario necesita realmente. Es fácil dejarse llevar recopilando todos los campos disponibles, pero concéntrese en los datos que realmente mejoran la experiencia del cliente. Un saludo personalizado utilizando el nombre del cliente tiene más impacto que mostrar su ID de usuario interno.
Si está listo para implementar pero le preocupa el esfuerzo de desarrollo, pruebe nuestra plataforma junto con su configuración de Zendesk. Puede comparar enfoques y elegir lo que mejor se adapte a las capacidades y el cronograma de su equipo.
Compartir esta entrada
Article by
