zendesk-switchboard-integration-custom-bot
eesel Team
Last edited 20 febrero 2026
{
"title": "Cómo construir un bot personalizado con Zendesk Switchboard: Una guía para desarrolladores",
"slug": "zendesk-switchboard-integration-custom-bot",
"locale": "es",
"date": "2026-02-20",
"updated": "2026-02-20",
"template": "default",
"excerpt": "Construye un bot personalizado para Zendesk Switchboard con esta guía técnica. Cubre las credenciales de la API, la configuración de la integración, el manejo de webhooks y el control de la conversación.",
"categories": [
"Blog Writer AI"
],
"tags": [
"Zendesk",
"Switchboard",
"Custom Bot",
"Integration",
"Sunshine Conversations"
],
"readTime": 11,
"author": 16,
"reviewer": 14,
"seo": {
"title": "Cómo construir un bot personalizado con Zendesk Switchboard: Una guía para desarrolladores",
"description": "Construye un bot personalizado para Zendesk Switchboard con esta guía técnica. Cubre las credenciales de la API, la configuración de la integración, el manejo de webhooks y el control de la conversación.",
"image": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-d9640095-198e-4779-8d67-74cf3eaf1b32"
},
"coverImage": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-d9640095-198e-4779-8d67-74cf3eaf1b32",
"coverImageAlt": "Imagen del banner para Cómo construir un bot personalizado con Zendesk Switchboard: Una guía para desarrolladores",
"coverImageWidth": 1920,
"coverImageHeight": 1080,
"faqs": {
"heading": "Preguntas Frecuentes",
"type": "blog",
"answerType": "html",
"faqs": [
{
"question": "¿Necesito un desarrollador para configurar una integración personalizada de Zendesk Switchboard?",
"answer": "Sí, construir una integración personalizada requiere recursos de desarrollo. Necesita construir y alojar un punto final de webhook, implementar llamadas a la API para las transferencias de control y gestionar el mantenimiento continuo. Si no tiene recursos de desarrollo, considere una solución gestionada como eesel AI que se conecta a través de integraciones estándar de Zendesk."
},
{
"question": "¿Qué planes de Zendesk incluyen acceso a las API de Switchboard para la integración de bots personalizados?",
"answer": "Las API de Switchboard requieren Zendesk Suite Professional o superior, que comienza en $115 por agente al mes con facturación anual. Las integraciones de chatbots de terceros también requieren planes Professional o Enterprise."
},
{
"question": "¿Cómo maneja un bot personalizado de integración de Zendesk Switchboard las transferencias de conversación?",
"answer": "A través de la operación passControl de la API. Su bot llama a este punto final con una integración de destino (normalmente 'next' para escalar al Espacio de Trabajo del Agente). Puede incluir metadatos para rellenar los campos del ticket durante la transferencia. La integración de destino se activa y recibe todos los mensajes posteriores del cliente."
},
{
"question": "¿Puedo usar un bot personalizado con Zendesk Switchboard junto con otros bots?",
"answer": "Sí, Switchboard admite múltiples integraciones. Puede tener su bot personalizado, agentes nativos de IA de Zendesk y bots de mercado de terceros configurados simultáneamente. Utilice los respondedores predeterminados por canal para enrutar diferentes canales a diferentes bots."
},
{
"question": "¿Cuáles son los problemas comunes al construir un bot personalizado de integración de Zendesk Switchboard?",
"answer": "Los problemas más comunes son: (1) Bots que responden cuando no están en estado activo, causando respuestas dobles, (2) Formato incorrecto de los metadatos que impide el llenado de los campos del ticket, (3) Falta de llamadas releaseControl que dejan las conversaciones atascadas, y (4) Problemas de seguridad o fiabilidad del punto final del webhook."
},
{
"question": "¿Existe una alternativa a la construcción de una integración personalizada de Zendesk Switchboard?",
"answer": "Sí, herramientas como eesel AI gestionan la orquestación de bots automáticamente sin necesidad de configuración de la API de Switchboard. Se conecta a través de integraciones estándar de Zendesk, define reglas de enrutamiento en lenguaje sencillo y el sistema gestiona la gestión de la conversación. Esto elimina la necesidad de recursos de desarrollo y mantenimiento continuo de la API."
}
],
"supportLink": null
}
}
---
Si necesita construir un bot personalizado que se integre directamente con la infraestructura de mensajería de Zendesk, tendrá que trabajar con Zendesk Switchboard. Esta capa de enrutamiento dentro de [Sunshine Conversations](https://developer.zendesk.com/documentation/conversations/) determina qué sistema (su bot, una IA de terceros o agentes humanos) controla cada conversación con el cliente.
Construir una integración personalizada le da la máxima flexibilidad. Usted controla la lógica, las reglas de transferencia y cómo se comporta su bot en los diferentes canales. Pero también requiere recursos de desarrollo y mantenimiento continuo.
Para los equipos que desean automatización sin la complejidad de la API, hay un camino más sencillo. [Nosotros gestionamos la orquestación de bots automáticamente](https://www.eesel.ai/integration/zendesk-ai) sin necesidad de configuración de Switchboard. Pero si necesita el control total que ofrece la integración nativa, esta guía le guiará a través de la configuración completa.
## Lo que necesitará
Antes de empezar, asegúrese de que tiene:
- **Zendesk Suite Professional o superior** - Las API de Switchboard requieren al menos el plan Professional, que comienza en $115 por agente al mes
- **Credenciales de la API de Sunshine Conversations** - Necesitará un ID de clave (Key ID), un secreto (Secret) y un ID de aplicación (App ID) de su Centro de administración de Zendesk
- **Punto final de webhook** - Un punto final HTTPS seguro donde Zendesk pueda enviar eventos de conversación
- **Entorno de desarrollo** - Su bot necesita estar alojado en algún lugar con acceso a Internet para recibir webhooks y hacer llamadas a la API
Si no está en Suite Professional o no tiene recursos de desarrollo disponibles, una [solución gestionada como la nuestra](https://www.eesel.ai/integration/zendesk-ai) se conecta a través de los canales estándar de Zendesk sin necesidad de configuración de la API.
## Entendiendo los conceptos de Zendesk Switchboard
El Switchboard puede parecer abstracto al principio. Vamos a desglosar cómo funciona realmente.
### El switchboard y sus integraciones
Piense en el switchboard como un controlador de tráfico. Se sitúa entre sus clientes y sus sistemas de negocio, enrutando cada conversación al destino correcto.
Cada sistema que puede manejar conversaciones aparece como una **integración de switchboard**. Esto incluye:
- **Agentes de IA de Zendesk** (el bot nativo, identificado como `zd:answerBot`)
- **Agentes de IA Avanzados** (con tecnología Ultimate, identificado como `ultimate`)
- **Espacio de Trabajo del Agente** (sus agentes humanos, identificados como `zd:agentWorkspace`)
- **Bots de terceros** (integraciones del mercado a través de OAuth)
- **Integraciones personalizadas** (su bot basado en webhook)
Fuente: [Documentación de Zendesk Switchboard](https://developer.zendesk.com/documentation/conversations/messaging-platform/programmable-conversations/switchboard/)
### Estados de integración: activo, pendiente y en espera
Cada integración de switchboard existe en uno de tres estados para cualquier conversación dada:
| Estado | Lo que significa | Entrega de eventos |
|-------|---------------|----------------|
| **Activo** | Controlando actualmente la conversación | Recibe todos los eventos |
| **Pendiente** | A punto de tomar el control (transferencia elegante) | Recibe todos los eventos |
| **En espera** | Esperando en segundo plano | Eventos suprimidos por defecto |
Sólo una integración puede estar **activa** a la vez. La integración activa es la que se espera que responda a los mensajes del cliente. Si su bot está en espera, no recibirá eventos `conversation:message`.
Fuente: [Documentación de Zendesk Switchboard](https://developer.zendesk.com/documentation/conversations/messaging-platform/programmable-conversations/switchboard/)
### Operaciones de transferencia de control
Su bot necesita manejar cuatro operaciones clave:
| Operación | Cuándo usarla |
|-----------|----------------|
| **passControl** | Escalar a otro sistema (normalmente agentes) |
| **releaseControl** | La conversación está completa, restablecer al valor predeterminado |
| **offerControl** | Transferencia elegante con control compartido temporalmente |
| **acceptControl** | Aceptar una transferencia ofrecida |
La mayoría de las veces, utilizará `passControl` con la palabra clave `"next"` para escalar a cualquier integración que esté configurada como su siguiente respondedor predeterminado (normalmente el Espacio de Trabajo del Agente).
Fuente: [Documentación de Zendesk Switchboard](https://developer.zendesk.com/documentation/conversations/messaging-platform/programmable-conversations/switchboard/)
## Paso 1: Obtenga sus credenciales de la API de Sunshine Conversations
Su bot se comunicará con Zendesk a través de la API de Sunshine Conversations. Aquí le mostramos cómo obtener las credenciales que necesita.
Primero, inicie sesión en su Centro de administración de Zendesk. Navegue a **Aplicaciones e integraciones**, luego a **API de Conversaciones**. Si no ha creado credenciales de API antes, haga clic en **Crear clave de API**.
Recibirá:
- **ID de clave** (actúa como el nombre de usuario para la autenticación de la API)
- **Secreto** (actúa como la contraseña, almacene esto de forma segura)
- **ID de aplicación** (identifica su aplicación de Sunshine Conversations)
Guarde los tres valores. Los utilizará en cada llamada a la API que haga su bot.
Pruebe sus credenciales con una simple llamada a la API para listar sus switchboards:
```bash
curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/switchboards \
--user '{key_id}:{secret}'
Si obtiene una respuesta JSON con los detalles de su switchboard, sus credenciales están funcionando.
Fuente: Documentación del Centro de administración de Zendesk
Paso 2: Cree su integración personalizada
Antes de que su bot pueda unirse al switchboard, necesita existir como una integración en Sunshine Conversations. Esto crea el registro del punto final del webhook que Zendesk utilizará para enviar eventos a su bot.
Utilice la API de Crear Integración:
curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/integrations \
-X POST \
--user '{key_id}:{secret}' \
-H 'content-type: application/json' \
-d '{
"type": "custom",
"name": "mi-bot-personalizado",
"webhooks": [{
"target": "https://su-punto-final-de-bot.com/webhook",
"triggers": ["conversation:create", "conversation:message"]
}]
}'
La respuesta incluirá un campo id. Guarde este ID de integración, lo necesitará para el siguiente paso.
Fuente: Referencia de la API de Conversaciones de Zendesk
Paso 3: Añada su integración al switchboard
Tener una integración no es suficiente. Necesita añadirla a su switchboard para que pueda recibir realmente el control de las conversaciones.
Primero, encuentre su ID de switchboard:
curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/switchboards \
--user '{key_id}:{secret}'
Ahora cree una integración de switchboard que enlace su integración personalizada al switchboard:
curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/switchboards/{switchboard_id}/switchboardIntegrations \
-X POST \
--user '{key_id}:{secret}' \
-H 'content-type: application/json' \
-d '{
"name": "mi-bot-personalizado",
"integrationId": "{custom_integration_id}",
"deliverStandbyEvents": false,
"nextSwitchboardIntegrationId": "{agent_workspace_integration_id}"
}'
Parámetros clave explicados:
- name: Un identificador legible para su bot
- integrationId: El ID del Paso 2
- deliverStandbyEvents: Establecer en
falsea menos que necesite rastrear las conversaciones que no está manejando activamente - nextSwitchboardIntegrationId: Normalmente su ID de integración del Espacio de Trabajo del Agente, esto determina a dónde van las conversaciones cuando su bot escala
Fuente: Referencia de la API de Conversaciones de Zendesk
Paso 4: Configure los webhooks para su bot
Su bot necesita recibir eventos en tiempo real de Zendesk. La configuración del webhook que configuró en el Paso 2 define a dónde van estos eventos, pero su punto final necesita manejarlos correctamente.
Eventos de webhook requeridos
Como mínimo, su bot debe suscribirse a:
- conversation:create - Nueva conversación iniciada
- conversation:message - El cliente envió un mensaje
- switchboard:passControl - El control fue pasado a o desde su bot
- switchboard:releaseControl - La conversación fue liberada (ticket cerrado)
Estructura de la carga útil del webhook
Cada webhook contiene un array de eventos. Así es como se ve un evento de mensaje:
{
"app": { "id": "5ebee0975ac5304b664a12fa" },
"webhook": { "id": "5f4eaef81e3dcc117c7ba48a", "version": "v2" },
"events": [{
"id": "5f74a0d52b5315fc007e798a",
"createdAt": "2020-09-30T15:14:29.834Z",
"type": "conversation:message",
"payload": {
"conversation": {
"id": "f52b01137aa6c250bc7251fa",
"activeSwitchboardIntegration": {
"id": "67dc32a58d289d63bfeb6346",
"name": "mi-bot-personalizado"
}
},
"message": {
"author": { "type": "user" },
"content": { "type": "text", "text": "Necesito ayuda con mi pedido" }
}
}
}]
}
Verificando que usted tiene el control
Antes de responder a cualquier mensaje, compruebe el objeto activeSwitchboardIntegration. Si el name no coincide con el nombre de la integración de switchboard de su bot, no debe responder. La conversación está siendo manejada por otro sistema.
Fuente: Documentación de Recepción de Mensajes de Zendesk
Paso 5: Implemente la lógica de transferencia de control
Cuando su bot determina que no puede resolver el problema del cliente, necesita escalar a un agente humano. Aquí es donde entra passControl.
Escalada básica
Para pasar el control a la siguiente integración configurada (normalmente el Espacio de Trabajo del Agente):
curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/conversations/{conversation_id}/passControl \
-X POST \
--user '{key_id}:{secret}' \
-H 'content-type: application/json' \
-d '{"switchboardIntegration": "next"}'
Pasar metadatos para rellenar los campos del ticket
Una de las características más potentes es rellenar los campos del ticket de Zendesk durante la transferencia. Incluya metadatos en su llamada passControl:
{
"switchboardIntegration": "zd-agentWorkspace",
"metadata": {
"dataCapture.systemField.priority": "high",
"dataCapture.systemField.tags": "bot-escalated,shipping-issue",
"dataCapture.systemField.group_id": "360000123456",
"dataCapture.ticketField.54321": "Pedido #12345",
"first_message_id": "603012d7e0a3f9000c879b67"
}
}
Esto establece automáticamente la prioridad del ticket, añade etiquetas, asigna a un grupo específico, rellena un campo personalizado y controla la cantidad de historial de conversación que ve el agente.
Liberando el control después de la resolución
Si su bot resuelve completamente el problema del cliente, llame a releaseControl para restablecer la conversación:
curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/conversations/{conversation_id}/releaseControl \
-X POST \
--user '{key_id}:{secret}' \
-H 'content-type: application/json' \
-d '{}'
Esto borra la integración activa. Si el cliente regresa más tarde, comenzará de nuevo con su respondedor predeterminado.
Fuente: Referencia de la API de Conversaciones de Zendesk
Paso 6: Pruebe su integración de bot personalizado
Antes de ponerlo en marcha, verifique que cada parte de su integración funciona correctamente.
Lista de verificación de pruebas
- Cree una conversación de prueba a través de su Web Widget o canal de mensajería
- Verifique que su bot recibe el evento
conversation:create - Envíe un mensaje de prueba y confirme que su bot recibe
conversation:message - Verifique que su bot sólo responde cuando
activeSwitchboardIntegration.namecoincide - Pruebe la escalada activando su flujo passControl
- Verifique la creación del ticket en el Espacio de Trabajo del Agente con los metadatos correctos
- Cierre el ticket y confirme que el control regresa a su bot después de que se ejecute la automatización
Problemas comunes de las pruebas
| Problema | Causa probable |
|---|---|
| El bot no recibe eventos | La integración no está en el switchboard, o deliverStandbyEvents es falso mientras no está activo |
| Respuestas dobles | El bot responde incluso cuando no está en estado activo |
| La transferencia no crea el ticket | nextSwitchboardIntegrationId incorrecto o carga útil de passControl mal formada |
| Los metadatos no aparecen en el ticket | Formato de clave de campo incorrecto o IDs de campo |
Fuente: Documentación del Espacio de Trabajo del Agente de Zendesk
Patrones comunes y mejores prácticas
Enrutamiento específico del canal
Los diferentes canales a menudo necesitan diferentes respondedores predeterminados. Configure los valores predeterminados por canal utilizando la API de Actualizar Integración:
curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/integrations/{channel_integration_id} \
-X PATCH \
--user '{key_id}:{secret}' \
-H 'content-type: application/json' \
-d '{"defaultResponderId": "{switchboard_integration_id}"}'
Por ejemplo, enrute las conversaciones de WhatsApp directamente a los agentes (canal de alto valor) mientras envía el tráfico del Web Widget a su bot primero.
Implementaciones graduales durante las migraciones
Si está migrando de una plataforma de bots a otra, ejecute ambas simultáneamente durante la transición:
- Añada ambos bots como integraciones de switchboard
- Enrute marcas o canales específicos a cada bot
- Cambie gradualmente el tráfico a medida que valida el nuevo bot
- Elimine la antigua integración del bot una vez que la migración esté completa
Controlando el historial de la conversación
Por defecto, Zendesk incluye los últimos 10 mensajes al crear un ticket. Para incluir la conversación completa, rastree el primer ID de mensaje cuando comience la conversación:
{
"metadata": {
"first_message_id": "{first_message_id}"
}
}
Pase esto en su llamada passControl para asegurar que los agentes vean el historial completo de la conversación.
Solución de problemas comunes
Conversaciones atascadas en la integración incorrecta
Si los clientes están atascados hablando con un bot que debería haber escalado, compruebe que su bot está llamando a passControl o releaseControl correctamente. También verifique que el nextSwitchboardIntegrationId está configurado en la integración de switchboard de su bot.
Los metadatos no se pasan a los tickets
Las claves de los campos deben seguir patrones exactos:
- Campos estándar:
dataCapture.systemField.{field_name} - Campos personalizados:
dataCapture.ticketField.{field_id}
Compruebe sus IDs de campo personalizados en el Centro de administración de Zendesk. Son valores numéricos, no los nombres de campo que ve en la interfaz de usuario.
Transferencias fallando silenciosamente
Habilite el registro para todos los eventos de webhook que recibe su bot. Si está llamando a passControl pero no ve el cambio de switchboard, verifique que sus credenciales de la API tienen los ámbitos correctos y que su JSON de carga útil es válido.
Estado de integración activa desconocido
Si no está seguro de qué integración controla actualmente una conversación, utilice la API de Obtener Conversación:
curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/conversations/{conversation_id} \
--user '{key_id}:{secret}'
Compruebe la propiedad activeSwitchboardIntegration en la respuesta.
Un enfoque más sencillo para la orquestación de bots de Zendesk
Construir y mantener una integración personalizada de Switchboard requiere recursos de desarrollo continuos. Su equipo necesita manejar la infraestructura de webhook, el control de versiones de la API, el manejo de errores y el mantenimiento continuo a medida que Zendesk actualiza su plataforma.
Para los equipos que desean automatización sin la complejidad de la API, ofrecemos un enfoque diferente. eesel AI gestiona la orquestación automáticamente sin necesidad de configuración de Switchboard.
Así es como funciona:
- No se necesita configuración de la API - Nos integramos a través de los canales estándar de Zendesk
- Aprende de su contenido - Nuestra IA se entrena en su centro de ayuda, tickets pasados y documentación
- Enrutamiento automático - Las conversaciones se enrutan en función de sus reglas, sin configuración manual del switchboard
- Reglas de escalada en lenguaje sencillo - En lugar de JSON, usted define reglas como "Siempre escalar las disputas de facturación a un humano"
Nuestro plan Business incluye capacidades de Agente de IA que responden directamente a los clientes, Triaje de IA para el enrutamiento de tickets y simulación masiva para probar con tickets pasados antes de ponerlo en marcha. Los planes comienzan en $239 por mes (facturación anual) con una prueba gratuita de 7 días.
La elección correcta depende de la capacidad técnica de su equipo. Native Switchboard ofrece la máxima flexibilidad para una lógica personalizada compleja. Nuestro enfoque ofrece un tiempo de rentabilidad más rápido cuando desea una automatización sofisticada sin el trabajo de infraestructura.
Compartir esta entrada
Article by
