Descripción general de la API de Zendesk Sunshine Conversations: Una guía para desarrolladores para 2026

Si está creando una solución de mensajería para clientes, probablemente se haya enfrentado a la pesadilla de administrar integraciones separadas para WhatsApp, Facebook Messenger, SMS y chat en la aplicación. Cada canal tiene su propia API, documentación y peculiaridades. La carga de mantenimiento se multiplica con cada canal que agrega.

Zendesk Sunshine Conversations resuelve esto al proporcionar una única API REST que unifica más de 14 canales de mensajería. Originalmente desarrollado como Smooch.io antes de que Zendesk lo adquiriera, Sunshine Conversations permite a los desarrolladores construir una vez e implementar en todas las principales plataformas de mensajería.

En esta guía, analizaré exactamente lo que ofrece la API de Sunshine Conversations, cómo funciona y lo que necesita saber para comenzar. También mostraré cómo eesel AI proporciona una alternativa para los equipos que desean mensajería impulsada por IA sin crear integraciones personalizadas.

¿Qué es Zendesk Sunshine Conversations?

Sunshine Conversations es una plataforma de mensajería multicanal que se encuentra en el corazón del ecosistema de experiencia del cliente de Zendesk. Actúa como una capa de traducción entre su aplicación y docenas de canales de mensajería, normalizando las peculiaridades de cada plataforma en una API consistente.

La plataforma atiende a dos audiencias principales:

Para los desarrolladores, elimina la necesidad de crear integraciones separadas para cada canal de mensajería. En lugar de aprender las idiosincrasias de la API de WhatsApp Business, los formatos de webhook de Facebook Messenger y las peculiaridades del proveedor de SMS, se integra una vez con Sunshine Conversations y la plataforma se encarga del resto.

Para las empresas, permite conectar herramientas existentes como mesas de ayuda, CRM y plataformas de bots a los clientes a través de sus canales de mensajería preferidos, a menudo sin escribir código.

El legado de Smooch.io

Sunshine Conversations comenzó su vida como Smooch.io, una plataforma de mensajería independiente que Zendesk adquirió. Todavía encontrará referencias a Smooch en la documentación heredada y en algunos repositorios de SDK. La plataforma central se ha integrado completamente en la Suite de Zendesk, pero la arquitectura de la API y muchos puntos finales conservan el ADN de Smooch.

Para los clientes de Zendesk con licencia, la URL base es https://{subdomain}.zendesk.com/sc. Las cuentas heredadas de Sunshine Conversations todavía usan https://api.smooch.io.

Capacidades y arquitectura centrales de la API

La API de Sunshine Conversations sigue los principios de REST con cuerpos de solicitud y respuesta JSON. La versión actual es v2, aunque v1.1 sigue siendo compatible con las integraciones existentes.

Puntos finales y recursos clave

La API se centra en varios recursos centrales:

Todos los puntos finales utilizan métodos HTTP estándar: GET para la recuperación, POST para la creación, PATCH para las actualizaciones y DELETE para la eliminación. La API devuelve formatos de error consistentes con códigos de estado HTTP y objetos de error descriptivos.

Paginación y límites

Sunshine Conversations utiliza la paginación basada en cursor en lugar de la paginación de desplazamiento. Este enfoque evita problemas de rendimiento con grandes conjuntos de datos al devolver un puntero a un elemento específico en lugar de números de página.

Puede usar los parámetros de consulta page[after] o page[before] para navegar hacia adelante o hacia atrás a través de los resultados. Un parámetro opcional page[size] controla el número de registros devueltos por solicitud.

Tenga en cuenta estos límites estrictos:

Cuando alcanza los límites de velocidad, la API devuelve un estado 429 Demasiadas solicitudes. Implemente una retirada exponencial con fluctuación en lugar de intervalos de reintento fijos. Se esperan picos de uso y los límites están diseñados para ser generosos para las operaciones normales.

Autenticación y seguridad

Sunshine Conversations admite dos métodos de autenticación, cada uno adecuado para diferentes casos de uso.

Autenticación básica

Para las llamadas API de servidor a servidor, la autenticación básica es el enfoque más simple. Utiliza su ID de clave API como nombre de usuario y el secreto como contraseña en el formato estándar de autenticación básica HTTP.

Este método funciona bien para las integraciones de backend donde está realizando llamadas desde su servidor a la API de Sunshine Conversations. Es sencillo de implementar y depurar.

