Como criar um bot personalizado com o Zendesk Switchboard: Um guia para desenvolvedores
Stevia Putri
Última edição February 20, 2026
Se você precisa criar um bot personalizado que se integra diretamente com a infraestrutura de mensagens do Zendesk, você precisará trabalhar com o Zendesk Switchboard. Esta camada de roteamento dentro do Sunshine Conversations determina qual sistema (seu bot, uma IA de terceiros ou agentes humanos) controla cada conversa com o cliente.
Construir uma integração personalizada oferece a você máxima flexibilidade. Você controla a lógica, as regras de transferência e como seu bot se comporta em diferentes canais. Mas também requer recursos de desenvolvimento e manutenção contínua.
Para equipes que desejam automação sem a complexidade da API, existe um caminho mais simples. Nós lidamos com a orquestração de bots automaticamente sem exigir a configuração do Switchboard. Mas se você precisa do controle total que a integração nativa oferece, este guia o orienta na configuração completa.
O que você vai precisar
Antes de começar, certifique-se de que você tem:
- Zendesk Suite Professional ou superior - As APIs do Switchboard exigem pelo menos o plano Professional, que começa em US$ 115 por agente por mês
- Credenciais da API do Sunshine Conversations - Você precisará de um ID de chave (Key ID), Segredo (Secret) e ID do aplicativo (App ID) do seu Centro de Administração do Zendesk
- Endpoint de webhook - Um endpoint HTTPS seguro onde o Zendesk pode enviar eventos de conversa
- Ambiente de desenvolvimento - Seu bot precisa ser hospedado em algum lugar com acesso à internet para receber webhooks e fazer chamadas de API
Se você não estiver no Suite Professional ou não tiver recursos de desenvolvimento disponíveis, uma solução gerenciada como a nossa se conecta por meio de canais padrão do Zendesk sem exigir a configuração da API.
Entendendo os conceitos do Zendesk Switchboard
O Switchboard pode parecer abstrato no começo. Vamos detalhar como ele realmente funciona.
O switchboard e suas integrações
Pense no switchboard como um controlador de tráfego. Ele fica entre seus clientes e seus sistemas de negócios, roteando cada conversa para o destino certo.
Cada sistema que pode lidar com conversas aparece como uma integração do switchboard. Isso inclui:
- Agentes de IA do Zendesk (o bot nativo, identificado como
zd:answerBot) - AI agents Advanced (com tecnologia Ultimate, identificado como
ultimate) - Agent Workspace (seus agentes humanos, identificados como
zd:agentWorkspace) - Bots de terceiros (integrações de marketplace via OAuth)
- Integrações personalizadas (seu bot baseado em webhook)
Fonte: Documentação do Zendesk Switchboard
Estados de integração: ativo, pendente e em espera
Cada integração do switchboard existe em um de três estados para qualquer conversa:
| Estado | O que significa | Entrega de eventos |
|---|---|---|
| Ativo | Controlando atualmente a conversa | Recebe todos os eventos |
| Pendente | Prestes a assumir o controle (transferência elegante) | Recebe todos os eventos |
| Em espera | Esperando em segundo plano | Eventos suprimidos por padrão |
Apenas uma integração pode estar ativa por vez. A integração ativa é aquela que se espera que responda às mensagens do cliente. Se o seu bot estiver em espera, ele não receberá eventos conversation:message.
Fonte: Documentação do Zendesk Switchboard
Operações de transferência de controle
Seu bot precisa lidar com quatro operações principais:
| Operação | Quando usá-la |
|---|---|
| passControl | Escalonando para outro sistema (normalmente agentes) |
| releaseControl | A conversa está completa, redefinir para o padrão |
| offerControl | Transferência elegante com controle compartilhado temporariamente |
| acceptControl | Aceitando uma transferência oferecida |
Na maioria das vezes, você usará passControl com a palavra-chave "next" para escalar para qualquer integração que esteja configurada como seu próximo respondedor padrão (geralmente o Agent Workspace).
Fonte: Documentação do Zendesk Switchboard
Passo 1: Obtenha suas credenciais da API do Sunshine Conversations
Seu bot se comunicará com o Zendesk através da API do Sunshine Conversations. Veja como obter as credenciais que você precisa.
Primeiro, faça login no seu Centro de Administração do Zendesk. Navegue até Aplicativos e integrações, depois API de Conversas. Se você não criou credenciais de API antes, clique em Criar chave de API.
Você receberá:
- ID da chave (atua como o nome de usuário para autenticação da API)
- Segredo (atua como a senha, armazene isso com segurança)
- ID do aplicativo (identifica seu aplicativo Sunshine Conversations)
Salve todos os três valores. Você os usará em cada chamada de API que seu bot fizer.
Teste suas credenciais com uma chamada de API simples para listar seus switchboards:
curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/switchboards \
--user '{key_id}:{secret}'
Se você receber uma resposta JSON com os detalhes do seu switchboard, suas credenciais estão funcionando.
Fonte: Documentação do Centro de Administração do Zendesk
Passo 2: Crie sua integração personalizada
Antes que seu bot possa se juntar ao switchboard, ele precisa existir como uma integração no Sunshine Conversations. Isso cria o registro do endpoint de webhook que o Zendesk usará para enviar eventos para o seu bot.
Use a API Criar Integração:
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": "my-custom-bot",
"webhooks": [{
"target": "https://your-bot-endpoint.com/webhook",
"triggers": ["conversation:create", "conversation:message"]
}]
}'
A resposta incluirá um campo id. Salve este ID de integração, você precisará dele para o próximo passo.
Fonte: Referência da API de Conversas do Zendesk
Passo 3: Adicione sua integração ao switchboard
Ter uma integração não é suficiente. Você precisa adicioná-la ao seu switchboard para que ela possa realmente receber o controle das conversas.
Primeiro, encontre o ID do seu switchboard:
curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/switchboards \
--user '{key_id}:{secret}'
Agora crie uma integração de switchboard que vincule sua integração personalizada ao 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": "my-custom-bot",
"integrationId": "{custom_integration_id}",
"deliverStandbyEvents": false,
"nextSwitchboardIntegrationId": "{agent_workspace_integration_id}"
}'
Parâmetros-chave explicados:
- name: Um identificador legível para o seu bot
- integrationId: O ID do Passo 2
- deliverStandbyEvents: Defina como
falsea menos que você precise rastrear conversas que não está lidando ativamente - nextSwitchboardIntegrationId: Geralmente o ID da sua integração do Agent Workspace, isso determina para onde as conversas vão quando seu bot escala
Fonte: Referência da API de Conversas do Zendesk
Passo 4: Configure webhooks para o seu bot
Seu bot precisa receber eventos em tempo real do Zendesk. A configuração de webhook que você configurou no Passo 2 define para onde esses eventos vão, mas seu endpoint precisa lidar com eles adequadamente.
Eventos de webhook obrigatórios
No mínimo, seu bot deve se inscrever em:
- conversation:create - Nova conversa iniciada
- conversation:message - Cliente enviou uma mensagem
- switchboard:passControl - O controle foi passado para ou do seu bot
- switchboard:releaseControl - A conversa foi liberada (ticket fechado)
Estrutura do payload do webhook
Cada webhook contém uma matriz de eventos. Veja como é um evento de mensagem:
{
"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": "my-custom-bot"
}
},
"message": {
"author": { "type": "user" },
"content": { "type": "text", "text": "I need help with my order" }
}
}
}]
}
Verificando se você está no controle
Antes de responder a qualquer mensagem, verifique o objeto activeSwitchboardIntegration. Se o name não corresponder ao nome da integração do switchboard do seu bot, você não deve responder. A conversa está sendo tratada por outro sistema.
Fonte: Documentação do Zendesk Recebendo Mensagens
Passo 5: Implemente a lógica de transferência de controle
Quando seu bot determina que não pode resolver o problema do cliente, ele precisa escalar para um agente humano. É aqui que passControl entra em ação.
Escalonamento básico
Para passar o controle para a próxima integração configurada (normalmente o Agent Workspace):
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"}'
Passando metadados para preencher os campos do ticket
Um dos recursos mais poderosos é preencher os campos do ticket do Zendesk durante a transferência. Inclua metadados na sua chamada passControl:
{
"switchboardIntegration": "zd-agentWorkspace",
"metadata": {
"dataCapture.systemField.priority": "high",
"dataCapture.systemField.tags": "bot-escalated,shipping-issue",
"dataCapture.systemField.group_id": "360000123456",
"dataCapture.ticketField.54321": "Order #12345",
"first_message_id": "603012d7e0a3f9000c879b67"
}
}
Isso define automaticamente a prioridade do ticket, adiciona tags, atribui a um grupo específico, preenche um campo personalizado e controla quanta história da conversa o agente vê.
Liberando o controle após a resolução
Se seu bot resolver completamente o problema do cliente, chame releaseControl para redefinir a conversa:
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 '{}'
Isso limpa a integração ativa. Se o cliente retornar mais tarde, ele começará do zero com seu respondedor padrão.
Fonte: Referência da API de Conversas do Zendesk
Passo 6: Teste sua integração de bot personalizado
Antes de entrar em produção, verifique se cada parte da sua integração funciona corretamente.
Lista de verificação de testes
- Crie uma conversa de teste através do seu Web Widget ou canal de mensagens
- Verifique se seu bot recebe o evento
conversation:create - Envie uma mensagem de teste e confirme se seu bot recebe
conversation:message - Verifique se seu bot responde apenas quando
activeSwitchboardIntegration.namecorresponde - Teste o escalonamento acionando seu fluxo passControl
- Verifique a criação do ticket no Agent Workspace com os metadados corretos
- Feche o ticket e confirme se o controle retorna ao seu bot após a execução da automação
Problemas comuns de teste
| Problema | Causa provável |
|---|---|
| Bot não recebe eventos | Integração não está no switchboard, ou deliverStandbyEvents é falso enquanto não está ativo |
| Respostas duplas | Bot respondendo mesmo quando não está no estado ativo |
| Transferência não criando ticket | nextSwitchboardIntegrationId errado ou payload passControl malformado |
| Metadados não aparecendo no ticket | Formato de chave de campo incorreto ou IDs de campo |
Fonte: Documentação do Zendesk Agent Workspace
Padrões comuns e melhores práticas
Roteamento específico do canal
Canais diferentes geralmente precisam de respondedores padrão diferentes. Configure padrões por canal usando a API Atualizar Integração:
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 exemplo, roteie conversas do WhatsApp diretamente para agentes (canal de alto valor) enquanto envia o tráfego do Web Widget para o seu bot primeiro.
Implementações faseadas durante as migrações
Se você estiver migrando de uma plataforma de bot para outra, execute ambas simultaneamente durante a transição:
- Adicione ambos os bots como integrações do switchboard
- Roteie marcas ou canais específicos para cada bot
- Mude gradualmente o tráfego à medida que você valida o novo bot
- Remova a antiga integração do bot assim que a migração for concluída
Controlando o histórico da conversa
Por padrão, o Zendesk inclui as últimas 10 mensagens ao criar um ticket. Para incluir a conversa completa, rastreie o ID da primeira mensagem quando a conversa começar:
{
"metadata": {
"first_message_id": "{first_message_id}"
}
}
Passe isso na sua chamada passControl para garantir que os agentes vejam o histórico completo da conversa.
Solução de problemas comuns
Conversas presas na integração errada
Se os clientes estão presos conversando com um bot que deveria ter escalado, verifique se seu bot está chamando passControl ou releaseControl corretamente. Verifique também se o nextSwitchboardIntegrationId está configurado na integração do switchboard do seu bot.
Metadados não passando para os tickets
As chaves de campo devem seguir padrões exatos:
- Campos padrão:
dataCapture.systemField.{field_name} - Campos personalizados:
dataCapture.ticketField.{field_id}
Verifique novamente seus IDs de campo personalizado no Centro de Administração do Zendesk. Eles são valores numéricos, não os nomes de campo que você vê na interface do usuário.
Transferências falhando silenciosamente
Ative o registro em log para todos os eventos de webhook que seu bot recebe. Se você estiver chamando passControl mas não vendo a mudança do switchboard, verifique se suas credenciais de API têm os escopos corretos e se seu JSON de payload é válido.
Estado de integração ativa desconhecido
Se você não tiver certeza de qual integração controla atualmente uma conversa, use a API Obter Conversa:
curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/conversations/{conversation_id} \
--user '{key_id}:{secret}'
Verifique a propriedade activeSwitchboardIntegration na resposta.
Uma abordagem mais simples para a orquestração de bots do Zendesk
Construir e manter uma integração personalizada do Switchboard requer recursos de desenvolvimento contínuos. Sua equipe precisa lidar com a infraestrutura de webhook, versionamento de API, tratamento de erros e manutenção contínua à medida que o Zendesk atualiza sua plataforma.
Para equipes que desejam automação sem a complexidade da API, oferecemos uma abordagem diferente. eesel AI lida com a orquestração automaticamente sem exigir a configuração do Switchboard.
Veja como funciona:
- Nenhuma configuração de API necessária - Nós integramos através dos canais padrão do Zendesk
- Aprende com seu conteúdo - Nossa IA treina em sua central de ajuda, tickets anteriores e documentação
- Roteamento automático - As conversas são roteadas com base em suas regras, sem configuração manual do switchboard
- Regras de escalonamento em português claro - Em vez de JSON, você define regras como "Sempre escalar disputas de cobrança para um humano"
Nosso plano Business inclui recursos de Agente de IA que respondem diretamente aos clientes, Triagem de IA para roteamento de tickets e simulação em massa para testar em relação a tickets anteriores antes de entrar em produção. Os planos começam em US$ 239 por mês (cobrança anual) com um teste gratuito de 7 dias.
A escolha certa depende da capacidade técnica da sua equipe. O Switchboard nativo oferece máxima flexibilidade para lógica personalizada complexa. Nossa abordagem oferece um tempo de retorno mais rápido quando você deseja automação sofisticada sem o trabalho de infraestrutura.
Perguntas Frequentes
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.
