Cómo construir un bot personalizado con Zendesk Switchboard: Una guía para desarrolladores

Escrito por

Stevia Putri

Última edición February 20, 2026

Verificado por expertos

Imagen del banner para Cómo construir un bot personalizado con Zendesk Switchboard: Una guía para desarrolladores

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 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 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.

Una captura de pantalla de la página de inicio de Zendesk.

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 se conecta a través de los canales estándar de Zendesk sin necesidad de configuración de la API.

La página de configuración de la API de Zendesk Sunshine Conversations que muestra las credenciales de la API, incluyendo el ID de la aplicación, el ID de la clave y la clave secreta.

Entendiendo los conceptos de Zendesk Switchboard

El Switchboard puede parecer abstracto al principio. Vamos a desglosar cómo funciona realmente.

Visión general visual de cómo Switchboard enruta las conversaciones entre los sistemas

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

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

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

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:

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 false a 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.name coincide
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

El espacio de trabajo del agente que muestra una conversación de mensajería en vivo con un cliente, junto con los detalles del ticket y el historial de interacciones.

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.

Guía visual para diagnosticar problemas comunes de integración

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.

eesel AI instructions panel showing natural language configuration for setting up AI agent behavior and escalation rules.

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"

Una captura de pantalla del panel de control de eesel AI que muestra integraciones de un solo clic para varios helpdesks, ilustrando una configuración fácil en comparación con el complejo proceso de integración de Ultimate Zendesk.

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.

Automate your content with AI agents

Prueba gratis Agendar demo

Preguntas Frecuentes

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.

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.

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.

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.

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.

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.

Share this article

Article by

Stevia Putri

Stevia Putri is a marketing generalist at eesel AI, where she helps turn powerful AI tools into stories that resonate. She’s driven by curiosity, clarity, and the human side of technology.