zendesk-sunshine-conversations-custom-integration

{
  "title": "Cómo construir una integración personalizada de Zendesk Sunshine Conversations",
  "slug": "zendesk-sunshine-conversations-custom-integration",
  "locale": "es",
  "date": "2026-02-20",
  "updated": "2026-02-20",
  "template": "default",
  "excerpt": "Construye integraciones personalizadas con Zendesk Sunshine Conversations utilizando esta guía técnica que cubre la configuración de la API, la configuración de webhooks, las operaciones de Switchboard y las mejores prácticas.",
  "categories": [
    "Blog Writer AI"
  ],
  "tags": [
    "Zendesk",
    "Sunshine Conversations",
    "API Integration",
    "Webhooks",
    "Customer Support"
  ],
  "readTime": 12,
  "author": 16,
  "reviewer": 14,
  "seo": {
    "title": "Cómo construir una integración personalizada de Zendesk Sunshine Conversations",
    "description": "Construye integraciones personalizadas con Zendesk Sunshine Conversations utilizando esta guía técnica que cubre la configuración de la API, la configuración de webhooks, las operaciones de Switchboard y las mejores prácticas.",
    "image": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-37d54b3d-f442-4a59-a37a-54fa5c58865d"
  },
  "coverImage": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-37d54b3d-f442-4a59-a37a-54fa5c58865d",
  "coverImageAlt": "Imagen del banner para Cómo construir una integración personalizada de Zendesk Sunshine Conversations",
  "coverImageWidth": 1920,
  "coverImageHeight": 1080,
  "faqs": {
    "heading": "Preguntas Frecuentes",
    "type": "blog",
    "answerType": "html",
    "faqs": [
      {
        "question": "¿Necesitas experiencia en programación para construir una integración personalizada de Zendesk Sunshine Conversations?",
        "answer": "Sí, construir una integración personalizada requiere conocimientos de programación, específicamente con APIs REST y webhooks. Necesitarás escribir código del lado del servidor para recibir eventos, procesar mensajes y enviar respuestas. Si no tienes recursos de desarrollo, considera soluciones pre-construidas como eesel AI que se integran sin necesidad de programar."
      },
      {
        "question": "¿Qué lenguajes de programación funcionan mejor para una integración personalizada de Zendesk Sunshine Conversations?",
        "answer": "Cualquier lenguaje que pueda manejar peticiones HTTP y JSON funcionará. Node.js, Python y Ruby son opciones populares con buen soporte de bibliotecas. Zendesk proporciona SDKs oficiales para Ruby y Java, pero puedes usar cualquier lenguaje que se ajuste a tu pila."
      },
      {
        "question": "¿Cuánto cuesta una integración personalizada de Zendesk Sunshine Conversations?",
        "answer": "La integración en sí es gratuita, pero necesitas un plan Zendesk Suite Professional ($115/agente/mes anual) o superior para acceder a la API. Los costos adicionales incluyen los excedentes de MAU (usuarios activos mensuales) ($50 por cada 2,500 MAUs más allá de los 1,000 incluidos) y cualquier infraestructura para alojar tu servidor de webhook."
      },
      {
        "question": "¿Puede una integración personalizada de Zendesk Sunshine Conversations manejar múltiples canales de mensajería?",
        "answer": "Sí. Una vez que tu integración está construida, funciona con cualquier canal conectado a Sunshine Conversations incluyendo WhatsApp, Facebook Messenger, Instagram, chat web y SMS. Tu código recibe los eventos de la misma manera independientemente del canal que utilice el cliente."
      },
      {
        "question": "¿Cómo pruebas una integración personalizada de Zendesk Sunshine Conversations antes de ponerla en marcha?",
        "answer": "Usa ngrok para exponer tu servidor local durante el desarrollo. Crea conversaciones de prueba a través del widget web o los canales conectados. Para pruebas más exhaustivas, ejecuta simulaciones con datos históricos de conversaciones. Zendesk también proporciona un entorno de pruebas (sandbox) en los planes Enterprise."
      },
      {
        "question": "¿Cuáles son los límites de velocidad para una integración personalizada de Zendesk Sunshine Conversations?",
        "answer": "El límite de velocidad predeterminado es de 100 solicitudes por minuto. Si excedes esto, recibirás un código de estado 429 con un encabezado Retry-After. Para casos de uso de alto volumen, contacta a Zendesk para aumentar tus límites. Siempre implementa un retroceso exponencial (exponential backoff) en tu lógica de reintento."
      }
    ],
    "supportLink": null
  }
}
---

