Como começar com o Zendesk Sunshine Conversations em 2026

Como começar com o Zendesk Sunshine Conversations em 2026

O Zendesk Sunshine Conversations traz todos os seus canais de mensagens de clientes para uma API unificada. Quer os clientes entrem em contato via WhatsApp, Facebook Messenger, Instagram ou chat do seu site, o Sunshine Conversations permite que você gerencie cada conversa de um único lugar. Mas configurá-lo não é algo simples. Este guia técnico detalha exatamente o que você precisa, passo a passo, para fazê-lo funcionar sem as habituais tentativas e erros.

Este guia cobre tudo o que você precisa para configurar o Sunshine Conversations do zero: os pré-requisitos, configuração da API, configuração de webhook, conexões de canais e transferências (handoffs) de bots. Também veremos como ferramentas como o eesel AI podem simplificar as integrações do Zendesk para equipes que não desejam construir soluções de API personalizadas.

Aviso justo: este é um guia técnico. Você precisará de recursos de desenvolvedor para implementar o Sunshine Conversations totalmente. Mas mesmo que você seja um gerente de projeto ou uma parte interessada do negócio avaliando a plataforma, você sairá daqui entendendo o que está envolvido.

O que é o Zendesk Sunshine Conversations?

O Sunshine Conversations é a plataforma de mensagens multicanal do Zendesk que unifica as conversas dos clientes em mais de 14 canais de mensagens por meio de uma única API REST. Originalmente um produto independente chamado Smooch.io, agora está totalmente integrado ao Zendesk Suite.

A plataforma segue uma arquitetura API-first. Em vez de gerenciar integrações separadas para WhatsApp, Facebook Messenger, SMS e chat no aplicativo, você conecta todos ao Sunshine Conversations e gerencia as mensagens programaticamente por meio de uma API unificada.

Aqui está onde o Sunshine Conversations se encaixa no ecossistema Zendesk:

Componente	O que faz
API Sunshine Conversations	API de mensagens unificada para todos os canais
Web Widget para Mensagens	Widget de chat voltado para o cliente para sites
Switchboard	Encaminha conversas entre bots e agentes humanos
Espaço de Trabalho do Agente	Onde sua equipe de suporte gerencia conversas escaladas

O Switchboard é particularmente importante. Ele controla qual sistema (seu bot, uma IA de terceiros ou um agente humano) gerencia cada conversa a qualquer momento. Quando um cliente faz uma pergunta que seu bot não consegue responder, o Switchboard passa o controle para um agente humano, preservando todo o histórico da conversa.

Pré-requisitos para a configuração do Zendesk Sunshine Conversations

Antes de começar a configurar o Sunshine Conversations, você precisará atender a vários requisitos. Resolver isso antecipadamente evita dores de cabeça mais tarde.

Requisitos de plano do Zendesk

Nem todo plano do Zendesk inclui acesso total ao Sunshine Conversations. Aqui está o que você precisa saber:

Plano	Preço (Anual)	Acesso ao Sunshine Conversations	MAUs Incluídos
Suite Team	US$ 55/agente/mês	Apenas mensagens básicas	N/A
Suite Growth	US$ 89/agente/mês	Apenas mensagens básicas	N/A
Suite Professional	US$ 115/agente/mês	Acesso total à API	1.000 MAUs
Suite Enterprise	US$ 169/agente/mês	Acesso total à API	1.000 MAUs

Os Usuários Ativos Mensais (MAUs) contam qualquer usuário único que envia ou recebe uma mensagem em um período de 30 dias. Os 1.000 MAUs básicos estão incluídos no Professional e superiores. Se precisar de mais, pacotes adicionais de 2.500 MAUs custam aproximadamente US$ 50 cada.

Se você estiver no Suite Team ou Growth, terá mensagens básicas através do Web Widget, mas não terá acesso total à API de Conversas. Para integrações personalizadas e a funcionalidade completa do Switchboard, você precisa do Suite Professional ou superior.

Requisitos técnicos

Você precisará de:

