zendesk-sunshine-conversations-custom-integration
eesel Team
Last edited 22 fevereiro 2026
{
"title": "Como criar uma integração personalizada do Zendesk Sunshine Conversations",
"slug": "zendesk-sunshine-conversations-custom-integration",
"locale": "pt",
"date": "2026-02-20",
"updated": "2026-02-20",
"template": "default",
"excerpt": "Crie integrações personalizadas com o Zendesk Sunshine Conversations usando este guia técnico que abrange a configuração da API, a configuração de webhook, as operações do Switchboard e as melhores práticas.",
"categories": [
"Blog Writer AI"
],
"tags": [
"Zendesk",
"Sunshine Conversations",
"API Integration",
"Webhooks",
"Customer Support"
],
"readTime": 12,
"author": 16,
"reviewer": 14,
"seo": {
"title": "Como criar uma integração personalizada do Zendesk Sunshine Conversations",
"description": "Crie integrações personalizadas com o Zendesk Sunshine Conversations usando este guia técnico que abrange a configuração da API, a configuração de webhook, as operações do Switchboard e as melhores práticas.",
"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": "Imagem do banner para Como criar uma integração personalizada do Zendesk Sunshine Conversations",
"coverImageWidth": 1920,
"coverImageHeight": 1080,
"faqs": {
"heading": "Perguntas frequentes",
"type": "blog",
"answerType": "html",
"faqs": [
{
"question": "É necessário ter experiência em programação para criar uma integração personalizada do Zendesk Sunshine Conversations?",
"answer": "Sim, criar uma integração personalizada requer conhecimento de programação, especificamente com APIs REST e webhooks. Você precisará escrever código do lado do servidor para receber eventos, processar mensagens e enviar respostas. Se você não tiver recursos de desenvolvimento, considere soluções pré-construídas como o eesel AI que se integram sem codificação."
},
{
"question": "Quais linguagens de programação funcionam melhor para uma integração personalizada do Zendesk Sunshine Conversations?",
"answer": "Qualquer linguagem que possa lidar com solicitações HTTP e JSON funcionará. Node.js, Python e Ruby são escolhas populares com bom suporte de biblioteca. O Zendesk fornece SDKs oficiais para Ruby e Java, mas você pode usar qualquer linguagem que se adapte à sua pilha."
},
{
"question": "Quanto custa uma integração personalizada do Zendesk Sunshine Conversations?",
"answer": "A integração em si é gratuita, mas você precisa de um plano Zendesk Suite Professional (US$ 115/agente/mês anualmente) ou superior para acessar a API. Os custos adicionais incluem excedentes de MAU (US$ 50 por 2.500 MAUs além dos 1.000 incluídos) e qualquer infraestrutura para hospedar seu servidor webhook."
},
{
"question": "Uma integração personalizada do Zendesk Sunshine Conversations pode lidar com vários canais de mensagens?",
"answer": "Sim. Depois que sua integração é construída, ela funciona com qualquer canal conectado ao Sunshine Conversations, incluindo WhatsApp, Facebook Messenger, Instagram, chat da web e SMS. Seu código recebe eventos da mesma forma, independentemente de qual canal o cliente usa."
},
{
"question": "Como testar uma integração personalizada do Zendesk Sunshine Conversations antes de entrar em operação?",
"answer": "Use o ngrok para expor seu servidor local durante o desenvolvimento. Crie conversas de teste por meio do widget da web ou canais conectados. Para testes mais abrangentes, execute simulações com dados históricos de conversas. O Zendesk também fornece um ambiente de sandbox em planos Enterprise."
},
{
"question": "Quais são os limites de taxa para uma integração personalizada do Zendesk Sunshine Conversations?",
"answer": "O limite de taxa padrão é de 100 solicitações por minuto. Se você exceder isso, receberá um código de status 429 com um cabeçalho Retry-After. Para casos de uso de alto volume, entre em contato com o Zendesk para aumentar seus limites. Sempre implemente o backoff exponencial em sua lógica de repetição."
}
],
"supportLink": null
}
}
---
Criar uma integração personalizada com o [Zendesk Sunshine Conversations](https://www.zendesk.com/messaging/) permite que você crie experiências de mensagens personalizadas que se adaptam às suas necessidades exatas de negócios. Se você deseja conectar um CRM proprietário, criar um bot especializado ou orquestrar fluxos de conversação complexos, a [API do Sunshine Conversations](https://developer.zendesk.com/api-reference/conversations/) fornece a base de que você precisa.
Este guia orienta você em tudo, desde a configuração inicial até a implantação em produção. Ao final, você terá um servidor webhook funcional que pode receber mensagens, responder de forma inteligente e entregar a agentes humanos quando necessário. Para referência oficial, consulte a [documentação da API do Zendesk](https://developer.zendesk.com/api-reference/conversations/).
Se você preferir pular o trabalho de engenharia, o [eesel AI](https://www.eesel.ai) oferece uma alternativa sem código que se conecta ao Zendesk em minutos e lida com as conversas de forma autônoma.
*O Zendesk Sunshine Conversations conecta canais de mensagens aos seus aplicativos de negócios por meio de webhooks e APIs.*
## O que você vai precisar
Antes de começar, certifique-se de ter o seguinte em vigor.
**Requisitos do Zendesk:**
- Um [plano Zendesk Suite Professional ou Enterprise](https://www.zendesk.com/pricing/) (o acesso à API do Sunshine Conversations requer esses níveis)
- Acesso de administrador à sua conta do Zendesk
- Pelo menos 1.000 usuários ativos mensais (MAUs) incluídos em seu plano (pacotes de MAU adicionais disponíveis por US$ 50 por 2.500 MAUs)
**Requisitos técnicos:**
- Um ambiente de servidor (Node.js recomendado para este guia)
- [ngrok](https://ngrok.com/) para teste de webhook local
- Conhecimento básico de APIs REST e webhooks
- Endpoint HTTPS para produção
| Plano | Preço Anual | Acesso ao Sunshine | MAUs Incluídos |
|------|--------------|-----------------|---------------|
| Suite Team | US$ 55/agente/mês | Mensagens básicas apenas | N/A |
| Suite Professional | US$ 115/agente/mês | Acesso total à API | 1.000 |
| Suite Enterprise | US$ 169/agente/mês | Acesso total à API | 1.000 |
## Entendendo a arquitetura do Sunshine Conversations
O [Sunshine Conversations](https://support.zendesk.com/hc/en-us/articles/6380323137306) é a plataforma de mensagens unificada do Zendesk. Originalmente Smooch.io (adquirido pelo Zendesk em 2019), agora alimenta mensagens em toda a Zendesk Suite. A arquitetura é construída em torno de alguns conceitos-chave que você precisa entender antes de construir.
**Apps (Aplicativos):** Cada aplicativo representa uma empresa ou marca. Você criará um aplicativo no Admin Center que contém todos os seus dados de conversação.
**Integrations (Integrações):** São as conexões entre o Sunshine Conversations e sistemas externos. As integrações personalizadas usam webhooks para enviar e receber mensagens.
**Conversations (Conversas):** Uma conversa é um tópico de mensagens entre um usuário e sua empresa. As conversas persistem entre os canais (um usuário pode começar no chat da web e continuar no WhatsApp).
**Switchboard (Central de Atendimento):** Isso controla quem "possui" uma conversa a qualquer momento. O Switchboard encaminha conversas entre bots, agentes e integrações.
**Authentication (Autenticação):** A API usa Basic Auth (ID da chave como nome de usuário, Segredo como senha) ou tokens JWT para segurança aprimorada.
O fluxo funciona assim: um cliente envia uma mensagem por meio de qualquer canal conectado (widget da web, WhatsApp, etc.). O Sunshine Conversations recebe a mensagem e a encaminha para sua integração de webhook. Seu servidor processa a mensagem, decide como responder e envia uma resposta de volta por meio da API. Se necessário, sua integração pode transferir o controle para um agente humano por meio do [Switchboard](https://docs.smooch.io/rest/).
## Passo 1: Crie seu aplicativo Sunshine Conversations e chaves de API
Primeiro, você precisa criar um aplicativo e gerar credenciais de API.
Navegue até o Zendesk Admin Center. Vá para **Apps e integrações** > **APIs** > **Conversations API**.
Clique em **Criar chave de API** e dê a ela um nome descritivo como "Integração de Webhook de Produção". Você receberá três informações:
- **App ID (ID do Aplicativo):** Um identificador exclusivo para seu aplicativo
- **Key ID (ID da Chave):** Usado como o nome de usuário para autenticação da API
- **Secret Key (Chave Secreta):** Usado como a senha para autenticação da API
Armazene essas credenciais com segurança. Você precisará delas para cada chamada de API. A Chave Secreta é mostrada apenas uma vez. Se você perdê-la, precisará gerar um novo par de chaves.
Configure suas variáveis de ambiente para manter as credenciais fora do seu código:
```bash
export SUNSHINE_APP_ID="your_app_id"
export SUNSHINE_KEY_ID="your_key_id"
export SUNSHINE_SECRET="your_secret_key"
Passo 2: Configure sua integração de webhook
Agora crie a integração de webhook que receberá eventos de mensagem.
No Admin Center, vá para Integrações > Integrações de conversas.
Clique em Criar integração e selecione Personalizado como o tipo. Configure o seguinte:
Target URL (URL de Destino): Para desenvolvimento local, use seu URL ngrok (configuraremos isso na próxima etapa). Para produção, use seu endpoint HTTPS.
Triggers (Gatilhos): Selecione quais eventos você deseja receber. No mínimo, habilite:
conversation:message- Recebe todas as mensagens recebidaspostback- Recebe cliques de botão e respostas rápidasconversation:start- Notifica quando uma nova conversa começa
Secret (Segredo): Gere uma string aleatória para verificação da assinatura do webhook. Isso garante que as solicitações realmente venham do Zendesk.
Salve seu ID de Webhook (exibido após a criação) e o Segredo Compartilhado que você configurou. Você precisará de ambos para verificação de assinatura.
Passo 3: Crie seu servidor webhook
Vamos construir um servidor Express.js simples que recebe e responde a mensagens.
Primeiro, inicialize seu projeto:
mkdir sunshine-integration
cd sunshine-integration
npm init -y
npm install express crypto dotenv
Crie um arquivo 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');
});
Crie um arquivo .env:
SUNSHINE_APP_ID=your_app_id
SUNSHINE_KEY_ID=your_key_id
SUNSHINE_SECRET=your_secret_key
WEBHOOK_SECRET=your_webhook_secret
Inicie seu servidor:
node index.js
Passo 4: Teste localmente com ngrok
Como o Sunshine Conversations requer um endpoint HTTPS público, use o ngrok para expor seu servidor local.
Instale o ngrok e inicie um túnel:
ngrok http 3000
Copie o URL HTTPS (algo como https://abc123.ngrok.io). Atualize sua integração de webhook no Admin Center com este URL como o URL de Destino.
Teste sua integração enviando uma mensagem por meio do Zendesk Web Widget ou qualquer canal conectado. Você deve ver a mensagem registrada no console do seu servidor, e o bot deve ecoar a mensagem de volta.
Passo 5: Configure o Switchboard para transferências de bot para agente
O Switchboard controla quando seu bot lida com mensagens versus quando agentes humanos assumem o controle. Isso é essencial para implantações de produção.
Conceitos-chave do Switchboard:
- Pass Control (Passar o Controle): Transfere imediatamente a propriedade para outra integração
- Offer Control (Oferecer o Controle): Compartilha o controle até que o destino aceite
- Release Control (Liberar o Controle): Retorna a conversa ao seu estado padrão
Para encontrar seu ID do Switchboard:
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 para um 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
}
})
}
);
}
Quando você passa o controle com metadados, o Zendesk preenche automaticamente os campos do ticket, define a prioridade e encaminha para a equipe apropriada com base em seus gatilhos.
Passo 6: Conecte canais de mensagens
Sua integração funciona com qualquer canal conectado ao Sunshine Conversations. Os canais disponíveis incluem:
- Web Widget (integrado)
- WhatsApp Business API
- Facebook Messenger
- Apple Messages for Business
- LINE
- Telegram
- SMS via Twilio ou MessageBird
- SDKs Android e iOS
Para adicionar um canal, vá para Admin Center > Canais > [Nome do Canal] e siga as etapas de autenticação. Cada canal tem requisitos específicos:
- WhatsApp: Requer verificação Meta Business e uma conta WhatsApp Business API
- Facebook/Instagram: Conecta-se por meio do seu Facebook Business Manager
- SMS: Requer uma conta Twilio ou MessageBird com um número de telefone
Uma vez conectado, todas as mensagens fluem através do mesmo endpoint de webhook, independentemente do canal. Seu código não precisa ser alterado para suportar novos canais.
Testando e depurando sua integração
Antes de entrar em operação, teste minuciosamente sua integração.
Melhores práticas de desenvolvimento local:
- Use o recurso de repetição do ngrok para reenviar webhooks durante a depuração
- Implemente o registro abrangente para cada evento recebido e ação tomada
- Crie conversas de teste e verifique o fluxo completo da mensagem para a resposta
Erros comuns e soluções:
| Erro | Causa | Solução |
|---|---|---|
| 401 Não autorizado | Assinatura de webhook inválida | Verifique se seu WEBHOOK_SECRET corresponde à configuração de integração |
| 429 Muitas solicitações | Limite de taxa excedido | Implemente a lógica de repetição com backoff exponencial |
| 403 Proibido | Credenciais de API inválidas | Verifique seu ID de chave e segredo |
| Tempo limite do webhook | Resposta do servidor > 10 segundos | Reconheça o webhook imediatamente, processe de forma assíncrona |
Limitação de taxa: O Sunshine Conversations limita as solicitações de API a 100 por minuto por padrão. Implemente o tratamento adequado:
if (response.status === 429) {
const retryAfter = response.headers.get('Retry-After');
await delay(retryAfter * 1000);
// Retry the request
}
Limites de tamanho da conversa: As conversas têm um limite de 30.000 mensagens. Arquive conversas antigas para ficar abaixo desse limite.
Melhores práticas de segurança
As integrações de produção exigem medidas de segurança adicionais.
Armazenamento de credenciais: Nunca envie credenciais para o controle de versão. Use variáveis de ambiente ou um gerenciador de segredos como AWS Secrets Manager ou HashiCorp Vault. O Zendesk segue práticas de segurança padrão do setor para proteger seus dados.
Verificação de assinatura de webhook: Sempre verifique o cabeçalho X-Smooch-Signature. Sem isso, qualquer pessoa pode enviar webhooks falsos para seu endpoint.
HTTPS apenas: O Sunshine Conversations requer HTTPS para URLs de webhook em produção. Use um certificado SSL válido.
Autenticação JWT: Para segurança aprimorada, mude de Basic Auth para 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}`;
}
Rotação de chave de API: Gere novas chaves periodicamente e revogue as antigas. O Sunshine Conversations suporta várias chaves ativas para rotação sem tempo de inatividade.
Implantando em produção
Quando estiver pronto para entrar em operação, siga esta lista de verificação.
Lista de verificação de implantação de produção:
- Mova do ngrok para um endpoint HTTPS permanente
- Implemente o tratamento de erros adequado e a lógica de repetição
- Configure o monitoramento e o alerta para falhas de webhook
- Configure a agregação de logs para depuração
- Teste as transferências do Switchboard com agentes reais
- Verifique se a limitação de taxa não afetará seu caso de uso
- Documente suas políticas de escalonamento
Recomendações de monitoramento:
Rastreie essas métricas para garantir uma integração saudável:
- Taxa de sucesso da entrega de webhook (meta: >99%)
- Tempo médio de resposta (mantenha abaixo de 5 segundos)
- Taxa de erro por tipo de erro
- Volume de conversas por canal
Configure alertas para entregas de webhook com falha, altas taxas de erro e limites de taxa de aproximação.
Alternativa: eesel AI para implementação mais rápida
Criar uma integração personalizada oferece controle total, mas requer tempo de desenvolvimento significativo e manutenção contínua. Se você precisa de mensagens com tecnologia de IA sem a sobrecarga de engenharia, considere o eesel AI como uma alternativa.
O eesel AI se conecta diretamente ao Zendesk e lida com todo o fluxo de conversação automaticamente. Em vez de construir webhooks e lógica do Switchboard, você simplesmente:
- Conecte o eesel AI à sua conta do Zendesk (integração com um clique)
- Treine o Agente de IA em seus tickets anteriores, central de ajuda e documentação
- Configure regras de escalonamento em inglês simples ("Escalar disputas de cobrança para a equipe de Finanças")
- Teste em um sandbox com tickets anteriores antes de entrar em operação
| Aspecto | Integração Personalizada | eesel AI |
|---|---|---|
| Tempo de configuração | 2-4 semanas | Minutos |
| Expertise técnica necessária | Alta (APIs, webhooks) | Baixa (sem código) |
| Capacidades de IA | Construa o seu próprio | Pré-construído com LLM |
| Manutenção | Desenvolvimento contínuo | Serviço gerenciado |
| Modelo de preços | Zendesk MAU + custos de desenvolvimento | Por interação (US$ 239-US$ 639/mês) |
As integrações personalizadas fazem sentido quando você tem sistemas proprietários que não se encaixam em padrões padrão ou precisam de fluxos de conversação altamente especializados. Para a maioria das equipes que desejam adicionar mensagens de IA ao Zendesk, o eesel AI oferece resultados mais rápidos com menos manutenção. Você pode ver o eesel em ação ou experimentá-lo gratuitamente.
Comece a construir com o Zendesk Sunshine Conversations
Agora você tem tudo o que precisa para criar uma integração personalizada com o Zendesk Sunshine Conversations. Desde a criação de chaves de API e configuração de webhooks até o tratamento do Switchboard e a implantação em produção, a base está no lugar.
As próximas etapas dependem do seu caso de uso específico. Você pode integrar com seu CRM para extrair dados do cliente, conectar-se a uma base de conhecimento para respostas inteligentes ou construir uma lógica de roteamento personalizada com base no conteúdo da mensagem.
Se a rota personalizada parecer mais engenharia do que sua equipe pode assumir agora, podemos ajudar. Nossos agentes de IA se integram ao Zendesk em minutos e lidam com as conversas de forma autônoma, enquanto escalam para sua equipe quando necessário. Você pode experimentar o eesel gratuitamente e testá-lo em tickets anteriores para ver exatamente como ele se comportaria antes de entrar em operação.
Compartilhe esta postagem
Article by