Construir una integración personalizada con [Zendesk Sunshine Conversations](https://www.zendesk.com/messaging/) te permite crear experiencias de mensajería a medida que se ajusten a las necesidades exactas de tu negocio. Ya sea que quieras conectar un CRM propietario, construir un bot especializado u orquestar flujos de conversación complejos, la [API de Sunshine Conversations](https://developer.zendesk.com/api-reference/conversations/) proporciona la base que necesitas.

Esta guía te lleva a través de todo, desde la configuración inicial hasta el despliegue en producción. Al final, tendrás un servidor de webhook funcional que puede recibir mensajes, responder inteligentemente y transferir a agentes humanos cuando sea necesario. Para referencia oficial, consulta la [documentación de la API de Zendesk](https://developer.zendesk.com/api-reference/conversations/).

Si prefieres saltarte el trabajo de ingeniería, [eesel AI](https://www.eesel.ai) ofrece una alternativa sin código que se conecta a Zendesk en minutos y gestiona las conversaciones de forma autónoma.

![Diagrama de la arquitectura de la integración de la API de Zendesk Sunshine Conversations](https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/7ef06c69-2578-47e2-b263-14872fd6462e)

*Zendesk Sunshine Conversations conecta los canales de mensajería con las aplicaciones de tu negocio a través de webhooks y APIs.*

## Lo que necesitarás

Antes de sumergirte, asegúrate de tener lo siguiente en su lugar.

**Requisitos de Zendesk:**
- Un [plan Zendesk Suite Professional o Enterprise](https://www.zendesk.com/pricing/) (el acceso a la API de Sunshine Conversations requiere estos niveles)
- Acceso de administrador a tu cuenta de Zendesk
- Al menos 1,000 Usuarios Activos Mensuales (MAUs) incluidos en tu plan (paquetes de MAU adicionales disponibles a $50 por cada 2,500 MAUs)

**Requisitos técnicos:**
- Un entorno de servidor (se recomienda Node.js para esta guía)
- [ngrok](https://ngrok.com/) para pruebas locales de webhook
- Conocimientos básicos de APIs REST y webhooks
- Endpoint HTTPS para producción

| Plan | Precio Anual | Acceso a Sunshine | MAUs Incluidos |
|------|--------------|-----------------|---------------|
| Suite Team | $55/agente/mes | Mensajería básica solamente | N/A |
| Suite Professional | $115/agente/mes | Acceso completo a la API | 1,000 |
| Suite Enterprise | $169/agente/mes | Acceso completo a la API | 1,000 |

## Entendiendo la arquitectura de Sunshine Conversations

[Sunshine Conversations](https://support.zendesk.com/hc/en-us/articles/6380323137306) es la plataforma de mensajería unificada de Zendesk. Originalmente Smooch.io (adquirida por Zendesk en 2019), ahora impulsa la mensajería en toda la Suite de Zendesk. La arquitectura se basa en algunos conceptos clave que necesitas entender antes de construir.

![Arquitectura de la API de Sunshine Conversations como un centro que enruta mensajes entre clientes e integraciones](https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/66c3f854-f5a6-4a79-a8cb-b87f53106e62)

**Apps (Aplicaciones):** Cada aplicación representa un negocio o marca. Crearás una aplicación en el Centro de Administración que contiene todos tus datos de conversación.

**Integrations (Integraciones):** Estas son las conexiones entre Sunshine Conversations y sistemas externos. Las integraciones personalizadas utilizan webhooks para enviar y recibir mensajes.

**Conversations (Conversaciones):** Una conversación es un hilo de mensajes entre un usuario y tu negocio. Las conversaciones persisten a través de los canales (un usuario puede comenzar en el chat web y continuar en WhatsApp).

**Switchboard (Centralita):** Esto controla quién "posee" una conversación en cualquier momento. La Centralita enruta las conversaciones entre bots, agentes e integraciones.

**Authentication (Autenticación):** La API utiliza Autenticación Básica (ID de Clave como nombre de usuario, Secreto como contraseña) o tokens JWT para una mayor seguridad.

El flujo funciona así: un cliente envía un mensaje a través de cualquier canal conectado (widget web, WhatsApp, etc.). Sunshine Conversations recibe el mensaje y lo reenvía a tu integración de webhook. Tu servidor procesa el mensaje, decide cómo responder y envía una respuesta a través de la API. Si es necesario, tu integración puede transferir el control a un agente humano a través de la [Centralita](https://docs.smooch.io/rest/).

## Paso 1: Crea tu aplicación de Sunshine Conversations y las claves de la API

Primero, necesitas crear una aplicación y generar credenciales de la API.

Navega al Centro de Administración de Zendesk. Ve a **Aplicaciones e integraciones** > **APIs** > **API de Conversaciones**.

Haz clic en **Crear Clave de API** y dale un nombre descriptivo como "Integración de Webhook de Producción". Recibirás tres piezas de información:

- **ID de la App (App ID):** Un identificador único para tu aplicación
- **ID de la Clave (Key ID):** Se utiliza como el nombre de usuario para la autenticación de la API
- **Clave Secreta (Secret Key):** Se utiliza como la contraseña para la autenticación de la API

Guarda estas credenciales de forma segura. Las necesitarás para cada llamada a la API. La Clave Secreta se muestra solo una vez. Si la pierdes, tendrás que generar un nuevo par de claves.

Configura tus variables de entorno para mantener las credenciales fuera de tu código:

```bash
export SUNSHINE_APP_ID="your_app_id"
export SUNSHINE_KEY_ID="your_key_id"
export SUNSHINE_SECRET="your_secret_key"

Paso 2: Configura tu integración de webhook

Ahora crea la integración de webhook que recibirá los eventos de los mensajes.

En el Centro de Administración, ve a Integraciones > Integraciones de Conversaciones.

Haz clic en Crear Integración y selecciona Personalizada (Custom) como el tipo. Configura lo siguiente:

URL de Destino (Target URL): Para el desarrollo local, utiliza tu URL de ngrok (lo configuraremos en el siguiente paso). Para producción, utiliza tu endpoint HTTPS.

Triggers (Disparadores): Selecciona qué eventos quieres recibir. Como mínimo, habilita:

• conversation:message - Recibe todos los mensajes entrantes
• postback - Recibe los clics de los botones y las respuestas rápidas
• conversation:start - Notifica cuando comienza una nueva conversación

Secret (Secreto): Genera una cadena aleatoria para la verificación de la firma del webhook. Esto asegura que las solicitudes realmente provengan de Zendesk.

Guarda tu ID de Webhook (mostrado después de la creación) y el Secreto Compartido (Shared Secret) que configuraste. Necesitarás ambos para la verificación de la firma.

Paso 3: Construye tu servidor de webhook

Construyamos un simple servidor Express.js que recibe y responde a los mensajes.

Primero, inicializa tu proyecto:

mkdir sunshine-integration
cd sunshine-integration
npm init -y
npm install express crypto dotenv

Crea un archivo index.js:

require('dotenv').config();
const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.raw({ type: 'application/json' }));

// Webhook verification middleware
function verifyWebhook(req, res, next) {
  const signature = req.headers['x-smooch-signature'];
  const secret = process.env.WEBHOOK_SECRET;

  const hash = crypto
    .createHmac('sha256', secret)
    .update(req.body)
    .digest('hex');

  if (hash !== signature) {
    return res.status(401).send('Unauthorized');
  }
  next();
}

// Handle incoming messages
app.post('/webhook', verifyWebhook, async (req, res) => {
  const event = JSON.parse(req.body);

  // Acknowledge receipt immediately
  res.status(200).send('OK');

  // Process the event
  if (event.trigger === 'message:appUser') {
    await handleUserMessage(event);
  }
});

async function handleUserMessage(event) {
  const message = event.messages[0];
  const userId = event.appUser._id;
  const conversationId = event.conversation._id;

  console.log(`Received: ${message.text} from ${userId}`);

  // Simple echo response (replace with your logic)
  await sendMessage(conversationId, `You said: ${message.text}`);
}

async function sendMessage(conversationId, text) {
  const auth = Buffer.from(
    `${process.env.SUNSHINE_KEY_ID}:${process.env.SUNSHINE_SECRET}`
  ).toString('base64');

  const response = await fetch(
    `https://api.smooch.io/v2/apps/${process.env.SUNSHINE_APP_ID}/conversations/${conversationId}/messages`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Basic ${auth}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        author: { type: 'business' },
        content: { type: 'text', text: text }
      })
    }
  );

  if (!response.ok) {
    console.error('Failed to send message:', await response.text());
  }
}

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

Crea un archivo .env:

SUNSHINE_APP_ID=your_app_id
SUNSHINE_KEY_ID=your_key_id
SUNSHINE_SECRET=your_secret_key
WEBHOOK_SECRET=your_webhook_secret

Inicia tu servidor:

node index.js

Paso 4: Prueba localmente con ngrok

Dado que Sunshine Conversations requiere un endpoint HTTPS público, utiliza ngrok para exponer tu servidor local.

Instala ngrok e inicia un túnel:

ngrok http 3000

Copia la URL HTTPS (algo como https://abc123.ngrok.io). Actualiza tu integración de webhook en el Centro de Administración con esta URL como la URL de Destino.

Prueba tu integración enviando un mensaje a través del Widget Web de Zendesk o cualquier canal conectado. Deberías ver el mensaje registrado en la consola de tu servidor, y el bot debería repetir el mensaje.

Paso 5: Configura la Centralita (Switchboard) para transferencias de bot a agente

La Centralita controla cuándo tu bot maneja los mensajes versus cuándo los agentes humanos toman el control. Esto es esencial para las implementaciones de producción.

Conceptos clave de la Centralita:

• Pass Control (Pasar el Control): Transfiere inmediatamente la propiedad a otra integración
• Offer Control (Ofrecer el Control): Comparte el control hasta que el objetivo lo acepte
• Release Control (Liberar el Control): Devuelve la conversación a su estado predeterminado

Para encontrar tu ID de Centralita:

async function getSwitchboardId() {
  const auth = Buffer.from(
    `${process.env.SUNSHINE_KEY_ID}:${process.env.SUNSHINE_SECRET}`
  ).toString('base64');

  const response = await fetch(
    `https://api.smooch.io/v2/apps/${process.env.SUNSHINE_APP_ID}/switchboards`,
    {
      headers: { 'Authorization': `Basic ${auth}` }
    }
  );

  const data = await response.json();
  return data.switchboards[0].id;
}

Para escalar a un agente humano:

async function escalateToAgent(conversationId, switchboardId, metadata = {}) {
  const auth = Buffer.from(
    `${process.env.SUNSHINE_KEY_ID}:${process.env.SUNSHINE_SECRET}`
  ).toString('base64');

  await fetch(
    `https://api.smooch.io/v2/apps/${process.env.SUNSHINE_APP_ID}/conversations/${conversationId}/switchboard/passControl`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Basic ${auth}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        switchboardIntegration: 'zd:agentWorkspace', // Zendesk Agent Workspace
        metadata: {
          priority: 'high',
          topic: metadata.topic || 'general',
          ...metadata
        }
      })
    }
  );
}