• Espaço de Trabalho do Agente do Zendesk ativado em sua conta
• Acesso de administrador ao Zendesk Admin Center
• Um servidor ou cloud function para receber eventos de webhook
• Compreensão básica de APIs REST e autenticação
• Ambiente de desenvolvimento (Node.js é recomendado com base nos exemplos oficiais)

Para o desenvolvimento local, o ngrok é inestimável. Ele cria uma URL pública que faz o túnel para sua máquina local, para que você possa testar webhooks sem implantar em produção.

Guia passo a passo de configuração do Zendesk Sunshine Conversations

Agora, a parte prática. Vamos percorrer cada etapa para fazer uma integração básica do Sunshine Conversations funcionar.

Passo 1: Instalar o Web Widget para mensagens

O Web Widget é o componente voltado para o cliente que aparece no seu site ou central de ajuda.

Para instalar em um site:

1. No Admin Center, clique em Canais > Mensagens e redes sociais > Mensagens
2. Clique no nome do widget que deseja configurar
3. Role para baixo e expanda a seção Instalação
4. Copie o trecho de código
5. Cole-o antes da tag de fechamento </body> em cada página onde deseja o widget

Para instalar em uma central de ajuda:

1. Navegue até as mesmas configurações de Mensagens
2. Expanda Instalação
3. Marque "Incorporar automaticamente o Web Widget na sua Central de Ajuda"
4. Clique em Salvar

A instalação na central de ajuda é um processo de um clique. Nenhum código é necessário.

Para layouts avançados (como incorporar o widget em um contêiner específico em vez de uma sobreposição flutuante), você pode usar o modo incorporado:

window.zEMessenger = {
  autorender: false
}

zE('messenger', 'render', {
  mode: 'embedded',
  widget: {
    targetElement: '#messaging-container'
  }
});

Passo 2: Criar chaves de API para autenticação

Cada chamada de API para o Sunshine Conversations requer autenticação. Você precisará de três credenciais:

1. App ID: Identifica seu aplicativo Sunshine Conversations
2. Key ID: Usado como nome de usuário para Basic Auth
3. Secret Key: Usada como senha (mostrada apenas uma vez na criação)

Para criar chaves de API:

1. Vá para Admin Center > Apps e integrações > APIs > Conversations API
2. Clique em Criar chave de API
3. Insira um nome descritivo (ex: "Integração de Bot de Produção")
4. Copie o App ID, Key ID e Secret Key imediatamente

A Secret Key é exibida apenas uma vez. Armazene-a com segurança em seu gerenciador de segredos ou variáveis de ambiente. Se você a perder, precisará criar uma nova chave de API.

Passo 3: Configurar uma integração de webhook

Os webhooks permitem que seu servidor receba notificações em tempo real quando mensagens chegam ou eventos ocorrem.

Para criar um webhook:

1. Navegue até Admin Center > Apps e integrações > Integrações > Conversations integrations
2. Clique em Criar integração
3. Insira a URL do endpoint do seu webhook (ex: https://seu-dominio.com/messages)
4. Selecione os gatilhos do webhook (no mínimo, ative conversation:message)
5. Salve a integração
6. Anote o Webhook ID e o Shared Secret para verificação de assinatura

Gatilhos de webhook comuns que você desejará ativar:

Gatilho	Quando dispara
conversation:message	Cliente ou agente envia uma mensagem
postback	Cliente clica em um botão ou resposta rápida
conversation:created	Uma nova conversa começa
conversation:typing	O usuário está digitando

Passo 4: Implantar seu servidor de webhook

Seu servidor precisa expor um endpoint POST que receba payloads de webhook do Sunshine Conversations.

Aqui está um exemplo mínimo usando Node.js:

const express = require('express');
const app = express();

app.use(express.json());

app.post('/messages', (req, res) => {
  const payload = req.body;
  console.log('Webhook recebido:', JSON.stringify(payload, null, 2));

  // Lidar com a mensagem com base no tipo
  if (payload.trigger === 'conversation:message') {
    const message = payload.payload.message;
    console.log(`Mensagem de ${message.author.type}: ${message.content.text}`);
  }

  res.status(200).send('OK');
});

app.listen(8000, () => console.log('Servidor de webhook rodando na porta 8000'));

Para desenvolvimento local, use o ngrok para criar um túnel público:

ngrok http 8000

Copie a URL HTTPS que o ngrok fornece e use-a como seu endpoint de webhook no Passo 3.

Passo 5: Enviar sua primeira mensagem de API

Agora teste o envio de uma mensagem do seu servidor para uma conversa de cliente.

O formato do endpoint é:

POST https://{subdominio}.zendesk.com/sc/v2/apps/{app_id}/conversations/{conversation_id}/messages

Aqui está um exemplo usando curl:

curl -X POST \
  "https://suaempresa.zendesk.com/sc/v2/apps/SEU_APP_ID/conversations/CONVERSATION_ID/messages" \
  -u "KEY_ID:SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "author": {
      "type": "business"
    },
    "content": {
      "type": "text",
      "text": "Olá! Obrigado pelo contato. Como posso ajudar você hoje?"
    }
  }'

