Como instalar o Widget do Cloud Chat no seu site e passar dados do contato automaticamente
Novo: Para configurar o Widget para dar suporte à multiplas conversas para um mesmo contato, siga a seguinte FAQ.
Você pode instalar o widget do Cloud Chat de forma simples em qualquer página Web. Basta seguir as instruções nesse
artigo para fazer as configurações necessárias.
Além da simples configuração do Widget, opcionalmente, também vamos ensinar a como passar informações de contato
automaticamente via código, sem que o usuário precise digitá-las.
Observação: Essa parte não é necessário para o funcionamento do Widget. Mas pode ser muito útil se o Widget for
apresentado em uma área logada do seu site.
Você pode passar:
- 📧 E-mail
- 📞 Telefone
- 🧑 Nome
- 🧩 Campos personalizados do contato (ex: CPF, status de plano, ID interno)
O campo personalizado de contato deve ser criado previamente. Informações sobre a manutenção de campos personalizados
podem ser encontradas aqui.
✅ Quando usar a passagem de informações de contato automaticamente?
- Em áreas logadas onde já se conhece o usuário
- Em páginas protegidas (ex: portal do cliente, dashboard interno)
- Para iniciar a conversa com mais contexto e evitar fricção
🛠️ Como instalar o Web widget no site
1. Copie o script base
Esse script precisa ser colado no HTML da sua página, logo antes do fechamento da tag :
<script>
(function(d,t) {
var BASE_URL="https://BASE_URL_CLOUDCHAT_AQUI";
var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=BASE_URL + "/packs/js/sdk.js";
g.defer = true;
g.async = true;
s.parentNode.insertBefore(g,s);
g.onload=function(){
window.cloudchatSDK.run({
websiteToken: "SEU_TOKEN_AQUI",
baseUrl: BASE_URL
});
}
})(document,"script");
</script>
Você encontra o websiteToken no painel de configuração da sua Inbox → Configurações → Código de incorporação.
BASE_URL = Url base do cloudchat, exemplo: "https://cloudchat.cloudhumans.com"
👤 Como passar dados do contato automaticamente
Você pode utilizar os eventos cloudchat:ready e cloudchat:on-start-conversation para preencher as informações do contato
e seus atributos.
Exemplo completo:
<script>
(function(d,t) {
var BASE_URL="https://BASE_URL_CLOUDCHAT_AQUI";
var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=BASE_URL+"/packs/js/sdk.js";
g.defer = true;
g.async = true;
s.parentNode.insertBefore(g,s);
g.onload=function(){
window.cloudchatSDK.run({
websiteToken: 'SEU_TOKEN_AQUI',
baseUrl: BASE_URL
});
// 1. Preenchendo informações do contato
window.addEventListener('cloudchat:ready', function() {
window.$cloudchat.setUser('[email protected]', {
email: '[email protected]',
name: 'João da Silva',
phone_number: '+5511999999999'
});
});
// 2. Passando atributos personalizados do contato
window.addEventListener('cloudchat:on-start-conversation', function() {
window.$cloudchat.setCustomAttributes({
plano: 'Premium',
id_cliente: '123456',
cnh: 'ABC123456789'
});
});
}
})(document,"script");
</script>
🌐 Validação de Domínio
Você pode configurar os domínios onde o widget de chat poderá funcionar. Isso é útil para evitar que seu widget seja
utilizado fora dos domínios autorizados, como por exemplo em ambientes de staging ou por terceiros não autorizados.
Como configurar?
No painel de configuração da sua Inbox → Configurações → Configuração, você verá a seção Validação de Domínio, como no
exemplo abaixo:
No campo de configuração:
- Deixe em branco para permitir todos os domínios
- Adicione domínios completos (ex: example.com)
- Ou subdomínios com curinga (ex: *.example.com)
Exemplo prático:
- Campo vazio → sem restrições; o widget funcionará em qualquer domínio
- example.com → permite uso apenas nesse domínio
- *.example.com → permite uso em todos os subdomínios de example.com, como app.example.com, login.example.com
⚠️ AVISO IMPORTANTE
🚨 Os scripts apresentados nesta FAQ são apenas exemplos.
Eles não devem ser usados exatamente como estão em produção sem as devidas adaptações.
🔑 Sobre o identificador do contato (identifier / hash)
O identifier (ou campo identificador) NUNCA deve ser estático.
- Cada contato precisa ter um identificador único
- Esse identificador representa a ID do usuário no seu sistema
- É ele que o Cloud Chat usa para correlacionar corretamente o contato
❌ O que acontece se você usar um identifier fixo?
Se o mesmo identifier for reutilizado para múltiplos usuários:
- O Cloud Chat irá mergear todos os usuários em um único contato, consequentemente, merge de tickets
🔍 Perguntas frequentes
O que acontece se já existir uma informação anterior do contato?
A nova informação enviada via script sobrescreve os dados antigos. O dado mais recente sempre prevalece.
E se eu errar o nome de algum campo personalizado?
Nenhum erro será lançado. O campo incorreto será ignorado silenciosamente. Apenas os campos existentes serão
atualizados.
Quais dados são obrigatórios?
Você precisa passar pelo menos o e-mail ou o telefone, pois são os identificadores únicos usados para fazer match com o
contato.
Posso passar atributos da conversa também?
Não por enquanto. A passagem de atributos personalizados da conversa não foi lançada na versão atual (v0) por limitações
técnicas. Caso precise disso, recomendamos usar o formulário no início da conversa.
Que tipos de formatações ele aceita?
O Widget do Cloud Chat aceita a maioria dos formatos do markdown. Alguns exemplos:
- Negrito / Taxado / Itálico
- Bloco de código
- Links
- Imagens
- Bullet points
Imagem de exemplo:
🧪 Como testar?
Você pode testar localmente ou em staging. Para validar:
1. Abra a página com o widget instalado
2. Verifique se o nome, e-mail, telefone e campos personalizados já aparecem preenchidos na conversa
3. Consulte no painel da Cloud Humans se os dados foram atribuídos ao contato corretamente