Cuando pasas el control con metadatos, Zendesk completa automáticamente los campos del ticket, establece la prioridad y enruta al equipo apropiado según tus disparadores.

Paso 6: Conecta los canales de mensajería

Tu integración funciona con cualquier canal conectado a Sunshine Conversations. Los canales disponibles incluyen:

• Widget Web (integrado)
• API de WhatsApp Business
• Facebook Messenger
• Instagram
• Apple Messages for Business
• LINE
• Telegram
• SMS a través de Twilio o MessageBird
• SDKs de Android e iOS

Para agregar un canal, ve a Centro de Administración > Canales > [Nombre del Canal] y sigue los pasos de autenticación. Cada canal tiene requisitos específicos:

• WhatsApp: Requiere la verificación de Meta Business y una cuenta de la API de WhatsApp Business
• Facebook/Instagram: Se conecta a través de tu Administrador Comercial de Facebook
• SMS: Requiere una cuenta de Twilio o MessageBird con un número de teléfono

Una vez conectado, todos los mensajes fluyen a través del mismo endpoint de webhook independientemente del canal. Tu código no necesita cambiar para soportar nuevos canales.

Pruebas y depuración de tu integración

Antes de poner en marcha, prueba a fondo tu integración.

Mejores prácticas de desarrollo local:

