Visão geral da API Zendesk Sunshine Conversations: Um guia do desenvolvedor para 2026
Stevia Putri
Stanley Nicholas
Last edited 20 fevereiro 2026
Expert Verified
Se você está criando uma solução de mensagens para clientes, provavelmente já enfrentou o pesadelo de gerenciar integrações separadas para WhatsApp, Facebook Messenger, SMS e chat no aplicativo. Cada canal tem sua própria API, documentação e peculiaridades. O fardo da manutenção se multiplica a cada canal que você adiciona.
Zendesk Sunshine Conversations resolve isso fornecendo uma única API REST que unifica mais de 14 canais de mensagens. Originalmente desenvolvido como Smooch.io antes de ser adquirido pelo Zendesk, o Sunshine Conversations permite que os desenvolvedores construam uma vez e implantem em todas as principais plataformas de mensagens.
Neste guia, vou detalhar exatamente o que a API Sunshine Conversations oferece, como ela funciona e o que você precisa saber para começar. Também mostrarei como o eesel AI oferece uma alternativa para equipes que desejam mensagens baseadas em IA sem criar integrações personalizadas.
O que é Zendesk Sunshine Conversations?
Sunshine Conversations é uma plataforma de mensagens multicanal que está no coração do ecossistema de experiência do cliente do Zendesk. Ele atua como uma camada de tradução entre seu aplicativo e dezenas de canais de mensagens, normalizando as peculiaridades de cada plataforma em uma API consistente.
A plataforma atende a dois públicos principais:
Para desenvolvedores, elimina a necessidade de criar integrações separadas para cada canal de mensagens. Em vez de aprender as idiossincrasias da API do WhatsApp Business, os formatos de webhook do Facebook Messenger e as peculiaridades do provedor de SMS, você se integra uma vez ao Sunshine Conversations e a plataforma cuida do resto.
Para empresas, permite conectar ferramentas existentes, como helpdesks, CRMs e plataformas de bot, aos clientes por meio de seus canais de mensagens preferidos, geralmente sem escrever código.
O legado do Smooch.io
Sunshine Conversations começou como Smooch.io, uma plataforma de mensagens independente que o Zendesk adquiriu. Você ainda encontrará referências ao Smooch na documentação legada e em alguns repositórios de SDK. A plataforma principal foi totalmente integrada ao Suite do Zendesk, mas a arquitetura da API e muitos endpoints retêm o DNA do Smooch.
Para clientes Zendesk licenciados, o URL base é https://{subdomain}.zendesk.com/sc. As contas legadas do Sunshine Conversations ainda usam https://api.smooch.io.
Principais recursos e arquitetura da API
A API Sunshine Conversations segue os princípios REST com corpos de solicitação e resposta JSON. A versão atual é a v2, embora a v1.1 permaneça compatível com integrações existentes.
Principais endpoints e recursos
A API se concentra em vários recursos principais:
| Recurso | Operações Primárias | Caso de Uso |
|---|---|---|
| Messages (Mensagens) | Send, receive, list messages (Enviar, receber, listar mensagens) | Core messaging functionality (Funcionalidade principal de mensagens) |
| Conversations (Conversas) | Create, read, update, delete conversation threads (Criar, ler, atualizar, excluir threads de conversas) | Conversation management (Gerenciamento de conversas) |
| Users (Usuários) | Profile management, authentication, merging (Gerenciamento de perfil, autenticação, mesclagem) | Customer identity (Identidade do cliente) |
| Webhooks | Subscribe to events, manage endpoints (Inscrever-se em eventos, gerenciar endpoints) | Real-time notifications (Notificações em tempo real) |
| Attachments (Anexos) | Upload, retrieve media files (Carregar, recuperar arquivos de mídia) | Rich messaging support (Suporte para mensagens avançadas) |
Todos os endpoints usam métodos HTTP padrão: GET para recuperação, POST para criação, PATCH para atualizações e DELETE para remoção. A API retorna formatos de erro consistentes com códigos de status HTTP e objetos de erro descritivos.
Paginação e limites
Sunshine Conversations usa paginação baseada em cursor em vez de paginação de deslocamento. Essa abordagem evita problemas de desempenho com grandes conjuntos de dados, retornando um ponteiro para um item específico em vez de números de página.
Você pode usar os parâmetros de consulta page[after] ou page[before] para navegar para frente ou para trás nos resultados. Um parâmetro page[size] opcional controla o número de registros retornados por solicitação.
Esteja ciente destes limites rígidos:
| Limite | Valor | Impacto |
|---|---|---|
| Messages per conversation (Mensagens por conversa) | 30,000 | Older conversations need archiving (Conversas mais antigas precisam ser arquivadas) |
| JSON request size (Tamanho da solicitação JSON) | 100KB | Large payloads will be rejected (Cargas úteis grandes serão rejeitadas) |
| File upload size (Tamanho do upload de arquivo) | 50MB | Media attachments have size caps (Anexos de mídia têm limites de tamanho) |
| Rate limiting (Limitação de taxa) | Variable (Variável) | 429 status code when exceeded (Código de status 429 quando excedido) |
Quando você atinge os limites de taxa, a API retorna um status 429 Too Many Requests (Muitas solicitações). Implemente backoff exponencial com jitter em vez de intervalos de repetição fixos. Picos de uso são esperados e os limites são projetados para serem generosos para operações normais.
Autenticação e segurança
Sunshine Conversations oferece suporte a dois métodos de autenticação, cada um adequado para diferentes casos de uso.
Autenticação básica
Para chamadas de API de servidor para servidor, a autenticação básica é a abordagem mais simples. Você usa o ID da sua chave de API como nome de usuário e o segredo como senha no formato de autenticação básica HTTP padrão.
Este método funciona bem para integrações de back-end onde você está fazendo chamadas do seu servidor para a API Sunshine Conversations. É simples de implementar e depurar.
Autenticação JWT
JSON Web Tokens (JWTs) fornecem uma opção de autenticação mais flexível, particularmente útil quando você precisa restringir o acesso ou quando passa credenciais por canais menos seguros.
Para gerar um JWT, você precisa de:
- Header (Cabeçalho) com algoritmo (HS256) e ID da chave
- Payload (Carga útil) com declaração de escopo (conta, aplicativo ou integração)
- Signature (Assinatura) usando seu segredo de API
Os JWTs são transmitidos no cabeçalho Authorization com o prefixo Bearer: Authorization: Bearer your-jwt-token.
Escopos de autorização
A API usa três escopos de autorização principais que determinam quais operações são permitidas:
| Escopo | Nível de Acesso | Melhor Para |
|---|---|---|
| account (conta) | All methods including account provisioning (Todos os métodos, incluindo provisionamento de conta) | Multi-tenant SaaS applications (Aplicativos SaaS multi-inquilino) |
| app (aplicativo) | All Core API methods (Todos os métodos da API principal) | Single application integrations (Integrações de aplicativo único) |
| integration (integração) | Users, Conversations, Attachments, Webhooks (Usuários, Conversas, Anexos, Webhooks) | Limited third-party integrations (Integrações limitadas de terceiros) |
As chaves de API seguem uma convenção de nomenclatura que indica seu escopo: as chaves de conta começam com act_, as chaves de conta de serviço com svc_ e as chaves de aplicativo com app_.
Canais de mensagens suportados
Sunshine Conversations oferece suporte à gama mais abrangente de canais de mensagens do setor. Todos os canais são acessíveis por meio da mesma API, com a plataforma lidando com a tradução entre formatos específicos do canal e a API unificada.
Aplicativos de mensagens de terceiros
- WhatsApp Business API - Suporte total para mensagens comerciais, modelos e mídia rica
- Facebook Messenger - Integração completa com botões, respostas rápidas e webviews
- Instagram Direct - Mensagens por meio de contas comerciais do Instagram
- Apple Messages for Business - Integração com a plataforma de mensagens comerciais da Apple
- LINE, Telegram, Viber - Suporte total para as principais plataformas de mensagens asiáticas e europeias
- Twitter DM - Mensagens diretas pelo Twitter
- WeChat - Suporte para a plataforma de mensagens dominante da China
Provedores de SMS e voz
- Twilio - Integração de SMS por meio da infraestrutura do Twilio
- MessageBird - Integração alternativa de provedor de SMS
SDKs criados pelo Zendesk
- Web Messenger - Widget de chat incorporável para sites
- Android SDK - Mensagens nativas no aplicativo Android
- iOS SDK - Mensagens nativas no aplicativo iOS
- Unity SDK - Integração de jogos e aplicativos 3D
A plataforma oferece suporte a recursos de mensagens avançadas em todos os canais onde disponíveis, incluindo mensagens estruturadas, respostas rápidas, carrosséis e compartilhamento de arquivos. Quando os canais adicionam novos recursos, o Sunshine Conversations normalmente é atualizado para suportá-los com o mínimo de alterações de código necessárias de sua parte.
Ferramentas de desenvolvedor e SDKs
Embora você possa interagir com a API Sunshine Conversations diretamente via HTTP, o Zendesk fornece SDKs oficiais que envolvem a API e lidam com autenticação, tratamento de erros e formatação de solicitações.
SDKs oficiais
| Linguagem | Pacote/Repositório | Status |
|---|---|---|
| Java | sunshine-conversations-java | Actively maintained (Ativamente mantido) |
| Ruby | sunshine-conversations-ruby | Auto-generated from OpenAPI (Gerado automaticamente a partir do OpenAPI) |
| Python | sunshine-conversations-client | PyPI package, auto-generated (Pacote PyPI, gerado automaticamente) |
| JavaScript | sunshine-conversations-javascript | Community maintained (Mantido pela comunidade) |
O SDK Java recebe a manutenção mais ativa do Zendesk. Os SDKs Ruby e Python são gerados automaticamente a partir da especificação OpenAPI, garantindo que permaneçam atualizados com as alterações da API, mas potencialmente carecendo de ergonomia artesanal.
Ferramentas de desenvolvimento
Para testes e exploração, o Zendesk fornece uma coleção Postman que inclui todos os endpoints com solicitações de exemplo. A especificação OpenAPI está disponível publicamente para gerar clientes ou documentação personalizados.
Integração de Webhook
O tratamento de eventos em tempo real acontece por meio de webhooks. Seu servidor expõe um endpoint que recebe solicitações POST quando os eventos ocorrem, como mensagens recebidas, confirmações de entrega ou alterações no estado da conversa.
Os gatilhos de webhook comuns incluem:
| Gatilho | Quando é Acionado |
|---|---|
| conversation:message (conversa:mensagem) | Customer or agent sends a message (Cliente ou agente envia uma mensagem) |
| postback | User clicks a button or quick reply (Usuário clica em um botão ou resposta rápida) |
| conversation:created (conversa:criada) | New conversation starts (Nova conversa começa) |
| conversation:typing (conversa:digitando) | User is typing indicator (Indicador de que o usuário está digitando) |
Você precisará verificar as assinaturas do webhook usando o segredo compartilhado fornecido quando você cria a integração do webhook para garantir que os eventos sejam genuinamente do Sunshine Conversations.
Integração com o ecossistema Zendesk
Sunshine Conversations não existe isoladamente. Ele está profundamente integrado à plataforma Zendesk mais ampla, o que pode acelerar o desenvolvimento ou fornecer abordagens alternativas, dependendo do seu caso de uso.
Web Widget
O Web Widget fornece uma interface de chat voltada para o cliente que é incorporada em seu site ou central de ajuda. Ele usa o Sunshine Conversations por baixo dos panos, então as conversas iniciadas por meio do widget fluem pela mesma API que você usa para outros canais.
Agent Workspace
Quando as conversas precisam de intervenção humana, elas aparecem no Agent Workspace do Zendesk como tickets. Os agentes podem responder diretamente e suas mensagens fluem de volta pelo Sunshine Conversations para o cliente em seu canal original. Isso oferece a você uma interface de agente unificada, mesmo quando os clientes estão espalhados por uma dúzia de plataformas de mensagens.
Switchboard
O Switchboard controla o roteamento de conversas entre bots, sistemas de IA e agentes humanos. Você pode passar programaticamente o controle entre os sistemas, mantendo o contexto da conversa. Isso permite fluxos de trabalho sofisticados, como triagem inicial por bot com escalonamento contínuo para humanos.
Na eesel AI, aproveitamos esses pontos de integração para fornecer atendimento ao cliente com tecnologia de IA que funciona nativamente no Zendesk. Nossos agentes de IA podem lidar com conversas por meio do Sunshine Conversations, escalar para agentes humanos quando necessário e manter o contexto completo durante toda a interação.
Preços e acesso do Zendesk Suite
O acesso à API Sunshine Conversations requer planos Zendesk Suite específicos. Nem todos os níveis incluem todos os recursos da plataforma.
| Plano | Preço Anual | Acesso ao Sunshine Conversations | MAUs Incluídos |
|---|---|---|---|
| Suite Team | $55/agente/mês | Basic messaging only (Apenas mensagens básicas) | N/A |
| Suite Growth | $89/agente/mês | Basic messaging only (Apenas mensagens básicas) | N/A |
| Suite Professional | $115/agente/mês | Full API access (Acesso total à API) | 1,000 |
| Suite Enterprise | $169/agente/mês | Full API access (Acesso total à API) | 1,000 |
Diferenciação chave: Suite Team e Growth incluem mensagens por meio do Web Widget, mas não fornecem acesso total à API para integrações personalizadas. Para criar suas próprias integrações com a API Sunshine Conversations, você precisa do Suite Professional ou Enterprise.
Usuários Ativos Mensais (MAUs) representam usuários únicos que enviam ou recebem mensagens dentro de um período de 30 dias. Se você exceder seus MAUs incluídos, pacotes adicionais estarão disponíveis a aproximadamente US$ 50 por 2.500 MAUs.
Fonte: Zendesk Pricing
Começando com o desenvolvimento do Sunshine Conversations
Se você está pronto para construir com o Sunshine Conversations, aqui está o que você precisa para começar.
Pré-requisitos
- Zendesk Suite Professional ou Enterprise - Necessário para acesso total à API
- Acesso ao Admin Center - Para gerar chaves de API e configurar canais
- Ambiente de desenvolvimento - Um servidor ou função de nuvem para receber webhooks
- Conhecimento básico de APIs REST - Para fazer chamadas de API e lidar com respostas
Etapas de início rápido
-
Gerar chaves de API - No Admin Center, navegue até Aplicativos e integrações > APIs > API de conversas. Crie uma nova chave e armazene com segurança o ID do aplicativo, o ID da chave e o segredo.
-
Configurar um endpoint de webhook - Crie um endpoint HTTPS acessível publicamente que possa receber solicitações POST. Para desenvolvimento local, ferramentas como ngrok podem criar túneis para sua máquina.
-
Configurar seu primeiro canal - No Admin Center, habilite um canal de mensagens (o Web Widget é o mais fácil para começar) e conecte-o ao seu aplicativo Sunshine Conversations.
-
Testar a integração - Envie uma mensagem pelo canal escolhido e verifique se ela chega ao seu endpoint de webhook. Em seguida, tente enviar uma resposta de volta pela API.
Para um passo a passo mais detalhado, consulte nosso guia completo para começar.
eesel AI: Mensagens baseadas em IA sem desenvolvimento personalizado
Criar integrações personalizadas com o Sunshine Conversations requer recursos de desenvolvimento significativos. Se seu objetivo é o atendimento ao cliente com tecnologia de IA, em vez de construir uma plataforma de mensagens personalizada, considere se você precisa construir.
Na eesel AI, fornecemos agentes de IA que se integram diretamente ao Zendesk, lidando com a complexidade do Sunshine Conversations, orquestração do Switchboard e mensagens multicanal sem exigir desenvolvimento personalizado. Você obtém atendimento ao cliente com tecnologia de IA que funciona em todos os canais de mensagens, com escalonamento humano e integração total do Zendesk, sem escrever código.
Para equipes que desejam adicionar recursos de chat com IA ao seu helpdesk existente, nosso chatbot de IA funciona em canais de mensagens com a mesma abordagem unificada do Sunshine Conversations, mas sem a sobrecarga de desenvolvimento. Se você precisar de ajuda para gerenciar o volume de tickets, o AI Triage roteia, marca e prioriza automaticamente os tickets antes que eles cheguem aos seus agentes.
Perguntas frequentes
Compartilhe esta postagem
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.
