Solução de problemas

Problemas comuns e soluções para integração e uso de widgets.

Encontrando problemas? Você está no lugar certo. Este guia cobre os problemas mais comuns que os desenvolvedores encontram ao integrar o widget, juntamente com soluções passo a passo. A maioria dos problemas pode ser resolvida em apenas alguns minutos.

50d Dica R—pida de Depura—o

Abra o Console do Desenvolvedor do seu navegador (F12) antes de solucionar problemas. A maioria dos erros do widget exibirá mensagens claras no console que apontam diretamente para o problema.

Se o widget não aparecer de forma alguma em sua página, siga estas etapas de solução de problemas na ordem:

❌ Problema: O script do widget falha ao carregar

Erro: "Widget não configurado" (com detalhes sobre cada atributo data-* ausente)

Verifique o console do navegador para esta mensagem de erro.

✅ Solução: Verifique os atributos obrigatórios

Certifique-se de que todos os atributos de dados obrigatórios estejam presentes na tag do script:

<script src="https://widget.companin.tech/widget.js" data-widget-key="YOUR_WIDGET_KEY" data-locale="en"></script>

❌ Problema: Falha na autenticação

Erro: "Autenticação necessária" ou "Credenciais inválidas"

O widget falha ao autenticar com a API. Isso geralmente acontece quando as credenciais estão incorretas ou expiradas.

✅ Solução: Verifique a configuração do OAuth

Problemas de autenticação geralmente são simples de corrigir. Trabalhe através dessas verificações:

Verifique se client_id está correto em seu aplicativo OAuth - Copie-o diretamente do seu painel para evitar erros de digitação
Certifique-se de que o aplicativo OAuth esteja ativo e não desativado em seu painel
Verifique se o aplicativo OAuth tem URIs de redirecionamento adequados configurados - O domínio do widget deve ser permitido
Verifique se o domínio do widget é permitido nas configurações de CORS em seu backend
Se você recentemente regenerou credenciais, certifique-se de que está usando os novos valores

Ainda preso? Tente criar um novo aplicativo OAuth em seu painel. Às vezes, começar do zero resolve problemas de configuração obscuros.

❌ Problema: /api/v1/auth/widget-token retorna 400 (Origem não permitida)

Erro: "Origem não permitida" ou solicitação de token do widget rejeitada

Comum ao incorporar em um iframe e o domínio host não está listado nas origens permitidas do OAuth.

✅ Solução: Alinhar origem host e lista de permissões do OAuth