• Utiliza la función de repetición de ngrok para reenviar webhooks durante la depuración
• Implementa un registro exhaustivo para cada evento recibido y acción tomada
• Crea conversaciones de prueba y verifica el flujo completo desde el mensaje hasta la respuesta

Errores comunes y soluciones:

Error	Causa	Solución
401 No autorizado	Firma de webhook inválida	Verifica que tu WEBHOOK_SECRET coincida con la configuración de la integración
429 Demasiadas solicitudes	Límite de velocidad excedido	Implementa lógica de reintento con retroceso exponencial
403 Prohibido	Credenciales de API inválidas	Verifica tu ID de Clave y Secreto
Tiempo de espera del webhook	Respuesta del servidor > 10 segundos	Reconoce el webhook inmediatamente, procesa asíncronamente

Limitación de velocidad: Sunshine Conversations limita las solicitudes de la API a 100 por minuto de forma predeterminada. Implementa un manejo adecuado:

if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After');
  await delay(retryAfter * 1000);
  // Retry the request
}

Límites de tamaño de la conversación: Las conversaciones tienen un límite de 30,000 mensajes. Archiva las conversaciones antiguas para mantenerte por debajo de este límite.

Mejores prácticas de seguridad

Las integraciones de producción requieren medidas de seguridad adicionales.

