Integração com Chat Widget

O Chat Widget permite incorporar seu Agente SipPulse AI diretamente em páginas web com um mínimo de código. Este guia aborda a criação, instalação, personalização e controle programático do widget.

1. Criar o Widget na Plataforma

1. Abra ⋮ → Publicar na lista de Agentes e clique em + Criar no cartão Chat Widget.
2. Preencha os campos de configuração inicial:

Campo	Descrição
Origens Permitidas	Domínios autorizados a carregar o widget (ex: exemplo.com, *.sua-empresa.com). Separe múltiplos domínios por vírgula. Solicitações de outras origens serão bloqueadas com um erro 403.
Mensagem de Boas-Vindas	Saudação inicial exibida quando o usuário abre o widget.
Cor do Widget	Cor primária para o ícone e cabeçalho, ajudando a alinhar o widget à identidade visual do seu site.

3. Clique em Criar. O cartão exibirá o widgetKey (identificador único) e o status mudará para Online.

O que é o widgetKey?

O widgetKey é a chave pública que conecta o widget no seu site ao seu Agente específico. Ele é essencial para a inicialização e deve ser tratado como um identificador único.

2. Instalação e Montagem

2.1 Via CDN (HTML Estático)

Este método é ideal para sites estáticos ou sistemas onde você não gerencia pacotes JavaScript.

<!-- 1. Crie um contêiner para o widget -->
<div id="sippulse-chat-widget"></div>

<!-- 2. Adicione o script do widget antes de fechar a tag </body> -->
<script src="https://cdn.jsdelivr.net/npm/@sippulseai/chat-widget/browser/chat-widget.latest.js" defer></script>

<!-- 3. Inicialize o widget quando o DOM estiver pronto -->
<script type="module">
  document.addEventListener("DOMContentLoaded", () => {
    const { ChatWidget } = SipPulseChat;

    const myWidget = new ChatWidget({
      widgetKey: "<SEU_WIDGET_KEY>",
      options: {
        color: "pulse",
        greetingMessage: "Olá! Como posso te ajudar hoje?",
        theme: "light",
        language: "pt",
        openOnLoad: false
      }
    });

    myWidget.mount("#sippulse-chat-widget");
  });
</script>

2.2 Via NPM (Frameworks como React, Vue, etc.)

Instale o pacote no seu projeto:

npm install @sippulseai/chat-widget
# ou
yarn add @sippulseai/chat-widget

React

// filepath: src/components/ChatWidgetComponent.jsx
import { useEffect, useRef } from "react";
import { ChatWidget } from "@sippulseai/chat-widget";

export default function ChatWidgetComponent() {
  const widgetRef = useRef(null);

  useEffect(() => {
    if (widgetRef.current) {
      const widget = new ChatWidget({
        widgetKey: "<SEU_WIDGET_KEY>",
        options: { color: "pulse", openOnLoad: false }
      });
      widget.mount(widgetRef.current);

      // Opcional: Limpa a instância quando o componente é desmontado
      return () => widget.destroy();
    }
  }, []);

  return <div ref={widgetRef} />;
}

Vue 3

<!-- filepath: src/components/ChatWidget.vue -->
<template>
  <div ref="widgetContainer"></div>
</template>

<script setup>
import { onMounted, onUnmounted, ref } from "vue";
import { ChatWidget } from "@sippulseai/chat-widget";

const widgetContainer = ref(null);
let widgetInstance = null;

onMounted(() => {
  if (widgetContainer.value) {
    widgetInstance = new ChatWidget({
      widgetKey: "<SEU_WIDGET_KEY>",
      options: { theme: "dark", language: "en" }
    });
    widgetInstance.mount(widgetContainer.value);
  }
});

onUnmounted(() => {
  if (widgetInstance) {
    widgetInstance.destroy();
  }
});
</script>

3. Opções de Configuração

Você pode personalizar o widget passando um objeto options durante a instanciação. Essas opções sobrescrevem as configurações salvas na plataforma.

Opção	Tipo	Padrão	Descrição
color	string	"pulse"	Cor do tema. Valores: "blue", "green", "red", "yellow", "purple", "orange", "tomato", "indigo", "pulse".
greetingMessage	string	(Definido na UI)	Mensagem de boas-vindas.
theme	"light" | "dark"	"light"	Tema visual do widget.
language	"en" | "pt"	"pt"	Idioma da interface do widget (não afeta as respostas do Agente).
openOnLoad	boolean	false	Se true, o widget carrega já expandido.

4. Ativar ou Desativar o Widget

Use o toggle no cartão Chat Widget na plataforma SipPulse AI para pausar ou retomar o atendimento rapidamente, sem precisar remover o código do seu site.

• Ligado: O widget funciona normalmente.
• Desligado: O widget não carrega e não responde a novas conversas.

5. Depuração e Solução de Problemas

Sintoma	Causa Provável	Ação Corretiva
Erro 403 Origin not allowed no console	O domínio do seu site não está na lista de Origens Permitidas.	Adicione o domínio exato (ex: meusite.com) na configuração do widget na plataforma SipPulse AI.
Erro ChatWidget is not defined	O script CDN não carregou ou foi bloqueado.	Verifique se a URL do script está correta e se não há bloqueios por políticas de segurança (CSP) ou ad-blockers.
Widget não aparece na tela	O seletor do mount() não encontrou o contêiner ou o contêiner não existe no DOM no momento da chamada.	Garanta que o <div> de contêiner exista no HTML e que o script de montagem rode após o DOM ser carregado (DOMContentLoaded).
Widget renderiza, mas não conecta	widgetKey inválido ou o widget está desativado na plataforma.	Confirme se o widgetKey está correto e se o status do widget é Online.

6. Custos

A utilização do Chat Widget não gera custos adicionais. A cobrança está associada apenas ao consumo de tokens do Agente durante as conversas, conforme o plano contratado.