Pular para o conteúdo principal
Fluxo
Widget v0.1.0NEW: Pacotes menores, carregamento sob demanda
arrow-leftAnteriorarrow-rightPróximo

Referência de hooks

Seleção de hooks para o estado do Support, a navegação, a identidade, as conversas e as páginas próprias.

Use esta página quando

Recorra aos hooks quando personalizar por props não for suficiente.

  • abrir ou fechar o widget a partir da sua própria interface
  • ler ou mudar o estado da navegação
  • identificar visitantes ou sincronizar metadados de contato pelo código
  • construir páginas próprias sobre o runtime do Support

Se você ainda está moldando o widget, comece por Visão geral, Mude uma coisa só ou Páginas e layouts.

Famílias de hooks

  • useSupport e useSupportConfig para o estado do widget
  • useSupportNavigation e os hooks de página para uma interface ciente da rota
  • useVisitor para a identidade e os metadados de contato
  • os hooks de conversa para páginas próprias, rascunhos, digitação, uploads e envio
  • useFeatureFlag(s) e useOnboarding para o estado tipado do Support
  • os hooks de feedback para o estado do formulário e o envio

Os hooks de escrita que não exigem provider aceitam options.client. Se você omitir client, é usado o SupportProvider mais próximo; se passar um cliente explícito, o hook pode rodar fora do runtime do widget. Passar client: null desativa de propósito o recurso ao provider. Isso vale para useSubmitFeedback, useSendMessage, useCreateConversation e useFileUpload.

useSupport

Acesse o estado e os controles do widget de suporte a partir de qualquer componente cliente.

Exemplo básico

tscomponents/custom-support-button.tsx
"use client";
 
import { useSupport } from "@fluxolat/react";
 
export function CustomSupportButton() {
  const { isOpen, toggle, unreadCount } = useSupport();
 
  return (
    <button
      onClick={toggle}
      className="relative border border-primary bg-primary px-4 py-2 text-white"
    >
      Support
      {unreadCount > 0 && (
        <span className="absolute -right-1 -top-1 flex h-5 w-5 items-center justify-center bg-red-500 text-xs">
          {unreadCount}
        </span>
      )}
    </button>
  );
}

Valores retornados

Nome

Tipo

useVisitor

Identifique visitantes via código e gerencie os metadados do contato.

Exemplo: identificar no login

tscomponents/auth-handler.tsx
"use client";
 
import { useVisitor } from "@fluxolat/react";
import { useEffect } from "react";
 
export function AuthHandler({ user }) {
  const { identify } = useVisitor();
 
  useEffect(() => {
    if (!user) {
      return;
    }
 
    void identify({
      externalId: user.id,
      email: user.email,
      name: user.name,
      image: user.avatar,
    });
  }, [user?.id, user?.email, user?.name, user?.avatar, identify]);
 
  return null;
}

Exemplo: atualizar os metadados após uma ação

tscomponents/upgrade-button.tsx
"use client";
 
import { useVisitor } from "@fluxolat/react";
 
export function UpgradeButton() {
  const { setVisitorMetadata } = useVisitor();
 
  const handleUpgrade = async () => {
    // Upgrade user's plan
    await upgradeToPro();
 
    // Update contact metadata so support agents see the change
    await setVisitorMetadata({
      plan: "pro",
      upgradedAt: new Date().toISOString(),
      mrr: 99,
    });
  };
 
  return <button onClick={handleUpgrade}>Upgrade to Pro</button>;
}

Valores retornados

Nome

Tipo

Parâmetros de identify()

Parâmetro

Tipo

useSupportConfig

Consulte e controle a visibilidade do widget e a configuração de tamanho.

Exemplo básico

tscomponents/custom-toggle.tsx
"use client";
 
import { useSupportConfig } from "@fluxolat/react";
 
export function CustomToggle() {
  const { isOpen, open, close, toggle, size } = useSupportConfig();
 
  return (
    <div className="flex gap-2">
      <button onClick={toggle}>
        {isOpen ? "Close Support" : "Open Support"}
      </button>
      <span>Size: {size}</span>
    </div>
  );
}

Valores retornados

Nome

Tipo

useSupportNavigation

Consulte o estado de navegação e os métodos de roteamento do widget.

Exemplo básico

tscomponents/navigation-buttons.tsx
"use client";
 
import { useSupportNavigation } from "@fluxolat/react";
 