Almacenamiento de credenciales: Nunca confirmes las credenciales al control de versiones. Utiliza variables de entorno o un administrador de secretos como AWS Secrets Manager o HashiCorp Vault. Zendesk sigue prácticas de seguridad estándar de la industria para proteger tus datos.

Verificación de la firma del webhook: Siempre verifica el encabezado X-Smooch-Signature. Sin esto, cualquiera puede enviar webhooks falsos a tu endpoint.

Solo HTTPS: Sunshine Conversations requiere HTTPS para las URLs de webhook en producción. Utiliza un certificado SSL válido.

Autenticación JWT: Para una mayor seguridad, cambia de Autenticación Básica a tokens JWT:

function generateJWT() {
  const header = { alg: 'HS256', typ: 'JWT' };
  const now = Math.floor(Date.now() / 1000);
  const payload = {
    scope: 'app',
    iat: now,
    exp: now + 600 // 10 minutes
  };

  const encodedHeader = Buffer.from(JSON.stringify(header)).toString('base64url');
  const encodedPayload = Buffer.from(JSON.stringify(payload)).toString('base64url');
  const signature = crypto
    .createHmac('sha256', process.env.SUNSHINE_SECRET)
    .update(`${encodedHeader}.${encodedPayload}`)
    .digest('base64url');

  return `${encodedHeader}.${encodedPayload}.${signature}`;
}

