zendesk-sunshine-conversations-user-data-ai-agents
eesel Team
Last edited 20 fevereiro 2026
{
"title": "Como acessar e usar dados do usuário no Zendesk Sunshine Conversations para agentes de IA",
"slug": "zendesk-sunshine-conversations-user-data-ai-agents",
"locale": "pt",
"date": "2026-02-20",
"updated": "2026-02-20",
"template": "default",
"excerpt": "Um guia técnico para acessar dados do usuário no Zendesk Sunshine Conversations, cobrindo a API de Usuário, API de Clientes, passagem de metadados e padrões de implementação prática para agentes de IA.",
"categories": [
"Blog Writer AI"
],
"tags": [
"Zendesk",
"Sunshine Conversations",
"AI agents",
"user data",
"API integration"
],
"readTime": 14,
"author": 16,
"reviewer": 14,
"seo": {
"title": "Como acessar e usar dados do usuário no Zendesk Sunshine Conversations para agentes de IA",
"description": "Um guia técnico para acessar dados do usuário no Zendesk Sunshine Conversations, cobrindo a API de Usuário, API de Clientes, passagem de metadados e padrões de implementação prática para agentes de IA.",
"image": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-621a5d12-46fe-402d-a6be-1b4486953e76"
},
"coverImage": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-621a5d12-46fe-402d-a6be-1b4486953e76",
"coverImageAlt": "Imagem do banner para Como acessar e usar dados do usuário no Zendesk Sunshine Conversations para agentes de IA",
"coverImageWidth": 1920,
"coverImageHeight": 1080,
"faqs": {
"heading": "Perguntas Frequentes",
"type": "blog",
"answerType": "html",
"faqs": [
{
"question": "Qual plano do Zendesk preciso para acessar dados do usuário no Sunshine Conversations para agentes de IA?",
"answer": "Você precisa do Zendesk Suite Professional ou superior, mais o complemento AI agents Advanced. O plano Suite Professional inclui acesso à API Conversations, enquanto o complemento Advanced desbloqueia o Integration Builder, onde você configura chamadas de API."
},
{
"question": "Posso acessar dados do usuário sem usar o Integration Builder?",
"answer": "Sim, você pode fazer chamadas de API diretamente para o Sunshine Conversations a partir de seus próprios servidores ou aplicativos. O Integration Builder é a interface sem código do Zendesk para as mesmas APIs subjacentes. Se você preferir escrever código, pode usar a API REST diretamente com as mesmas credenciais de autenticação."
},
{
"question": "Os dados do cliente estão seguros ao usar essas APIs?",
"answer": "O Sunshine Conversations criptografa os dados em trânsito e em repouso. As chamadas de API usam HTTPS e a autenticação requer sua chave secreta. Siga as práticas recomendadas de segurança: armazene as credenciais em variáveis de ambiente, gire as chaves periodicamente e use chaves separadas para ambientes de desenvolvimento e produção."
},
{
"question": "O que acontece se um usuário não forneceu seu nome ou outras informações de perfil?",
"answer": "Os campos da API retornarão valores nulos ou vazios. Sempre crie uma lógica de fallback em seus diálogos. Verifique se {{givenName}} existe antes de usá-lo em saudações e tenha mensagens alternativas prontas para quando os dados do perfil estiverem incompletos."
},
{
"question": "Posso atualizar as informações do perfil do usuário por meio da API?",
"answer": "Atualizações limitadas são possíveis. Você pode atualizar os metadados da conversa e algumas propriedades do usuário, mas os campos de perfil principais, como sobrenome e givenName, geralmente são somente leitura depois de definidos. Para atualizar as informações do usuário, talvez seja necessário usar a API principal de Usuários do Zendesk em vez da API do Sunshine Conversations."
}
],
"supportLink": null
}
}
---
Experiências de cliente personalizadas começam com o conhecimento de com quem você está falando. Quando um cliente entra em contato com seu agente de IA, ele espera mais do que respostas genéricas. Eles querem que você saiba o nome deles, entenda o histórico deles e tenha contexto sobre o problema deles. Os dados do usuário no [Zendesk Sunshine Conversations](https://developer.zendesk.com/api-reference/conversations/) tornam isso possível.
O Sunshine Conversations serve como a camada de mensagens sob os agentes de IA do Zendesk, lidando com tudo, desde mensagens do WhatsApp até bate-papo na web. Mas acessar os dados do usuário armazenados nele requer a compreensão da [arquitetura da API](https://developer.zendesk.com/documentation/conversations/how-to-guides/messaging-user-data-ai-agents-advanced/) e saber quais endpoints chamar. Este guia explica exatamente como recuperar e usar os dados do cliente para criar experiências de agente de IA mais personalizadas.
Se você está procurando uma abordagem mais simples que não exija a criação de integrações de API personalizadas, oferecemos uma alternativa. Nossa plataforma se conecta diretamente ao Zendesk e lida com o acesso aos dados do usuário automaticamente. Mas se você estiver criando soluções personalizadas ou precisar de controle total sobre o fluxo de dados, este guia técnico mostrará exatamente o que você precisa saber.
## Entendendo a arquitetura de dados do Sunshine Conversations
O Sunshine Conversations (anteriormente Smooch.io) opera como a camada de dados subjacente para todas as interações de mensagens no Zendesk. Originalmente um produto independente, agora está totalmente integrado ao Zendesk Suite e lida com o trabalho pesado de roteamento de mensagens entre clientes, agentes de IA e agentes humanos. A plataforma fornece uma [API de mensagens unificada](https://developer.zendesk.com/api-reference/conversations/) que conecta vários canais a uma única interface de conversa.
Veja como os dados fluem: quando um cliente envia uma mensagem via WhatsApp, widget da web ou qualquer outro canal, o Sunshine Conversations recebe essa mensagem, identifica o usuário e a encaminha para o manipulador apropriado. Seu agente de IA então interage com o Sunshine Conversations para acessar perfis de usuário, histórico de conversas e metadados.
A plataforma armazena dados do usuário em vários locais distintos:
**Objeto Usuário (User object)**: Contém informações básicas do perfil, incluindo o ID do usuário, nome (profile.surname e profile.givenName), endereço de e-mail, preferências de localidade, status de autenticação e quando se inscreveram pela primeira vez (signedUpAt). O endpoint da API de Usuário (User API) dá acesso a tudo isso.
**Objeto Clientes (Clients object)**: Cada usuário pode ter vários "clientes" representando diferentes canais que usam. Um cliente pode ter um cliente WhatsApp, um cliente SMS e um cliente de bate-papo na web. Cada cliente armazena dados específicos do canal, incluindo números de telefone para usuários do WhatsApp e SMS.
**Metadados da conversa (Conversation metadata)**: São dados contextuais que você passa do seu site ou aplicativo, como URLs de página, IDs de pedido ou campos personalizados. Eles são armazenados no nível da conversa e podem ser acessados ou atualizados durante o bate-papo.
**Participantes (Participants)**: Cada conversa tem participantes, e essa ligação é como você conecta um ID de conversa a um ID de usuário específico.
Para trabalhar com esses dados, você precisará de alguns pré-requisitos: uma licença do Sunshine Conversations (incluída no Zendesk Suite Professional e superior), [chaves de API criadas no Admin Center](https://support.zendesk.com/hc/en-us/articles/4576088682266) e o complemento AI agents Advanced para os recursos do Integration Builder.
## Configurando o acesso à API aos dados do usuário
Antes de poder recuperar qualquer informação do usuário, você precisa configurar a autenticação. O Sunshine Conversations usa um sistema de duas credenciais para acesso à API que você precisará configurar uma vez e referenciar em todas as suas chamadas de API.
Vá para o Admin Center, depois navegue até Apps e integrações, selecione APIs e clique em Conversations API. Se você não vir esta opção, verifique se você está no Suite Professional ou superior e se o Agent Workspace está habilitado. Você encontrará instruções de configuração detalhadas na [documentação da API Conversations](https://support.zendesk.com/hc/en-us/articles/4576088682266).
Clique em "Criar chave de API" e dê a ela um nome descritivo como "Acesso aos Dados do Usuário do Agente de IA". O sistema gerará três informações:
- **ID do aplicativo (App ID)**: Isso identifica sua conta do Zendesk e aparece na maioria dos URLs da API
- **ID da chave (Key ID)**: Isso serve como o nome de usuário para autenticação básica
- **Chave secreta (Secret Key)**: Isso serve como a senha. Copie-a imediatamente, ela aparece apenas uma vez
Para integrações de API no Integration Builder, você usará a autenticação básica com o ID da chave como o nome de usuário e a chave secreta como a senha. O ID do aplicativo é incorporado nos URLs do endpoint da API. Você precisará de todas as três credenciais para cada chamada de API.
Aqui está uma dica rápida: crie chaves de API separadas para ambientes de desenvolvimento e produção. O Integration Builder oferece suporte a vários ambientes, para que você possa configurar diferentes credenciais para teste versus uso ao vivo. Você pode armazenar até 10 chaves, então há espaço para organizá-las por caso de uso. Vale a pena configurar isso cedo para que você não modifique acidentalmente os dados ao vivo durante o teste.
## Recuperando dados do perfil do usuário
Obter dados do usuário requer um processo de API de duas etapas por causa de como o Sunshine Conversations estrutura seu modelo de dados. Primeiro, você precisa encontrar o ID do usuário associado à conversa atual. Em seguida, você usa esse ID de usuário para buscar o perfil completo.
### Passo 1: Liste os participantes para obter o ID do usuário
Cada conversa tem um ID exclusivo que é gerado automaticamente quando o bate-papo começa. Em AI agents Advanced, isso está disponível como um parâmetro do sistema chamado `platformConversationId`. Você usa isso para chamar o endpoint List Participants.
Crie uma [integração de API no Integration Builder](https://support.zendesk.com/hc/en-us/articles/8357756844442) com estas configurações:
- Tipo de método: GET
- URL: `https://YOUR_DOMAIN.zendesk.com/sc/v2/apps/YOUR_APP_ID/conversations/{{platformConversationId}}/participants`
A resposta inclui um array de participantes. Para uma conversa típica com o cliente, você obterá um objeto participante contendo o userId que você precisa. Use esta consulta JSONata para extraí-lo: `data.participants.userId`
### Passo 2: Obtenha os detalhes do usuário da API de Usuário
Agora que você tem o userId, crie uma segunda integração de API para buscar o perfil completo do usuário:
- Tipo de método: GET
- URL: `https://YOUR_DOMAIN.zendesk.com/sc/v2/apps/YOUR_APP_ID/users/{{userId}}`
A resposta contém um objeto de usuário abrangente. Aqui estão os principais campos que você pode extrair com consultas JSONata:
| Campo | Consulta JSONata | Valor de Exemplo |
|------------|----------------------------|--------------------|
| Primeiro nome | `data.user.profile.givenName` | "Sarah" |
| Sobrenome | `data.user.profile.surname` | "Johnson" |
| Email | `data.user.profile.email` | "sarah@example.com" |
| Localidade | `data.user.profile.locale` | "en-US" |
| Status autenticado | `data.user.authenticated` | true/false |
| ID de usuário do Zendesk | `data.user.zendeskId` | "35104420567444" |
### Passo 3: Use os dados em seus fluxos de bot
Armazene esses valores como parâmetros de sessão no Integration Builder e, em seguida, referencie-os em seu diálogo usando chaves duplas como `{{givenName}}`. Você também pode usá-los em lógica condicional, por exemplo, verificando `{{authenticated}}` para mostrar diferentes fluxos para usuários autenticados versus convidados.
Um padrão que funciona bem: crie uma ação de evento "Chat Started" que executa ambas as chamadas de API automaticamente sempre que uma conversa começa. Isso garante que os dados do usuário estejam disponíveis antes que o cliente envie sua primeira mensagem, permitindo saudações personalizadas desde o início.
## Acessando dados específicos do canal (WhatsApp, SMS e mais)
O objeto do usuário fornece informações de perfil, mas e os detalhes específicos do canal, como números de telefone? É aí que entra a API de Clientes (Clients API). Este endpoint revela quais canais um usuário está conectado e fornece identificadores específicos do canal.
### Por que a API de Clientes é importante
Se um cliente entrar em contato com você via WhatsApp, o número de telefone dele não será armazenado no objeto de usuário principal. Em vez disso, ele reside no array de clientes como parte do registro do cliente WhatsApp. Isso é fundamental para casos de uso como:
- Procurar pedidos de clientes pelo número de telefone em seu CRM
- Enviar mensagens SMS de acompanhamento
- Identificar clientes recorrentes em diferentes números de telefone
- Verificar a identidade do usuário por meio da correspondência de telefone
### Recuperando dados do cliente
Crie uma integração de API que chama:
- Tipo de método: GET
- URL: `https://YOUR_DOMAIN.zendesk.com/sc/v2/apps/YOUR_APP_ID/users/{{userId}}/clients`
A resposta inclui um array de objetos de cliente, cada um representando uma conexão de canal diferente. Para usuários do WhatsApp, você verá algo como isto:
```json
{
"type": "whatsapp",
"externalId": "1234567890",
"displayName": "Sarah Johnson",
"raw": {
"from": "+15551234567"
},
"linkedAt": "2024-01-15T10:30:00.000Z"
}
Extraindo o número de telefone do WhatsApp
Use esta consulta JSONata para obter o número de telefone: data.clients[type="whatsapp"].raw.from
Você pode adaptar este padrão para outros canais. Para usuários de SMS, altere o filtro de tipo: data.clients[type="sms"].raw.from
Uma aplicação prática: armazene este número de telefone como um parâmetro de sessão e, em seguida, use-o em uma chamada de API subsequente para seu CRM para procurar o histórico de pedidos do cliente. Quando o agente de IA os cumprimenta pelo nome e diz "Vejo que você tem um pedido da semana passada", a experiência parece genuinamente pessoal.
Passando dados personalizados via metadados da conversa
Às vezes, você precisa passar informações do seu site ou aplicativo para a conversa. Talvez seja o URL da página onde o cliente clicou em ajuda, o ID do pedido do fluxo de checkout ou o nível de assinatura. O Sunshine Conversations lida com isso por meio de metadados.
Passando dados do Widget da Web
Se você estiver usando o Widget da Web do Zendesk, você pode anexar dados personalizados quando a conversa começar:
zE("messenger:set", "conversationFields", [
{ id: "7662882404114", value: "Premium Plan" }
])
Esses dados aparecem nos metadados da conversa com uma chave formatada como zen:ticket_field:7662882404114, onde o número é o ID do seu campo personalizado. O requisito principal: o campo personalizado deve ser editável pelo usuário final no Zendesk.
Recuperando metadados em agentes de IA
No Integration Builder, crie uma Ação usando as ações do CRM com:
- Alvo: Sunshine Conversations
- Tarefa: Obter metadados da conversa
- Recupere o objeto de metadados e extraia chaves específicas
Referencie o nome completo da chave, incluindo o prefixo zen:ticket_field:, ao configurar seu mapeamento de parâmetros. O valor que você passou do widget agora está disponível como um parâmetro de sessão em seu diálogo.
Definindo metadados de agentes de IA
Você também pode atualizar os metadados durante a conversa. Isso é útil quando o agente de IA coleta informações que devem aparecer no ticket do Zendesk quando escalado para um agente humano.
Crie uma Ação com a Tarefa definida como "Atualizar metadados da conversa". Use o mesmo formato de chave (zen:ticket_field:FIELD_ID) e passe seu parâmetro como o valor. Quando a conversa for escalada para o Agent Workspace, esse campo personalizado será pré-preenchido.
Algumas coisas a ter em mente: para campos suspensos, passe o valor da tag em vez do nome de exibição. Para campos de pesquisa, passe o ID do registro relacionado. Campos do sistema como assunto ou status não podem ser atualizados por meio deste método, apenas campos personalizados.
Exemplos práticos de implementação
Vamos colocar isso em prática com alguns cenários do mundo real.
Saudação personalizada com fallback
Configure seu evento "Chat Started" para acionar uma integração de API que busca o primeiro nome do usuário. Armazene-o como {{givenName}}. Em sua mensagem de boas-vindas, escreva: "Olá {{givenName}}, como posso ajudá-lo hoje?"
Mas e se o nome estiver faltando? Adicione uma verificação condicional. Se {{givenName}} estiver vazio, ramifique para uma mensagem que diz "Olá, como posso ajudá-lo hoje?" Isso evita espaços em branco estranhos em suas saudações.
Pesquisa de CRM para histórico de pedidos
Combine a API de Clientes com sua própria API de CRM. Primeiro, obtenha o número do WhatsApp usando data.clients[type="whatsapp"].raw.from. Em seguida, crie uma segunda integração de API que chama o endpoint de pesquisa do seu CRM, passando esse número de telefone como um parâmetro.
Quando o CRM retorna dados de pedidos, extraia detalhes importantes como número e status do pedido recente. Agora seu agente de IA pode dizer "Vejo que você tem o pedido #12345 de ontem. Você está ligando sobre isso?"
Fluxos de usuário autenticados
Use o campo authenticated da API de Usuário para mostrar diferentes experiências. Usuários autenticados podem ter acesso a ações específicas da conta, como "Verificar o status do meu pedido" ou "Atualizar minha assinatura". Usuários convidados veem um menu mais limitado focado em tópicos de ajuda geral.
O status de autenticação é especialmente útil para ações confidenciais à segurança. Antes de processar um reembolso ou alteração de conta, verifique se {{authenticated}} é igual a true e se o nível de verificação de identidade do e-mail atende aos seus requisitos.
Solução de problemas comuns
Mesmo com a configuração correta, as coisas nem sempre funcionam perfeitamente. Aqui estão os problemas mais comuns e como resolvê-los.
ID de usuário não encontrado: Se sua chamada List Participants retornar vazio, verifique se platformConversationId está realmente sendo passado. Verifique seu painel de teste do Integration Builder para ver quais valores estão disponíveis em tempo de execução. A conversa precisa existir antes que você possa listar seus participantes.
Falhas de autenticação da API: Verifique novamente o formato do seu cabeçalho de autenticação básica. Deve ser codificado em Base64 KeyID:Secret. Um erro comum é trocar o ID da chave e o ID do aplicativo ou esquecer de incluir o ID do aplicativo no caminho do URL.
Dados do cliente ausentes: Nem todos os canais preenchem o array de clientes com os mesmos campos. O WhatsApp normalmente inclui números de telefone, mas os clientes de bate-papo na web podem não incluir. Verifique a documentação específica do canal para entender o que está disponível.
Metadados não aparecendo no Agent Workspace: Certifique-se de que seu campo personalizado seja editável pelo usuário final. Verifique também o formato exato do nome da chave, deve ser zen:ticket_field:12345 sem espaços ou variações extras. O ID do campo deve corresponder exatamente.
Parâmetros de sessão vazios: Verifique a ordem das operações em seu diálogo. As integrações de API devem ser executadas antes que você tente usar seus parâmetros de saída. Se você estiver usando parâmetros de uma chamada de API em uma chamada subsequente, verifique se a primeira está sendo concluída com sucesso.
Limitação de taxa: O Sunshine Conversations tem limites de taxa por conta. Se você estiver recebendo erros 429, implemente o backoff exponencial em sua lógica de repetição ou armazene em cache os dados do usuário para reduzir as pesquisas repetidas para a mesma conversa.
Simplificando o acesso aos dados do usuário com eesel AI
Tudo o que abordamos funciona bem se você tiver recursos de desenvolvedor e tempo para criar integrações personalizadas. Mas nem toda equipe tem. Se você precisa de suporte com tecnologia de IA sem a sobrecarga de engenharia, existe um caminho mais simples.
Construímos o eesel AI especificamente para equipes que desejam recursos sofisticados de agentes de IA sem criar integrações de API personalizadas. Em vez de criar fluxos de trabalho do Integration Builder e gerenciar credenciais de API, você conecta o eesel diretamente à sua conta do Zendesk por meio de um fluxo OAuth simples.
Aqui está a diferença na abordagem. Com o método da API do Sunshine Conversations, você está construindo a infraestrutura: criando chaves de API, escrevendo consultas JSONata, lidando com cenários de erro e mantendo a integração ao longo do tempo. Com nossa abordagem, essa infraestrutura já está construída. Você se concentra em configurar o comportamento da IA enquanto nós cuidamos do encanamento de dados.
Quando você conecta o eesel ao Zendesk, acessamos automaticamente perfis de usuário, histórico de tickets e campos personalizados sem exigir que você crie chamadas de API separadas. Você define regras de escalonamento em inglês simples como "Se o cliente mencionar um problema de faturamento, encaminhe-o para a equipe financeira" em vez de construir uma lógica condicional complexa no Integration Builder.
| Caso de Uso | API do Sunshine Conversations | eesel AI |
|---|---|---|
| Tempo de configuração | Dias a semanas | Minutos |
| Requisitos técnicos | Recursos de desenvolvedor | Nenhum |
| Integrações de canal personalizadas | Flexibilidade total | Canais padrão |
| Orquestração de API de várias etapas | Controle total | Pré-construído |
| Sobrecarga de manutenção | Contínua | Mínima |
Se você estiver construindo soluções altamente personalizadas com requisitos de canal exclusivos ou orquestração complexa de vários sistemas, a abordagem da API do Sunshine Conversations oferece a flexibilidade de que você precisa. Mas se seu objetivo é implantar suporte ao cliente com tecnologia de IA rapidamente, sem recursos de engenharia, nossa integração com o Zendesk lida com a complexidade para você.
Comece a construir experiências de agentes de IA personalizadas
Agora você tem o quadro completo para acessar os dados do usuário no Zendesk Sunshine Conversations. A arquitetura envolve três fontes de dados principais: a API de Usuário para informações de perfil, a API de Clientes para detalhes específicos do canal, como números de telefone, e os metadados da conversa para contexto personalizado de seus aplicativos.
O padrão de implementação é consistente em todos os casos de uso: crie integrações de API no Integration Builder, use JSONata para extrair os campos que você precisa, armazene-os como parâmetros de sessão e referencie esses parâmetros em seus fluxos de diálogo. Com o processo de duas etapas de obter os participantes primeiro e, em seguida, os detalhes do usuário, você pode acessar tudo, desde nomes básicos até números de telefone do WhatsApp.
Antes de começar a construir, audite quais dados do usuário você realmente precisa. É fácil se deixar levar coletando todos os campos disponíveis, mas concentre-se nos dados que realmente melhoram a experiência do cliente. Uma saudação personalizada usando o primeiro nome do cliente tem mais impacto do que exibir seu ID de usuário interno.
Se você está pronto para implementar, mas preocupado com o esforço de desenvolvimento, experimente nossa plataforma junto com sua configuração do Zendesk. Você pode comparar abordagens e escolher o que funciona melhor para as capacidades e o cronograma de sua equipe.
Compartilhe esta postagem
Article by
