Saltar al contenido principal
Fluxo
Widget v0.1.0NEW: Paquetes más pequeños, carga diferida
arrow-leftAnteriorarrow-rightSiguiente

Referencia de hooks

Selección de hooks para el estado de Support, la navegación, la identidad, las conversaciones y las páginas propias.

Usa esta página cuando

Recurre a los hooks cuando personalizar mediante props no baste.

  • abrir o cerrar el widget desde tu propia interfaz
  • leer o cambiar el estado de la navegación
  • identificar visitantes o sincronizar metadatos de contacto desde el código
  • construir páginas propias sobre el runtime de Support

Si todavía estás dando forma al widget, empieza por Visión general, Cambia una sola cosa o Páginas y layouts.

Familias de hooks

  • useSupport y useSupportConfig para el estado del widget
  • useSupportNavigation y los hooks de página para una interfaz consciente de la ruta
  • useVisitor para la identidad y los metadatos de contacto
  • los hooks de conversación para páginas propias, borradores, escritura, subidas y envío
  • useFeatureFlag(s) y useOnboarding para el estado tipado de Support
  • los hooks de feedback para el estado del formulario y su envío

Los hooks de escritura que no exigen proveedor aceptan options.client. Si omites client, se usa el SupportProvider más cercano; si pasas un cliente explícito, el hook puede ejecutarse fuera del runtime del widget. Pasar client: null desactiva a propósito el recurso al proveedor. Esto vale para useSubmitFeedback, useSendMessage, useCreateConversation y useFileUpload.

useSupport

Accede al estado y a los controles del widget desde cualquier componente cliente.

Ejemplo 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 devueltos

Nombre

Tipo

useVisitor

Identifica visitantes desde código y gestiona los metadatos del contacto.

Ejemplo: identificar al iniciar sesión

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;
}

Ejemplo: actualizar los metadatos tras una acción

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 devueltos

Nombre

Tipo

Parámetros de identify()

Parámetro

Tipo

useSupportConfig

Consulta y controla la visibilidad del widget y su configuración de tamaño.

Ejemplo 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 devueltos

Nombre

Tipo

useSupportNavigation

Consulta el estado de navegación y los métodos de enrutado del widget.

Ejemplo 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 devueltos

Nombre

Tipo

useSupportHandle

Accede al manejador imperativo desde dentro del árbol del widget. Es una alternativa a usar refs sobre el componente Support. El hook devuelve null fuera del árbol del widget; la tabla de abajo describe el manejador cuando sí está disponible.

Ejemplo 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 devueltos

Nombre

Tipo

useHomePage

Hook de lógica para construir páginas de inicio propias. Aporta todo el estado y las acciones que necesita la página de inicio.

Ejemplo 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 devueltos

Nombre

Tipo

useConversationPage

Hook de lógica para construir páginas de conversación propias. Gestiona el ciclo de vida de la conversación, los mensajes y el redactor.

Ejemplo 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 devueltos

Nombre

Tipo

useMessageComposer

Hook para gestionar la redacción de mensajes con archivos adjuntos.

Ejemplo 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, el envío de mensajes puede resolver el cliente del proveedor. Los avisos de escritura necesitan un client explícito o las entradas de tiempo real que se ven en el código fuente completo de Support. Si construyes un redactor independiente y quieres indicadores de escritura, pasa el cliente explícitamente; si no, el mensaje se envía igual, pero la actividad de escritura no se comunica.

Valores devueltos

Nombre

Tipo

useFileUpload

Hook para gestionar subidas de archivos con seguimiento del progreso. Puede usar el cliente de SupportProvider o un cliente explícito para flujos sin proveedor. Si importas FluxoClient directamente, instala @fluxolat/core en tu app.

Ejemplo 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 un SupportProvider puedes llamar a useFileUpload() sin opciones y usará el cliente del proveedor.

Valores devueltos

Nombre

Tipo

useSupportText

Accede al sistema de localización del widget de soporte.

Ejemplo 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>
  );
}

Función de formato devuelta

useSupportText() devuelve una función de formato. La tabla de abajo documenta la referencia de esa función.

Nombre

Tipo

useSupportEvents

Accede al contexto de eventos para los eventos que emite tu propio código del widget. En la v0.2.0 el widget integrado no publica automáticamente eventos de ciclo de vida ni de mensaje. El hook devuelve null fuera del proveedor de eventos del widget; lee la referencia de eventos manuales antes de usarlo para analítica.

Ejemplo 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 devueltos

Nombre

Tipo

useSupportEventEmitter

Hook de conveniencia para emitir eventos desde dentro del widget.

Valores devueltos

Nombre

Tipo

Tipos

Los tipos compartidos de los hooks y del modelo de datos de soporte están ahora en la página de Tipos. Úsala para PublicVisitor, PublicWebsiteResponse, FluxoClient, TimelineItem, Conversation y el resto de la referencia seleccionada de tipos. Esta página no es una lista exhaustiva de exportaciones: las declaraciones de @fluxolat/react/hooks que instales incluyen además consultas de conversación y de línea de tiempo, hooks de escritura y de lectura en tiempo real, hooks de funcionalidades y onboarding, hooks de feedback y escrituras de creación, envío y subida.

¿Te resultó útil esta página?

Abre una incidencia de documentación ya rellenada para que el equipo pueda actuar.

Sí, me ayudóSe puede mejorar
arrow-left Textos e idiomaReferencia de eventos manuales arrow-right