Rotación de claves de API: Genera nuevas claves periódicamente y revoca las antiguas. Sunshine Conversations soporta múltiples claves activas para la rotación sin tiempo de inactividad.

Despliegue a producción

Cuando estés listo para poner en marcha, sigue esta lista de verificación.

Lista de verificación de despliegue a producción:

• Mueve de ngrok a un endpoint HTTPS permanente
• Implementa un manejo de errores adecuado y lógica de reintento
• Configura la monitorización y las alertas para los fallos de webhook
• Configura la agregación de registros para la depuración
• Prueba las transferencias de la Centralita con agentes reales
• Verifica que la limitación de velocidad no afectará tu caso de uso
• Documenta tus políticas de escalada

Recomendaciones de monitorización:

Realiza un seguimiento de estas métricas para asegurar una integración saludable:

• Tasa de éxito de la entrega de webhook (objetivo: >99%)
• Tiempo de respuesta promedio (mantener por debajo de 5 segundos)
• Tasa de error por tipo de error
• Volumen de conversación por canal

Configura alertas para las entregas de webhook fallidas, las altas tasas de error y la aproximación a los límites de velocidad.

Alternativa: eesel AI para una implementación más rápida

Construir una integración personalizada te da un control completo, pero requiere un tiempo de desarrollo significativo y un mantenimiento continuo. Si necesitas mensajería impulsada por IA sin la sobrecarga de ingeniería, considera eesel AI como una alternativa.

eesel AI se conecta directamente a Zendesk y gestiona todo el flujo de conversación automáticamente. En lugar de construir webhooks y lógica de Centralita, simplemente:

1. Conecta eesel AI a tu cuenta de Zendesk (integración con un solo clic)
2. Entrena al Agente de IA en tus tickets pasados, centro de ayuda y documentación
3. Configura las reglas de escalada en lenguaje sencillo ("Escalar las disputas de facturación al equipo de Finanzas")
4. Prueba en un sandbox con tickets pasados antes de poner en marcha

Aspecto	Integración Personalizada	eesel AI
Tiempo de configuración	2-4 semanas	Minutos
Experiencia técnica requerida	Alta (APIs, webhooks)	Baja (sin código)
Capacidades de IA	Construye la tuya propia	Pre-construida con LLM
Mantenimiento	Desarrollo continuo	Servicio gestionado
Modelo de precios	Zendesk MAU + costos de desarrollo	Por interacción ($239-$639/mes)

Las integraciones personalizadas tienen sentido cuando tienes sistemas propietarios que no se ajustan a los patrones estándar o necesitas flujos de conversación altamente especializados. Para la mayoría de los equipos que buscan agregar mensajería de IA a Zendesk, eesel AI ofrece resultados más rápidos con menos mantenimiento. Puedes ver eesel en acción o probarlo gratis.

Comienza a construir con Zendesk Sunshine Conversations

Ahora tienes todo lo que necesitas para construir una integración personalizada con Zendesk Sunshine Conversations. Desde la creación de claves de API y la configuración de webhooks hasta el manejo de la Centralita y el despliegue a producción, la base está en su lugar.

Los siguientes pasos dependen de tu caso de uso específico. Podrías integrarte con tu CRM para extraer datos de clientes, conectarte a una base de conocimientos para obtener respuestas inteligentes o construir una lógica de enrutamiento personalizada basada en el contenido del mensaje.

Si la ruta personalizada se siente como más ingeniería de la que tu equipo puede asumir en este momento, podemos ayudar. Nuestros agentes de IA se integran con Zendesk en minutos y gestionan las conversaciones de forma autónoma mientras escalan a tu equipo cuando es necesario. Puedes probar eesel gratis y probarlo en tickets pasados para ver exactamente cómo se desempeñaría antes de ponerlo en marcha.