Autenticación JWT

Los tokens web JSON proporcionan una opción de autenticación más flexible, particularmente útil cuando necesita limitar el acceso o cuando pasa credenciales a través de canales menos seguros.

Para generar un JWT, necesita:

• Encabezado con algoritmo (HS256) e ID de clave
• Carga útil con reclamo de alcance (cuenta, aplicación o integración)
• Firma usando su secreto de API

Los JWT se transmiten en el encabezado de autorización con el prefijo Bearer: Authorization: Bearer your-jwt-token.

Alcances de autorización

La API utiliza tres alcances de autorización principales que determinan qué operaciones están permitidas:

Las claves API siguen una convención de nomenclatura que indica su alcance: las claves de cuenta comienzan con act_, las claves de cuenta de servicio con svc_ y las claves de aplicación con app_.

Canales de mensajería compatibles

Sunshine Conversations admite la gama más completa de canales de mensajería de la industria. Se puede acceder a todos los canales a través de la misma API, y la plataforma se encarga de la traducción entre los formatos específicos del canal y la API unificada.

Aplicaciones de mensajería de terceros

• API de WhatsApp Business - Soporte completo para mensajería empresarial, plantillas y medios enriquecidos
• Facebook Messenger - Integración completa con botones, respuestas rápidas y vistas web
• Instagram Direct - Mensajería a través de cuentas comerciales de Instagram
• Apple Messages for Business - Integración con la plataforma de mensajería empresarial de Apple
• LINE, Telegram, Viber - Soporte completo para las principales plataformas de mensajería asiáticas y europeas
• Twitter DM - Mensajería directa a través de Twitter
• WeChat - Soporte para la plataforma de mensajería dominante de China

Proveedores de SMS y voz

• Twilio - Integración de SMS a través de la infraestructura de Twilio
• MessageBird - Integración alternativa de proveedor de SMS

SDK creados por Zendesk

• Web Messenger - Widget de chat integrable para sitios web
• Android SDK - Mensajería nativa en la aplicación de Android
• iOS SDK - Mensajería nativa en la aplicación de iOS
• Unity SDK - Integración de aplicaciones de juegos y 3D

La plataforma admite funciones de mensajería enriquecida en todos los canales donde estén disponibles, incluidos mensajes estructurados, respuestas rápidas, carruseles e intercambio de archivos. Cuando los canales agregan nuevas funciones, Sunshine Conversations normalmente se actualiza para admitirlas con cambios mínimos de código requeridos de su parte.

Herramientas de desarrollo y SDK

Si bien puede interactuar con la API de Sunshine Conversations directamente a través de HTTP, Zendesk proporciona SDK oficiales que envuelven la API y manejan la autenticación, el manejo de errores y el formato de solicitud.

SDK oficiales

El SDK de Java recibe el mantenimiento más activo de Zendesk. Los SDK de Ruby y Python se generan automáticamente a partir de la especificación OpenAPI, lo que garantiza que se mantengan actualizados con los cambios de la API, pero que potencialmente carezcan de ergonomía hecha a mano.

Herramientas de desarrollo

Para pruebas y exploración, Zendesk proporciona una colección Postman que incluye todos los puntos finales con solicitudes de ejemplo. La especificación OpenAPI está disponible públicamente para generar clientes o documentación personalizados.

Integración de Webhook

El manejo de eventos en tiempo real se realiza a través de webhooks. Su servidor expone un punto final que recibe solicitudes POST cuando ocurren eventos, como mensajes entrantes, confirmaciones de entrega o cambios en el estado de la conversación.

Los desencadenadores de webhook comunes incluyen:

Tendrá que verificar las firmas de webhook utilizando el secreto compartido proporcionado cuando crea la integración de webhook para asegurarse de que los eventos provengan genuinamente de Sunshine Conversations.

Integración con el ecosistema de Zendesk

Sunshine Conversations no existe de forma aislada. Está profundamente integrado en la plataforma Zendesk más amplia, lo que puede acelerar el desarrollo o proporcionar enfoques alternativos según su caso de uso.

Web Widget

El Web Widget proporciona una interfaz de chat orientada al cliente que se integra en su sitio web o centro de ayuda. Utiliza Sunshine Conversations por debajo, por lo que las conversaciones iniciadas a través del widget fluyen a través de la misma API que utiliza para otros canales.

