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.

🔍 Dica de Depuração Rápida

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 na 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 necessários

Certifique-se de que todos os atributos de dados necessários estão presentes na tag de script:

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

❌ Problema: Autenticação falhou

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 diretos de corrigir. Trabalhe através dessas verificações:

Verifique se client_id está correto em seu aplicativo OAuth - Copie diretamente do seu painel para evitar erros de digitação
Certifique-se de que o aplicativo OAuth está 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 no 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: Alinhe a origem host e a 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 de esquema completo + 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 será 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 é projetado para ser visualmente isolado da 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
Espere 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 sobrescritas.

❌ Problema: Fontes não carregando

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

Certifique-se de que a família da fonte está 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 (devem 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 normalmente duram 30 minutos de inatividade
Verifique se há problemas de conectividade de rede - Sua conexão com a internet é estável?
Procure por erros de CORS no console - Isso indica que seu domínio pode não estar na lista de permissões
Verifique se o firewall/software de 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 no 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 configuradas corretamente
Certifique-se de que as ações dos botões são válidas

Problemas de desempenho

❌ Problema: Widget carrega lentamente

✅ Solução: Otimize 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 preguiçoso se não for crítico

❌ Problema: Alto uso de memória

✅ Solução: Reduza o uso de recursos

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

Compatibilidade do navegador

❌ 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ê precisar 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

Passos comuns de depuração

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

Ainda está 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 de configuração.

Voltar

Solução de Problemas

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

🔍 Dica de Depuração Rápida

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 na 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 necessários

Certifique-se de que todos os atributos de dados necessários estão presentes na tag de script:

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

❌ Problema: Autenticação falhou

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 diretos de corrigir. Trabalhe através dessas verificações:

Verifique se client_id está correto em seu aplicativo OAuth - Copie diretamente do seu painel para evitar erros de digitação
Certifique-se de que o aplicativo OAuth está 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 no 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: Alinhe a origem host e a 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 de esquema completo + 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 será 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 é projetado para ser visualmente isolado da 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
Espere 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 está 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 (devem 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 normalmente duram 30 minutos de inatividade
Verifique se há problemas de conectividade de rede - Sua conexão com a internet é estável?
Procure por erros de CORS no console - Isso indica que seu domínio pode não estar na lista de permissões
Verifique se o firewall/software de 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 configuradas corretamente
Certifique-se de que as ações dos botões são válidas

Problemas de desempenho

❌ Problema: Widget carrega lentamente

✅ Solução: Otimize 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 preguiçoso se não for crítico

❌ Problema: Alto uso de memória

✅ Solução: Reduza o uso de recursos

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

Compatibilidade do navegador

❌ 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ê precisar 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

Passos comuns de depuração

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

Ainda está 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 de configuração.

Voltar

Solução de Problemas

Widget Não Carregando

❌ Problema: O script do widget falha ao carregar

✅ Solução: Verifique os atributos necessários

❌ Problema: Autenticação falhou

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

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

✅ Solução: Alinhe a origem host e a 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: Otimize o carregamento

❌ Problema: Alto uso de memória

✅ Solução: Reduza o uso de recursos

Compatibilidade do navegador

❌ 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

Passos 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 necessários

❌ Problema: Autenticação falhou

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

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

✅ Solução: Alinhe a origem host e a 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: Otimize o carregamento

❌ Problema: Alto uso de memória

✅ Solução: Reduza o uso de recursos

Compatibilidade do navegador

❌ 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

Passos comuns de depuração