Ainda estamos construindo coisas aqui! Ajude-nos a melhorar relatando bugs aqui.
Entrar

Guia Rápido

Incorpore o widget e obtenha um token de widget do servidor.

Visão Geral do Widget

O aplicativo widget está hospedado em widget.companin.tech e fornece uma maneira fácil de incorporar um assistente de IA em seu site. Para começar, você precisará criar um assistente e um aplicativo OAuth.

O widget é um aplicativo leve e independente executado em um iframe isolado no seu site. Essa arquitetura garante que o widget não entre em conflito com seu CSS ou JavaScript existente, ao mesmo tempo que mantém excelente desempenho e segurança.

⚡ Implantação rápida

A maioria dos desenvolvedores tem o widget em execução em seus sites em 10 minutos. O processo de configuração envolve apenas três etapas: criação de credenciais, configuração da aparência e adição de uma única tag de script ao seu HTML.

1. Criar um Assistente

Primeiro, crie um assistente de IA em seu painel de controle:

Seu assistente é o cérebro de IA por trás do widget. Ele processa mensagens do usuário, mantém o contexto da conversa e gera respostas inteligentes. Cada assistente 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á ao seu painel de controle e navegue para a página "Data Sources"
  2. Clique no botão "Add" na seção Assistants
  3. Preencha os detalhes do assistente (nome, descrição, tom, etc.)
  4. Salve o assistente e anote o ID

Dica: Dê ao seu assistente instruções claras e específicas sobre sua função e limitações. Por exemplo: "Você é um assistente 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 para criar um tíquete de suporte."

2. Criar um Aplicativo OAuth

Crie um aplicativo OAuth para autenticar seu widget:

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

3. Incorporar o Widget via Iframe

A forma mais simples de integrar o widget é incorporá-lo diretamente com um iframe. Esse método não exige inicialização em JavaScript e funciona imediatamente. Se você usar vários iframes na mesma página, mantenha cada integração isolada com seu próprio contêiner e parâmetros.

<iframe src="https://widget.companin.tech/embed/session?clientId=YOUR_CLIENT_ID&assistantId=YOUR_ASSISTANT_ID&configId=YOUR_CONFIG_ID&locale=en" style="border:none; width:100%; height:600px; border-radius:8px;" title="Customer Support AI Assistant Widget"></iframe>

Substitua YOUR_CLIENT_ID e YOUR_ASSISTANT_ID pelos seus valores reais. O parâmetro locale pode ser definido para corresponder ao idioma do seu site.

Avançado: Inicialização 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 scripts

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

<script  src="https://widget.companin.tech/widget.js"  data-client-id="YOUR_CLIENT_ID"  data-assistant-id="YOUR_ASSISTANT_ID"  data-config-id="YOUR_CONFIG_ID"  data-instance-id="support-widget"  data-locale="en"  data-dev="false"></script>

Atributos de script

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

  • data-client-id: Seu ID de cliente OAuth - Isso autentica seu aplicativo com nossa API. Pense nisso como a senha do seu aplicativo.
  • data-assistant-id: O UUID do seu assistente – identifica qual Assistente de IA do Suporte ao Cliente lida com as conversas.
  • data-config-id: O UUID da configuração do seu widget - Isso determina a aparência e o comportamento do seu widget (cores, tamanho, posição, etc.).
  • data-instance-id: ID de instância exclusivo por widget – obrigatório ao incorporar vários widgets na mesma página para evitar colisões e ativar a segmentação de API por instância.
  • data-custom-css: (opcional) regras CSS inline que serão injetadas no <head> do iframe antes da renderização do aplicativo. Use isto para substituir estilos sem modificar sua configuração. A codificação de URL é tratada automaticamente.
  • data-locale: Código do idioma (por exemplo, "en", "es", "fr") - Define o idioma de exibição do widget. O assistente ainda responderá em qualquer idioma em que os usuários escreverem.
  • data-dev: Defina como "true" para o modo de desenvolvimento (localhost) - Use isto ao testar localmente. Remova ou defina como "false" para produção.

O widget irá automaticamente:

  • Obtenha a configuração do ID de configuração
  • Dimensione-se de acordo com as dimensões do widget na configuração
  • Posicione o botão recolhido com base nas configurações
  • Iniciar aberto ou fechado com base na configuração start_open da configuração

Notas

  • O widget gerencia automaticamente seu próprio dimensionamento com base nas suas definições de configuração
  • A posição do botão recolhido pode ser personalizada através da configuração do widget
  • O widget respeita a configuração start_open da sua configuração
  • Todos os estilos (cores, fontes, dimensões) são controlados 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 de host local
  • 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 a origem do seu host (por exemplo, http://localhost:3000) esteja incluída em OAuth enabled_origins ao incorporar o widget em um iframe.
← VoltarPróximo: Referência da API →