Substitua os espaços reservados por suas credenciais reais e o ID da conversa. O ID da conversa vem do payload do webhook quando um cliente inicia um chat.

Conectando canais de mensagens ao Zendesk Sunshine Conversations

Assim que sua integração básica estiver funcionando, você poderá conectar canais de mensagens adicionais. O Sunshine Conversations suporta uma ampla gama de plataformas.

Tipo de Canal	Exemplos
Mensagens sociais	WhatsApp, Facebook Messenger, Instagram, Twitter DM
Aplicativos de chat	LINE, Telegram, WeChat, Viber
Provedores de SMS	Twilio, MessageBird
SDKs nativos	iOS SDK, Android SDK, Web Messenger
Mensagens comerciais	Apple Messages for Business

Para adicionar um canal:

1. Vá para Admin Center > Canais > Mensagens e redes sociais > Mensagens
2. Selecione o tipo de canal que deseja adicionar
3. Conclua a autenticação específica da plataforma
4. Vincule o canal ao seu aplicativo Sunshine Conversations

Cada canal tem seus próprios requisitos. O WhatsApp requer aprovação da API Business da Meta. O Facebook e o Instagram requerem verificação da Meta Business. Canais de SMS incorrem em custos por mensagem do seu provedor (Twilio, MessageBird, etc.).

A vantagem é que, uma vez conectados, todos os canais fluem pela mesma API. Sua lógica de bot e fluxos de trabalho de agentes lidam com as mensagens da mesma maneira, independentemente de onde elas se originaram.

Para equipes que gerenciam um suporte omnichannel complexo, essa abordagem unificada simplifica tanto o desenvolvimento quanto as operações. As equipes também podem explorar chatbots de IA para Zendesk como uma alternativa ao desenvolvimento personalizado.

Configurando o Switchboard para transferências de bot para agente no Zendesk Sunshine Conversations

O Switchboard é o que torna o Sunshine Conversations poderoso para equipes que usam bots de IA junto com agentes humanos. Ele controla qual integração gerencia cada conversa e permite transferências suaves.

Operações principais do Switchboard

Operação	Finalidade	Caso de Uso
Pass Control	Transfere a propriedade imediatamente	Bot escala para agente humano
Offer Control	Compartilha o controle até que o alvo aceite	Transferência gradual com aceitação
Release Control	Retorna ao estado padrão	Conversa concluída

Encontrando seus IDs de Switchboard e de respondedor

Antes de configurar as transferências, você precisa do seu ID de Switchboard e dos IDs de respondedor para cada integração.

Passo 1: Obtenha seu ID de Switchboard

Use a API List Switchboards:

GET https://api.smooch.io/v2/apps/{appId}/switchboards

Para residência de dados na UE:

GET https://api.eu-1.smooch.io/v2/apps/{appId}/switchboards

Clientes licenciados do Zendesk usam um host diferente:

GET https://{subdominio}.zendesk.com/sc/v2/apps/{appId}/switchboards

Passo 2: Obtenha seus IDs de respondedor

GET https://{subdominio}.zendesk.com/sc/v2/apps/{appId}/switchboards/{switchboardId}/switchboardIntegrations

Isso retorna todas as integrações registradas no seu Switchboard, incluindo seu bot e o Espaço de Trabalho do Agente do Zendesk.

Implementando a transferência de bot para agente

Quando seu bot determinar que deve escalar para um humano, chame o endpoint Pass Control:

POST /v2/apps/{appId}/conversations/{conversationId}/passControl

Inclua metadados para preencher os campos do ticket durante a transferência:

{
  "switchboardIntegration": "next",
  "metadata": {
    "zendesk:ticket_subject": "Cliente precisa de ajuda com faturamento",
    "zendesk:ticket_tags": "escalonamento, faturamento"
  }
}

Comportamento de transferência e retorno

Quando o controle passa para um agente humano:

1. Um ticket é criado automaticamente no Espaço de Trabalho do Agente
2. Os agentes veem o histórico completo da conversa da interação com o bot
3. O agente permanece como o primeiro respondedor até que o status do ticket mude para Fechado

O tempo padrão de Resolvido para Fechado é de 4 dias. Durante esse tempo, se o cliente retornar, ele ainda estará conectado à mesma conversa com o agente humano.

Para fechar tickets mais rapidamente para retorno imediato ao bot, crie um gatilho:

• Condição: Tags contém "fechar"
• Ação: Definir Status como Fechado

Adicione a tag "fechar" ao marcar os tickets como Resolvidos, e eles serão fechados imediatamente.

eesel AI: Uma alternativa mais simples para começar com as mensagens do Zendesk

O Sunshine Conversations é poderoso, mas requer recursos significativos de desenvolvimento. Você precisa de engenheiros para construir o servidor de webhook, implementar as chamadas de API, lidar com erros e manter a integração ao longo do tempo.

Nem toda equipe tem essa capacidade. Se você deseja mensagens baseadas em IA sem construir uma integração personalizada, o eesel AI oferece uma abordagem diferente.

Como simplificamos a integração com o Zendesk

Nós nos conectamos diretamente à sua instância do Zendesk sem desenvolvimento de API personalizada. Você não precisa construir servidores de webhook ou gerenciar credenciais de API. A configuração leva minutos, não semanas.

Veja como funciona:

1. Conecte o eesel à sua conta Zendesk
2. Nós aprendemos com sua central de ajuda existente, tickets anteriores e macros
3. Configure regras de escalonamento em linguagem simples (sem código)
4. Teste com simulações em tickets históricos
5. Entre no ar com respostas baseadas em IA

Nosso Agente de IA gerencia tickets de linha de frente de forma autônoma. Ele lê as mensagens recebidas, elabora respostas fundamentadas em sua base de conhecimento e as envia. Quando encontra algo que não consegue resolver, ele escala para um agente humano com todo o contexto preservado.

Quando escolher cada abordagem

Caso de Uso	Melhor Opção
Fluxos de trabalho de mensagens personalizados	API Sunshine Conversations
Automação rápida de suporte por IA	eesel AI
Multicanal de alto volume (mais de 14 canais)	Sunshine Conversations + recursos de desenvolvedor
Equipes sem capacidade de engenharia	eesel AI
Orquestração complexa de bots	Switchboard do Sunshine Conversations
Transferências simples de bot para agente	eesel AI

Se você precisa de todo o poder do Sunshine Conversations (integrações personalizadas, múltiplos canais além do chat web, lógica de roteamento complexa), a abordagem de API faz sentido. Mas se o seu objetivo é automatizar o suporte do Zendesk com IA sem construir infraestrutura, o eesel AI resolve isso nativamente.

Para equipes que já usam o sistema de tickets do Zendesk, nós nos integramos diretamente aos seus fluxos de trabalho existentes. Nenhuma API separada para manter.

