@eduzz-automacoes/webchat-widget

Biblioteca oficial do webchat da Eduzz para:

• uso em apps React via npm
• publicação de bundle standalone em CDN
• integração com o backend/proxy do Service Hub

Uso via React

import { Webchat } from "@eduzz-automacoes/webchat-widget";
import "@eduzz-automacoes/webchat-widget/style.css";

export function Example() {
  return (
    <Webchat
      clientId="SEU_CLIENT_ID"
      userCredentials={{
        userId: "user_123",
        userToken: "token_gerado_no_backend",
      }}
      config={{
        botName: "Eduzzinho",
        brandColor: "#18181b",
        accentColor: "#f36f21",
        showWelcomeScreen: true,
      }}
    />
  );
}

Posição e afastamento da borda

A prop config.position ancora o widget em um canto (bottom-right — padrão — ou bottom-left). O afastamento da borda é controlado por offsetX (distância da borda lateral) e offsetY (distância da borda inferior). Ambos aceitam qualquer comprimento CSS e têm padrão "24px" — movem o FAB e o painel juntos, mantendo o alinhamento.

<Webchat
  clientId="SEU_CLIENT_ID"
  config={{
    position: "bottom-right",
    offsetX: "40px",
    offsetY: "40px",
  }}
/>

No modo CDN, os mesmos valores podem ser passados via EduzzWebchat.init({ offsetX, offsetY }) ou por data-attributes no script (data-offset-x="40px" / data-offset-y="40px").

No mobile o painel ocupa a tela inteira, então offsetX/offsetY não se aplicam nesse caso.

Sessão autenticada com auto-renovação

Em vez de injetar userCredentials estático, o produto pode fornecer getSession: o widget busca as credenciais no backend do próprio produto e renova o userToken automaticamente pouco antes de expirar. Os dois modos são mutuamente exclusivos — quando getSession é informado, userCredentials é ignorado.

import { Webchat } from "@eduzz-automacoes/webchat-widget";
import "@eduzz-automacoes/webchat-widget/style.css";

export function Example({ authId }: { authId: string }) {
  return (
    <Webchat
      clientId="SEU_CLIENT_ID"
      // chamado pelo widget; renove/recrie a sessão a partir do SEU backend
      getSession={async () => {
        const { userId, userToken, expiresAt } = await fetch(
          "/api/webchat/session",
          {
            method: "POST",
          },
        ).then((res) => res.json());

        return { userId, userToken, expiresAt }; // expiresAt: epoch em ms
      }}
      // recria a sessão quando este valor muda (ex.: troca de usuário autenticado)
      sessionKey={authId}
      // (opcional) observabilidade da sessão capturada — null quando ausente
      onSessionChange={(session) => console.log("webchat session", session)}
    />
  );
}

Se getSession rejeitar ou resolver sem userToken, o widget cai em modo anônimo.

Controle programático do painel

No modo React, a prop opcional onPanelApiChange entrega uma API imperativa para abrir/fechar o painel (e null quando o widget desmonta):

import { useRef } from "react";
import { Webchat } from "@eduzz-automacoes/webchat-widget";

export function Example() {
  const panelApiRef = useRef(null);

  return (
    <>
      <button onClick={() => panelApiRef.current?.open()}>
        Falar com suporte
      </button>
      <Webchat
        clientId="SEU_CLIENT_ID"
        onPanelApiChange={(panelApi) => {
          panelApiRef.current = panelApi;
        }}
      />
    </>
  );
}

A API tem open(), close(), toggle(), hide() e show() — toggle() equivale ao clique no FAB. hide() oculta o widget inteiro (FAB + painel) via CSS preservando o estado (conversa, painel aberto/fechado); show() reexibe exatamente como estava.

No modo CDN (global window.EduzzWebchat), os mesmos métodos ficam disponíveis na API global:

EduzzWebchat.open(); // abre o painel (no-op se já aberto ou não montado)
EduzzWebchat.close(); // fecha o painel (no-op se já fechado ou não montado)
EduzzWebchat.toggle(); // alterna o painel
EduzzWebchat.hide(); // oculta o widget inteiro (FAB + painel), preservando o estado
EduzzWebchat.show(); // reexibe o widget como estava antes do hide()

Chamadas feitas antes do bundle carregar (via loader script.js) são enfileiradas e executadas quando o runtime fica pronto. Sem init() prévio, são no-op silencioso.

Publicação manual no npm

pnpm --filter @eduzz-automacoes/webchat-widget build
cd packages/webchat-widget
pnpm pack