export function NavigationButtons() {
  const { page, navigate, goBack, canGoBack } = useSupportNavigation();
 
  return (
    <div className="flex gap-2">
      {canGoBack && <button onClick={goBack}>← Back</button>}
      <span>Current page: {page}</span>
      <button onClick={() => navigate({ page: "HOME" })}>Go Home</button>
      <button
        onClick={() =>
          navigate({
            page: "CONVERSATION",
            params: { conversationId: "conv_123" }
          })
        }
      >
        Open Conversation
      </button>
    </div>
  );
}

Valores retornados

Nome

Tipo

useSupportHandle

Acesse o manipulador imperativo de dentro da árvore do widget. É uma alternativa a usar refs no componente Support. O hook devolve null fora da árvore do widget; a tabela abaixo descreve o manipulador quando ele está disponível.

Exemplo básico

tscomponents/help-button.tsx
"use client";
 
import { useSupportHandle } from "@fluxolat/react";
 
export function HelpButton() {
  const support = useSupportHandle();
 
  const handleNeedHelp = () => {
    // Open support and start a new conversation
    support?.startConversation("I need help with my order");
  };
 
  return (
    <button onClick={handleNeedHelp}>
      Need Help?
    </button>
  );
}

Valores retornados

Nome

Tipo

useHomePage

Hook de lógica para construir páginas iniciais próprias. Fornece todo o estado e as ações de que a página inicial precisa.

Exemplo básico

tspages/custom-home.tsx
"use client";
 
import { useHomePage } from "@fluxolat/react";
 
export function CustomHomePage() {
  const home = useHomePage({
    onStartConversation: () => console.log("Conversation started"),
    onOpenConversation: (id) => console.log("Opened:", id),
    onOpenConversationHistory: () => console.log("Opened history"),
  });
 
  return (
    <div>
      <h1>Welcome!</h1>
 
      {home.lastOpenConversation && (
        <button onClick={() => home.openConversation(home.lastOpenConversation!.id)}>
          Continue conversation
        </button>
      )}
 
      <button onClick={() => home.startConversation()}>
        Start new conversation
      </button>
 
      {home.availableConversationsCount > 0 && (
        <button onClick={home.openConversationHistory}>
          View {home.availableConversationsCount} conversations
        </button>
      )}
    </div>
  );
}

Valores retornados

Nome

Tipo

useConversationPage

Hook de lógica para construir páginas de conversa próprias. Gerencia o ciclo de vida da conversa, as mensagens e o redator.

Exemplo básico

tspages/custom-conversation.tsx
"use client";
 
import { useConversationPage } from "@fluxolat/react";
 
export function CustomConversationPage({ conversationId }: { conversationId: string }) {
  const conversation = useConversationPage({
    conversationId,
    onConversationIdChange: (id) => console.log("Active:", id),
  });
 
  return (
    <div>
      {/* Messages */}
      <div className="flex-1 overflow-y-auto">
        {conversation.items.map((item) => (
          <div key={item.id}>{/* Render message */}</div>
        ))}
      </div>
 
      {/* Composer */}
      <form onSubmit={(e) => { e.preventDefault(); conversation.composer.submit(); }}>
        <input
          value={conversation.composer.message}
          onChange={(e) => conversation.composer.setMessage(e.target.value)}
          placeholder={conversation.isPending ? "Start the conversation..." : "Type a message..."}
        />
        <button
          type="submit"
          disabled={!conversation.composer.canSubmit || conversation.composer.isSubmitting}
        >
          Send
        </button>
      </form>
    </div>
  );
}

Valores retornados

Nome

Tipo

useMessageComposer

Hook para gerenciar a redação de mensagens com arquivos anexados.

Exemplo básico

tscomponents/message-input.tsx
"use client";
 
import { useMessageComposer } from "@fluxolat/react";
 
export function MessageInput({ conversationId }: { conversationId: string }) {
  const composer = useMessageComposer({
    conversationId,
    onMessageSent: () => console.log("Message sent!"),
  });
 
  return (
    <form onSubmit={(e) => { e.preventDefault(); composer.submit(); }}>
      <input
        value={composer.message}
        onChange={(e) => composer.setMessage(e.target.value)}
        placeholder="Type a message..."
      />
      <input
        type="file"
        multiple
        onChange={(e) => {
          if (e.target.files) {
            composer.addFiles(Array.from(e.target.files));
          }
        }}
      />
      {composer.files.map((file, index) => (
        <span key={file.name}>
          {file.name}{" "}
          <button type="button" onClick={() => composer.removeFile(index)}>
            ×
          </button>
        </span>
      ))}
      <button type="submit" disabled={!composer.canSubmit || composer.isSubmitting}>
        {composer.isSubmitting ? "Sending..." : "Send"}
      </button>
    </form>
  );
}