Problemas comuns de solução de problemas com o Zendesk Sunshine Conversations

Mesmo com uma configuração cuidadosa, você provavelmente encontrará alguns problemas comuns. Veja como resolvê-los.

Falhas na verificação de assinatura de webhook

Se o seu endpoint de webhook rejeitar as solicitações do Zendesk devido a assinaturas inválidas, verifique:

1. Você está usando o Shared Secret correto das configurações de integração do seu webhook
2. A lógica de validação de assinatura corresponde à especificação do Zendesk (HMAC SHA256)
3. Seu servidor recebe o cabeçalho X-API-Key corretamente

Exemplo de validação em Node.js:

const crypto = require('crypto');

function validateSignature(req) {
  const signature = req.headers['x-api-key'];
  const secret = process.env.WEBHOOK_SECRET;
  const payload = JSON.stringify(req.body);

  const hash = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return signature === hash;
}

Erros de CORS com o Web Widget

Se o seu widget não carregar devido a violações da política CORS, verifique:

• O domínio do seu site foi adicionado às origens permitidas no Admin Center
• O script do widget é carregado do CDN do Zendesk, não auto-hospedado
• Seus cabeçalhos de Política de Segurança de Conteúdo (CSP) permitem *.zdassets.com e *.zendesk.com

Limitação de taxa (Rate limiting) e estrangulamento de API

A API do Sunshine Conversations tem limites de taxa por conta:

• Nível padrão: 120 solicitações por minuto
• Nível de alto volume: Limites personalizados disponíveis sob consulta

Se você estiver atingindo os limites de taxa:

1. Implemente o backoff exponencial em sua lógica de repetição
2. Agrupe operações sempre que possível
3. Armazene em cache IDs de conversa e dados de usuário para reduzir chamadas de busca
4. Entre em contato com o suporte do Zendesk para solicitar limites mais altos, se necessário

Mensagens não aparecendo no Espaço de Trabalho do Agente

Se as mensagens enviadas via API não estiverem visíveis para os agentes:

• Verifique se a conversa foi criada corretamente antes de enviar mensagens
• Verifique se o author.type da mensagem está definido como business ou user corretamente
• Certifique-se de que o Espaço de Trabalho do Agente está ativado para sua conta
• Confirme se a conversa não foi arquivada ou fechada

Começando com o Zendesk Sunshine Conversations hoje

Aqui está um checklist rápido para colocar o Sunshine Conversations em funcionamento:

Passo	Ação
1	Verifique se você tem o Suite Professional ou superior (mínimo de US$ 115/agente/mês)
2	Ative o Espaço de Trabalho do Agente no Admin Center
3	Crie chaves de API e armazene as credenciais com segurança
4	Instale o Web Widget em seu site ou central de ajuda
5	Configure a integração de webhook para manipulação de mensagens
6	Teste em um ambiente de sandbox antes da produção
7	Monitore o uso de MAU em relação aos seus limites incluídos (1.000 básicos)

Próximos passos para implementação avançada

Assim que o básico estiver funcionando, explore:

• Tipos de mensagens ricas: Carrosséis, botões, respostas rápidas para conversas interativas
• Autenticação de usuário: Autenticação baseada em JWT para experiências personalizadas
• Fluxos de bot personalizados: Implemente árvores de conversação com o Switchboard
• Expansão de canais: Conecte WhatsApp, Facebook Messenger ou SMS
• Automação de IA: Considere integrar suporte ao cliente baseado em IA para reduzir a carga de trabalho manual

Experimente o eesel AI para resultados mais rápidos

Se você preferir pular o trabalho de desenvolvimento e colocar o suporte do Zendesk baseado em IA para funcionar rapidamente, inicie um teste gratuito com o eesel AI. Conecte suas fontes de conhecimento, configure regras de escalonamento e entre no ar sem escrever uma única linha de código.

Para equipes que avaliam os preços do Zendesk AI e seus recursos, oferecemos uma alternativa direta: pague por interação, não por assento de agente. Nenhum desenvolvimento de API é necessário.