Espacio de trabajo del agente

Cuando las conversaciones necesitan intervención humana, aparecen en el espacio de trabajo del agente de Zendesk como tickets. Los agentes pueden responder directamente y sus mensajes fluyen de regreso a través de Sunshine Conversations al cliente en su canal original. Esto le brinda una interfaz de agente unificada incluso cuando los clientes están distribuidos en una docena de plataformas de mensajería.

Switchboard

El Switchboard controla el enrutamiento de conversaciones entre bots, sistemas de IA y agentes humanos. Puede pasar el control entre sistemas mediante programación mientras mantiene el contexto de la conversación. Esto permite flujos de trabajo sofisticados como el triaje primero por bot con escalamiento perfecto a humanos.

En eesel AI, aprovechamos estos puntos de integración para proporcionar un servicio al cliente impulsado por IA que funciona de forma nativa dentro de Zendesk. Nuestros agentes de IA pueden manejar conversaciones a través de Sunshine Conversations, escalar a agentes humanos cuando sea necesario y mantener el contexto completo durante toda la interacción.

Precios y acceso de Zendesk Suite

El acceso a la API de Sunshine Conversations requiere planes específicos de Zendesk Suite. No todos los niveles incluyen todas las capacidades de la plataforma.

Distinción clave: Suite Team y Growth incluyen mensajería a través del Web Widget, pero no brindan acceso completo a la API para integraciones personalizadas. Para crear sus propias integraciones con la API de Sunshine Conversations, necesita Suite Professional o Enterprise.

Los usuarios activos mensuales (MAU) representan a los usuarios únicos que envían o reciben mensajes en un período de 30 días. Si excede sus MAU incluidos, hay paquetes adicionales disponibles a aproximadamente $50 por 2500 MAU.

Fuente: Precios de Zendesk

Comenzando con el desarrollo de Sunshine Conversations

Si está listo para construir con Sunshine Conversations, esto es lo que necesita para comenzar.

Requisitos previos

1. Zendesk Suite Professional o Enterprise - Requerido para acceso completo a la API
2. Acceso al Centro de administración - Para generar claves API y configurar canales
3. Entorno de desarrollo - Un servidor o función en la nube para recibir webhooks
4. Comprensión básica de las API REST - Para realizar llamadas API y manejar respuestas

Pasos de inicio rápido

1. Generar claves API - En el Centro de administración, navegue a Aplicaciones e integraciones > API > API de conversaciones. Cree una nueva clave y almacene de forma segura el ID de la aplicación, el ID de la clave y el secreto.

2. Configurar un punto final de webhook - Cree un punto final HTTPS de acceso público que pueda recibir solicitudes POST. Para el desarrollo local, herramientas como ngrok pueden crear túneles a su máquina.

3. Configurar su primer canal - En el Centro de administración, habilite un canal de mensajería (Web Widget es el más fácil para comenzar) y conéctelo a su aplicación Sunshine Conversations.

4. Probar la integración - Envíe un mensaje a través del canal elegido y verifique que llegue a su punto final de webhook. Luego, intente enviar una respuesta a través de la API.

Para obtener un tutorial más detallado, consulte nuestra guía completa para comenzar.

eesel AI: Mensajería impulsada por IA sin desarrollo personalizado

La creación de integraciones personalizadas con Sunshine Conversations requiere importantes recursos de desarrollo. Si su objetivo es el servicio al cliente impulsado por IA en lugar de construir una plataforma de mensajería personalizada, considere si necesita construir algo.

En eesel AI, proporcionamos agentes de IA que se integran directamente con Zendesk, manejando la complejidad de Sunshine Conversations, la orquestación de Switchboard y la mensajería multicanal sin requerir desarrollo personalizado. Obtiene un servicio al cliente impulsado por IA que funciona en todos los canales de mensajería, con escalamiento humano e integración completa de Zendesk, sin escribir código.

Para los equipos que buscan agregar capacidades de chat de IA a su mesa de ayuda existente, nuestro chatbot de IA funciona en todos los canales de mensajería con el mismo enfoque unificado que Sunshine Conversations, pero sin la sobrecarga de desarrollo. Si necesita ayuda para administrar el volumen de tickets, AI Triage enruta, etiqueta y prioriza automáticamente los tickets antes de que lleguen a sus agentes.