Dentro de SupportProvider, o envio de mensagens consegue resolver o cliente do provider. Os avisos de digitação exigem um client explícito ou as entradas de tempo real que aparecem no código-fonte completo do Support. Se você construir um redator independente e quiser indicadores de digitação, passe o cliente explicitamente; caso contrário, a mensagem é enviada do mesmo jeito, mas a atividade de digitação não é comunicada.

Valores retornados

Nome

Tipo

useFileUpload

Hook para gerenciar uploads de arquivos com acompanhamento do progresso. Pode usar o cliente do SupportProvider ou um cliente explícito para fluxos sem provider. Se você importar FluxoClient diretamente, instale @fluxolat/core no seu app.

Exemplo básico

tscomponents/file-uploader.tsx
"use client";
 
import { FluxoClient } from "@fluxolat/core";
import { useFileUpload } from "@fluxolat/react/hooks/use-file-upload";
 
const client = new FluxoClient({ publicKey: "pk_test_xxxx" });
 
export function FileUploader() {
  const upload = useFileUpload({ client });
  const conversationId = "conv_123";
 
  return (
    <div>
      <input
        type="file"
        multiple
        onChange={async (e) => {
          if (e.target.files?.length) {
            await upload.uploadFiles(Array.from(e.target.files), conversationId);
          }
        }}
      />
      {upload.isUploading && (
        <div>
          <progress value={upload.progress} max={100} />
          <span>{upload.progress}%</span>
        </div>
      )}
      {upload.error && <p className="text-red-500">{upload.error.message}</p>}
    </div>
  );
}

Dentro de um SupportProvider você pode chamar useFileUpload() sem opções e ele usará o cliente do provider.

Valores retornados

Nome

Tipo

useSupportText

Acesse o sistema de localização do widget de suporte.

Exemplo básico

tscomponents/localized-button.tsx
"use client";
 
import { useSupportText } from "@fluxolat/react";
 
export function LocalizedButton() {
  const format = useSupportText();
 
  return (
    <button>
      {format("common.actions.askQuestion")}
    </button>
  );
}

Função de formatação retornada

useSupportText() devolve uma função de formatação. A tabela abaixo documenta a referência dessa função.

Nome

Tipo

useSupportEvents

Acesse o contexto de eventos para os eventos emitidos pelo seu próprio código do widget. Na v0.2.0 o widget embutido não publica automaticamente eventos de ciclo de vida nem de mensagem. O hook devolve null fora do provider de eventos do widget; leia a referência de eventos manuais antes de usá-lo para análises.

Exemplo básico

tscomponents/analytics-tracker.tsx
"use client";
 
import { useSupportEvents } from "@fluxolat/react";
import { useEffect } from "react";
 
export function AnalyticsTracker() {
  const events = useSupportEvents();
 
  useEffect(() => {
    if (!events) return;
 
    const unsubscribe = events.subscribe("messageSent", (event) => {
      // Track in your analytics
      analytics.track("support_message_sent", {
        conversationId: event.conversationId,
      });
    });
 
    return unsubscribe;
  }, [events]);
 
  return null;
}

Valores retornados

Nome

Tipo

useSupportEventEmitter

Hook de conveniência para emitir eventos de dentro do widget.

Valores retornados

Nome

Tipo

Tipos

Os tipos compartilhados dos hooks e do modelo de dados de suporte agora ficam na página de Tipos. Use-a para PublicVisitor, PublicWebsiteResponse, FluxoClient, TimelineItem, Conversation e o resto da referência selecionada de tipos. Esta página não é uma lista exaustiva de exportações: as declarações de @fluxolat/react/hooks que você instalar incluem também consultas de conversa e de linha do tempo, hooks de digitação e leitura em tempo real, hooks de funcionalidades e onboarding, hooks de feedback e escritas de criação, envio e upload.

Esta página foi útil?

Abra uma issue de documentação já preenchida para que a equipe possa agir.

Sim, ajudouPode melhorar
arrow-left Textos e idiomaReferência de eventos manuais arrow-right