Início Rápido

Visão Geral do Widget

O aplicativo widget está hospedado em widget.companin.tech e fornece uma maneira fácil de incorporar um Agente de Suporte ao Cliente AI em seu site. Para começar, você precisará criar um agente e um aplicativo OAuth.

O widget é um aplicativo leve e autônomo que roda em um iframe isolado em seu site. Essa arquitetura garante que o widget não conflite com seu CSS ou JavaScript existentes, enquanto mantém excelente desempenho e segurança.

1. Crie um Agente

Primeiro, crie um Agente de Suporte ao Cliente AI em seu painel:

Seu agente é o cérebro de IA por trás do widget. Ele processa mensagens de usuários, mantém o contexto da conversa e gera respostas inteligentes. Cada agente pode ser personalizado com instruções específicas, traços de personalidade e bases de conhecimento para corresponder ao seu caso de uso.

1. Vá para o seu painel e navegue até a página "Fontes de Dados"
2. Clique no botão "Adicionar" na seção Agentes
3. Preencha os detalhes do agente (nome, descrição, tom, etc.)
4. Salve o agente e anote seu ID

Dica: Dê ao seu agente instruções claras e específicas sobre seu papel e limitações. Por exemplo: "Você é um agente de suporte ao cliente útil para um produto SaaS. Você pode responder perguntas sobre recursos, preços e gerenciamento de contas. Para problemas técnicos, direcione os usuários a criar um ticket de suporte."

2. Crie um Aplicativo OAuth

Crie um aplicativo OAuth para autenticar seu widget:

1. Vá para a página "OAuth" em seu painel
2. Clique em "Criar Aplicativo"
3. Preencha o nome e a descrição do aplicativo
4. Copie o client_id do aplicativo criado

3. Incorpore o Widget via Iframe

A maneira mais simples de integrar o widget é incorporá-lo diretamente usando um iframe. Este método não requer inicialização em JavaScript e funciona imediatamente. Para múltiplos iframes em uma página, mantenha cada incorporação restrita ao seu próprio contêiner e parâmetros.

<iframe src="https://widget.companin.tech/embed/session?key=YOUR_WIDGET_KEY&locale=en" style="border:none; width:100%; height:600px; border-radius:8px;" title="Customer Support AI Agent Widget"></iframe>

Substitua YOUR_WIDGET_KEY pela chave de instalação do seu widget (o valor wgt_… — copie-o da página de Widget ou Instalação no painel de controle). O parâmetro locale pode ser configurado para corresponder ao idioma do seu site.

Avançado: Inicialização em JavaScript

O método de integração recomendado é usar nosso carregador de widget JavaScript, que fornece dimensionamento automático, gerenciamento de configuração e comportamento responsivo.

Integração de Script

Adicione a seguinte tag de script à sua página HTML:

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

Atributos do Script

Cada atributo serve a um propósito específico na configuração do seu widget:

• data-widget-key: O ID do Widget do seu widget - O único valor que a maioria das instalações precisa. Ele resolve seu cliente, agente e servidor de configuração no lado do servidor, para que você não os cole separadamente.

Os três atributos abaixo são uma alternativa avançada para data-widget-key - use-os para configurações de múltiplas instâncias onde você precisa direcionar explicitamente um cliente, agente ou configuração específica:

• data-client-id: Seu ID de cliente OAuth - Isso autentica seu aplicativo com nossa API. Pense nisso como a senha do seu aplicativo.
• data-agent-id: O UUID do seu agente - Isso identifica qual Agente de IA de Suporte ao Cliente lida com as conversas.
• data-config-id: O UUID da sua configuração de widget - Isso determina como seu widget se parece e se comporta (cores, tamanho, posição, etc.).
• data-instance-id: ID de instância única por widget - Necessário ao incorporar múltiplos widgets na mesma página para evitar colisões e permitir direcionamento de API por instância.
• data-custom-css: Obsoleto. Definir este atributo registra um aviso no console e não tem efeito. Defina custom_css na configuração do seu widget no painel em vez disso — ele é carregado da configuração e injetado no iframe automaticamente.
• data-locale: Código de idioma (por exemplo, "en", "es", "fr") - Define o idioma de exibição do widget. O agente ainda responderá em qualquer idioma que os usuários escreverem.
• data-dev: Defina como "true" para modo de desenvolvimento (localhost) - Use isso ao testar localmente. Remova ou defina como "false" para produção.

O widget automaticamente:

• Busca a configuração do ID de configuração
• Dimensiona-se de acordo com as dimensões do widget na configuração
• Posiciona o botão colapsado com base nas configurações de configuração
• Começa aberto ou fechado com base na configuração start_open

Notas

• O widget gerencia automaticamente seu próprio dimensionamento com base nas configurações de configuração
• A posição do botão colapsado pode ser personalizada através da configuração do widget
• O widget respeita a configuração start_open da sua configuração
• Todo o estilo (cores, fontes, dimensões) é controlado através da configuração do widget
• O widget usa comunicação postMessage para comportamento responsivo
• O modo de desenvolvimento pode ser ativado com data-dev="true" para testes em localhost
• Para troca de token do lado do servidor, use /api/v1/auth/widget-token e mantenha o segredo do cliente apenas no seu servidor.
• Certifique-se de que sua origem host (por exemplo, http://localhost:3000) está incluída nas allowed_origins do OAuth ao incorporar o widget em um iframe.