Adicione a origem da sua página de incorporação (por exemplo, http://localhost:3000) às allowed_origins do OAuth.
Use o formato completo de esquema + host (+ porta), sem caminho final.
Ao incorporar em um iframe, certifique-se de que as chamadas de token carreguem a origem da página host em X-Embed-Origin.
Verifique se a URL da solicitação é /api/v1/auth/widget-token (não caminhos legados).

Dica de validação: Verifique a aba de rede do navegador para os cabeçalhos da solicitação de token e compare X-Embed-Origin com sua entrada allowed_origins do OAuth.

❌ Problema: O widget aparece colapsado, mas o botão está invisível

Problema de posicionamento do botão

O widget carrega, mas o botão está fora da área visível.

✅ Solução: Verifique a configuração de posicionamento

Verifique a configuração de posição do widget
Verifique se há conflitos de CSS com position: fixed
Certifique-se de que os contêineres pai não tenham overflow: hidden

❌ Problema: Widget oculto em dispositivos móveis

✅ Solução: Ajuste as configurações móveis

Se hide_on_mobile estiver ativado na configuração, o widget ficará oculto em dispositivos móveis. Desative esta configuração ou ajuste o ponto de interrupção móvel.

Problemas de Estilo

Problemas visuais são comuns e geralmente fáceis de corrigir. O widget foi projetado para ser visualmente isolado de sua página, mas às vezes podem ocorrer conflitos.

❌ Problema: Cores não aplicadas

✅ Solução: Limpar cache e verificar configuração

Siga estas etapas para diagnosticar problemas de cor:

Limpe o cache do navegador e recarregue a página (Ctrl+Shift+R ou Cmd+Shift+R para recarga forçada)
Verifique se os valores de cor são códigos hexadecimais válidos (devem começar com # e ter 6 caracteres, por exemplo, #FF5733)
Verifique se a configuração foi salva no painel - Procure uma confirmação de "salvo"
Certifique-se de que você está editando a configuração correta - Verifique se o ID da configuração corresponde à sua tag de script
Aguarde alguns segundos após salvar - As alterações na configuração podem levar de 5 a 10 segundos para se propagar

Dica de depuração: Abra o widget em seu navegador e use a ferramenta de inspecionar elemento para verificar quais valores de CSS estão realmente sendo aplicados. Isso mostrará se suas cores estão carregando ou sendo substituídas.

❌ Problema: Fontes não carregando

✅ Solução: Configuração de fonte

Certifique-se de que a família da fonte esteja definida como "system-ui" ou uma fonte segura para a web
Fontes personalizadas podem não carregar devido a restrições de CORS
Verifique se os valores de peso da fonte são suportados

Problemas de Funcionalidade

Quando o widget carrega corretamente, mas os recursos não funcionam como esperado, essas soluções ajudarão.

❌ Problema: Mensagens não enviadas

Erro de rede, tempo limite ou sessão expirada

O usuário digita uma mensagem e clica em enviar, mas nada acontece ou um erro aparece. Verifique a aba de rede do navegador para solicitações falhadas (deve aparecer em vermelho na aba de rede).

✅ Solução: Verifique a sessão e a rede

Problemas de envio de mensagens geralmente estão relacionados à conectividade de rede ou sessões expiradas. Diagnostique sistematicamente:

Verifique se os endpoints da API são acessíveis - Tente acessar a URL da API diretamente em seu navegador
Verifique se o token de autenticação é válido - Procure por erros 401/403 na aba de rede
Certifique-se de que a sessão não expirou - As sessões geralmente duram 30 minutos de inatividade
Verifique se há problemas de conectividade de rede - Sua conexão com a internet está estável?
Procure por erros de CORS no console - Isso indica que seu domínio pode não estar na lista branca
Verifique se o software de firewall/segurança não está bloqueando a API - Redes corporativas às vezes bloqueiam APIs externas

Teste rápido: Se as mensagens funcionam em uma janela anônima, mas não em seu navegador normal, o problema provavelmente está relacionado a extensões do navegador ou dados de autenticação em cache.

❌ Problema: Fluxos de conversa não funcionando

✅ Solução: Valide a configuração do fluxo

Verifique se as palavras-chave de gatilho correspondem exatamente
Verifique se as respostas do fluxo estão corretamente configuradas
Certifique-se de que as ações do botão sejam válidas

Problemas de Desempenho

❌ Problema: Widget carrega lentamente

✅ Solução: Otimizar o carregamento

Use a versão de produção em vez da de desenvolvimento
Ative o cache do navegador para ativos estáticos
Minimize CSS e imagens personalizados
Considere o carregamento lento se não for crítico

❌ Problema: Alto uso de memória

✅ Solução: Reduzir o uso de recursos

Limite o comprimento do histórico de mensagens
Otimize imagens e mídias
Desative recursos não utilizados

Compatibilidade com Navegadores

❌ Problema: Widget não funcionando em navegadores mais antigos

✅ Solução: Verifique o suporte do navegador

O widget requer recursos modernos do navegador:

Suporte a JavaScript ES6+
API PostMessage
CSS Grid e Flexbox
Capacidades modernas de iframe

Navegadores mínimos suportados: Chrome 60+, Firefox 55+, Safari 12+, Edge 79+

Obtendo Ajuda

Quando você precisa de assistência adicional além deste guia, essas ferramentas e recursos ajudarão você a diagnosticar problemas ou obter suporte.

Modo de Depuração

Ative o modo de depuração para ver logs detalhados no console do seu navegador. Isso fornece insights sobre o que o widget está fazendo em cada etapa:

<script  src="https://widget.companin.tech/widget.js"  data-widget-key="YOUR_WIDGET_KEY"  data-dev="true"></script>

Ferramentas de Desenvolvedor do Navegador

Verifique a aba Console para erros de JavaScript
Verifique a aba Rede para solicitações falhadas
Verifique a aba Aplicativo para problemas de armazenamento local
Use a aba Elementos para inspecionar o DOM do widget

Etapas Comuns de Depuração

Limpe o cache e os cookies do navegador
Tente no modo de navegação anônima/privada
Teste com navegadores diferentes
Verifique a conectividade de rede
Verifique todos os valores de configuração

Ainda tendo problemas?

Verifique nosso guia de configuração ou entre em contato com o suporte com os logs do console do seu navegador e detalhes da configuração.

Voltar

Solução de problemas

Problemas comuns e soluções para integração e uso de widgets.

50d Dica R—pida de Depura—o

Abra o Console do Desenvolvedor do seu navegador (F12) antes de solucionar problemas. A maioria dos erros do widget exibirá mensagens claras no console que apontam diretamente para o problema.

Se o widget não aparecer de forma alguma em sua página, siga estas etapas de solução de problemas na ordem:

❌ Problema: O script do widget falha ao carregar

Erro: "Widget não configurado" (com detalhes sobre cada atributo data-* ausente)

Verifique o console do navegador para esta mensagem de erro.

✅ Solução: Verifique os atributos obrigatórios

Certifique-se de que todos os atributos de dados obrigatórios estejam presentes na tag do script:

<script src="https://widget.companin.tech/widget.js" data-widget-key="YOUR_WIDGET_KEY" data-locale="en"></script>

❌ Problema: Falha na autenticação

Erro: "Autenticação necessária" ou "Credenciais inválidas"

O widget falha ao autenticar com a API. Isso geralmente acontece quando as credenciais estão incorretas ou expiradas.

✅ Solução: Verifique a configuração do OAuth

Problemas de autenticação geralmente são simples de corrigir. Trabalhe através dessas verificações:

Verifique se client_id está correto em seu aplicativo OAuth - Copie-o diretamente do seu painel para evitar erros de digitação
Certifique-se de que o aplicativo OAuth esteja ativo e não desativado em seu painel
Verifique se o aplicativo OAuth tem URIs de redirecionamento adequados configurados - O domínio do widget deve ser permitido
Verifique se o domínio do widget é permitido nas configurações de CORS em seu backend
Se você recentemente regenerou credenciais, certifique-se de que está usando os novos valores

Ainda preso? Tente criar um novo aplicativo OAuth em seu painel. Às vezes, começar do zero resolve problemas de configuração obscuros.

❌ Problema: /api/v1/auth/widget-token retorna 400 (Origem não permitida)

Erro: "Origem não permitida" ou solicitação de token do widget rejeitada

Comum ao incorporar em um iframe e o domínio host não está listado nas origens permitidas do OAuth.

✅ Solução: Alinhar origem host e lista de permissões do OAuth

Adicione a origem da sua página de incorporação (por exemplo, http://localhost:3000) às allowed_origins do OAuth.
Use o formato completo de esquema + host (+ porta), sem caminho final.
Ao incorporar em um iframe, certifique-se de que as chamadas de token carreguem a origem da página host em X-Embed-Origin.
Verifique se a URL da solicitação é /api/v1/auth/widget-token (não caminhos legados).

Dica de validação: Verifique a aba de rede do navegador para os cabeçalhos da solicitação de token e compare X-Embed-Origin com sua entrada allowed_origins do OAuth.

❌ Problema: O widget aparece colapsado, mas o botão está invisível

Problema de posicionamento do botão

O widget carrega, mas o botão está fora da área visível.

✅ Solução: Verifique a configuração de posicionamento

Verifique a configuração de posição do widget
Verifique se há conflitos de CSS com position: fixed
Certifique-se de que os contêineres pai não tenham overflow: hidden

❌ Problema: Widget oculto em dispositivos móveis

✅ Solução: Ajuste as configurações móveis

Se hide_on_mobile estiver ativado na configuração, o widget ficará oculto em dispositivos móveis. Desative esta configuração ou ajuste o ponto de interrupção móvel.

Problemas de Estilo

Problemas visuais são comuns e geralmente fáceis de corrigir. O widget foi projetado para ser visualmente isolado de sua página, mas às vezes podem ocorrer conflitos.

❌ Problema: Cores não aplicadas

✅ Solução: Limpar cache e verificar configuração

Siga estas etapas para diagnosticar problemas de cor:

Limpe o cache do navegador e recarregue a página (Ctrl+Shift+R ou Cmd+Shift+R para recarga forçada)
Verifique se os valores de cor são códigos hexadecimais válidos (devem começar com # e ter 6 caracteres, por exemplo, #FF5733)
Verifique se a configuração foi salva no painel - Procure uma confirmação de "salvo"
Certifique-se de que você está editando a configuração correta - Verifique se o ID da configuração corresponde à sua tag de script
Aguarde alguns segundos após salvar - As alterações na configuração podem levar de 5 a 10 segundos para se propagar

❌ Problema: Fontes não carregando

✅ Solução: Configuração de fonte

Certifique-se de que a família da fonte esteja definida como "system-ui" ou uma fonte segura para a web
Fontes personalizadas podem não carregar devido a restrições de CORS
Verifique se os valores de peso da fonte são suportados

Problemas de Funcionalidade

Quando o widget carrega corretamente, mas os recursos não funcionam como esperado, essas soluções ajudarão.

❌ Problema: Mensagens não enviadas

Erro de rede, tempo limite ou sessão expirada

O usuário digita uma mensagem e clica em enviar, mas nada acontece ou um erro aparece. Verifique a aba de rede do navegador para solicitações falhadas (deve aparecer em vermelho na aba de rede).

✅ Solução: Verifique a sessão e a rede

Problemas de envio de mensagens geralmente estão relacionados à conectividade de rede ou sessões expiradas. Diagnostique sistematicamente:

Verifique se os endpoints da API são acessíveis - Tente acessar a URL da API diretamente em seu navegador
Verifique se o token de autenticação é válido - Procure por erros 401/403 na aba de rede
Certifique-se de que a sessão não expirou - As sessões geralmente duram 30 minutos de inatividade
Verifique se há problemas de conectividade de rede - Sua conexão com a internet está estável?
Procure por erros de CORS no console - Isso indica que seu domínio pode não estar na lista branca
Verifique se o software de firewall/segurança não está bloqueando a API - Redes corporativas às vezes bloqueiam APIs externas

❌ Problema: Fluxos de conversa não funcionando

✅ Solução: Valide a configuração do fluxo

Verifique se as palavras-chave de gatilho correspondem exatamente
Verifique se as respostas do fluxo estão corretamente configuradas
Certifique-se de que as ações do botão sejam válidas

Problemas de Desempenho

❌ Problema: Widget carrega lentamente

✅ Solução: Otimizar o carregamento

Use a versão de produção em vez da de desenvolvimento
Ative o cache do navegador para ativos estáticos
Minimize CSS e imagens personalizados
Considere o carregamento lento se não for crítico

❌ Problema: Alto uso de memória

✅ Solução: Reduzir o uso de recursos

Limite o comprimento do histórico de mensagens
Otimize imagens e mídias
Desative recursos não utilizados

Compatibilidade com Navegadores

❌ Problema: Widget não funcionando em navegadores mais antigos

✅ Solução: Verifique o suporte do navegador

O widget requer recursos modernos do navegador:

Suporte a JavaScript ES6+
API PostMessage
CSS Grid e Flexbox
Capacidades modernas de iframe

Navegadores mínimos suportados: Chrome 60+, Firefox 55+, Safari 12+, Edge 79+

Obtendo Ajuda

Quando você precisa de assistência adicional além deste guia, essas ferramentas e recursos ajudarão você a diagnosticar problemas ou obter suporte.

Modo de Depuração

Ative o modo de depuração para ver logs detalhados no console do seu navegador. Isso fornece insights sobre o que o widget está fazendo em cada etapa:

<script  src="https://widget.companin.tech/widget.js"  data-widget-key="YOUR_WIDGET_KEY"  data-dev="true"></script>

Ferramentas de Desenvolvedor do Navegador

Verifique a aba Console para erros de JavaScript
Verifique a aba Rede para solicitações falhadas
Verifique a aba Aplicativo para problemas de armazenamento local
Use a aba Elementos para inspecionar o DOM do widget

Etapas Comuns de Depuração

Limpe o cache e os cookies do navegador
Tente no modo de navegação anônima/privada
Teste com navegadores diferentes
Verifique a conectividade de rede
Verifique todos os valores de configuração

Ainda tendo problemas?

Verifique nosso guia de configuração ou entre em contato com o suporte com os logs do console do seu navegador e detalhes da configuração.

Voltar

Solução de problemas

Widget Não Carregando

❌ Problema: O script do widget falha ao carregar

✅ Solução: Verifique os atributos obrigatórios

❌ Problema: Falha na autenticação

✅ Solução: Verifique a configuração do OAuth

❌ Problema: /api/v1/auth/widget-token retorna 400 (Origem não permitida)

✅ Solução: Alinhar origem host e lista de permissões do OAuth

Widget Não Visível

❌ Problema: O widget aparece colapsado, mas o botão está invisível

✅ Solução: Verifique a configuração de posicionamento

❌ Problema: Widget oculto em dispositivos móveis

✅ Solução: Ajuste as configurações móveis

Problemas de Estilo

❌ Problema: Cores não aplicadas

✅ Solução: Limpar cache e verificar configuração

❌ Problema: Fontes não carregando

✅ Solução: Configuração de fonte

Problemas de Funcionalidade

❌ Problema: Mensagens não enviadas

✅ Solução: Verifique a sessão e a rede

❌ Problema: Fluxos de conversa não funcionando

✅ Solução: Valide a configuração do fluxo

Problemas de Desempenho

❌ Problema: Widget carrega lentamente

✅ Solução: Otimizar o carregamento

❌ Problema: Alto uso de memória

✅ Solução: Reduzir o uso de recursos

Compatibilidade com Navegadores

❌ Problema: Widget não funcionando em navegadores mais antigos

✅ Solução: Verifique o suporte do navegador

Obtendo Ajuda

Modo de Depuração

Ferramentas de Desenvolvedor do Navegador

Etapas Comuns de Depuração

Solução de problemas

Widget Não Carregando

❌ Problema: O script do widget falha ao carregar

✅ Solução: Verifique os atributos obrigatórios

❌ Problema: Falha na autenticação

✅ Solução: Verifique a configuração do OAuth

❌ Problema: /api/v1/auth/widget-token retorna 400 (Origem não permitida)

✅ Solução: Alinhar origem host e lista de permissões do OAuth

Widget Não Visível

❌ Problema: O widget aparece colapsado, mas o botão está invisível

✅ Solução: Verifique a configuração de posicionamento

❌ Problema: Widget oculto em dispositivos móveis

✅ Solução: Ajuste as configurações móveis

Problemas de Estilo

❌ Problema: Cores não aplicadas

✅ Solução: Limpar cache e verificar configuração

❌ Problema: Fontes não carregando

✅ Solução: Configuração de fonte

Problemas de Funcionalidade

❌ Problema: Mensagens não enviadas

✅ Solução: Verifique a sessão e a rede

❌ Problema: Fluxos de conversa não funcionando

✅ Solução: Valide a configuração do fluxo

Problemas de Desempenho

❌ Problema: Widget carrega lentamente

✅ Solução: Otimizar o carregamento

❌ Problema: Alto uso de memória

✅ Solução: Reduzir o uso de recursos

Compatibilidade com Navegadores

❌ Problema: Widget não funcionando em navegadores mais antigos

✅ Solução: Verifique o suporte do navegador

Obtendo Ajuda

Modo de Depuração

Ferramentas de Desenvolvedor do Navegador

Etapas Comuns de Depuração