zendesk-switchboard-integration-custom-bot
eesel Team
Last edited 20 fevereiro 2026
{
"title": "Como criar um bot personalizado com o Zendesk Switchboard: Um guia para desenvolvedores",
"slug": "zendesk-switchboard-integration-custom-bot",
"locale": "pt",
"date": "2026-02-20",
"updated": "2026-02-20",
"template": "default",
"excerpt": "Crie um bot personalizado para o Zendesk Switchboard com este guia técnico. Abrange credenciais de API, configuração de integração, tratamento de webhook e controle de conversas.",
"categories": [
"Blog Writer AI"
],
"tags": [
"Zendesk",
"Switchboard",
"Custom Bot",
"Integration",
"Sunshine Conversations"
],
"readTime": 11,
"author": 16,
"reviewer": 14,
"seo": {
"title": "Como criar um bot personalizado com o Zendesk Switchboard: Um guia para desenvolvedores",
"description": "Crie um bot personalizado para o Zendesk Switchboard com este guia técnico. Abrange credenciais de API, configuração de integração, tratamento de webhook e controle de conversas.",
"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": "Imagem do banner para Como criar um bot personalizado com o Zendesk Switchboard: Um guia para desenvolvedores",
"coverImageWidth": 1920,
"coverImageHeight": 1080,
"faqs": {
"heading": "Perguntas Frequentes",
"type": "blog",
"answerType": "html",
"faqs": [
{
"question": "Preciso de um desenvolvedor para configurar uma integração personalizada do Zendesk Switchboard?",
"answer": "Sim, criar uma integração personalizada requer recursos de desenvolvimento. Você precisa construir e hospedar um endpoint de webhook, implementar chamadas de API para transferências de controle e lidar com a manutenção contínua. Se você não tiver recursos de desenvolvimento, considere uma solução gerenciada como o eesel AI que se conecta por meio de integrações padrão do Zendesk."
},
{
"question": "Quais planos do Zendesk incluem acesso às APIs do Switchboard para integração de bot personalizado?",
"answer": "As APIs do Switchboard exigem o Zendesk Suite Professional ou superior, que começa em US$ 115 por agente por mês quando cobrado anualmente. As integrações de chatbot de terceiros também exigem planos Professional ou Enterprise."
},
{
"question": "Como o bot personalizado de integração do Zendesk Switchboard lida com as transferências de conversas?",
"answer": "Através da operação passControl da API. Seu bot chama este endpoint com uma integração de destino (normalmente 'next' para escalar para o Agent Workspace). Você pode incluir metadados para preencher os campos do ticket durante a transferência. A integração de destino se torna ativa e recebe todas as mensagens subsequentes do cliente."
},
{
"question": "Posso usar um bot personalizado com o Zendesk Switchboard junto com outros bots?",
"answer": "Sim, o Switchboard suporta múltiplas integrações. Você pode ter seu bot personalizado, agentes de IA nativos do Zendesk e bots de marketplace de terceiros todos configurados simultaneamente. Use respondedores padrão por canal para rotear diferentes canais para diferentes bots."
},
{
"question": "Quais são os problemas comuns ao criar um bot personalizado de integração do Zendesk Switchboard?",
"answer": "Os problemas mais comuns são: (1) Bots respondendo quando não estão no estado ativo, causando respostas duplas, (2) Formatação incorreta de metadados impedindo o preenchimento dos campos do ticket, (3) Chamadas releaseControl ausentes deixando as conversas presas e (4) Problemas de segurança ou confiabilidade do endpoint de webhook."
},
{
"question": "Existe uma alternativa para construir uma integração personalizada do Zendesk Switchboard?",
"answer": "Sim, ferramentas como o eesel AI lidam com a orquestração de bots automaticamente, sem exigir a configuração da API do Switchboard. Você se conecta por meio de integrações padrão do Zendesk, define regras de roteamento em português claro e o sistema lida com o gerenciamento de conversas. Isso elimina a necessidade de recursos de desenvolvimento e manutenção contínua da API."
}
],
"supportLink": null
}
}
---
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](https://developer.zendesk.com/documentation/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](https://www.eesel.ai/integration/zendesk-ai) 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](https://www.eesel.ai/integration/zendesk-ai) 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](https://developer.zendesk.com/documentation/conversations/messaging-platform/programmable-conversations/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](https://developer.zendesk.com/documentation/conversations/messaging-platform/programmable-conversations/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](https://developer.zendesk.com/documentation/conversations/messaging-platform/programmable-conversations/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:
```bash
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.
Compartilhe esta postagem
Article by
