Programmatic access to support widget state and visitor management.

Overview

Cossistant provides React hooks for programmatic control over the support widget and visitor identification. These hooks are ideal when you need to integrate support functionality into custom components or respond to application events.

useSupport

Access support widget state and controls from any client component.

Basic Example

tscomponents/custom-support-button.tsx
"use client";
 
import { useSupport } from "@cossistant/next";
 
export function CustomSupportButton() {
  const { isOpen, toggle, unreadCount } = useSupport();
 
  return (
    <button
      onClick={toggle}
      className="relative rounded-lg 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 rounded-full bg-red-500 text-xs">
          {unreadCount}
        </span>
      )}
    </button>
  );
}

Return Values

Name

Type

useVisitor

Programmatically identify visitors and manage contact metadata.

Example: Identify on Auth

tscomponents/auth-handler.tsx
"use client";
 
import { useVisitor } from "@cossistant/next";
import { useEffect } from "react";
 
export function AuthHandler({ user }) {
  const { visitor, identify } = useVisitor();
 
  useEffect(() => {
    // Only identify if we have a user and visitor isn't already a contact
    if (user && !visitor?.contact) {
      identify({
        externalId: user.id,
        email: user.email,
        name: user.name,
        image: user.avatar,
      });
    }
  }, [user, visitor?.contact, identify]);
 
  return null;
}

Example: Update Metadata on Action

tscomponents/upgrade-button.tsx
"use client";
 
import { useVisitor } from "@cossistant/next";
 
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>;
}

Return Values

Name

Type

identify() Parameters

Parameter

Type

Types

PublicVisitor

The visitor object returned by the widget, representing an anonymous or identified visitor.

Property

Type

PublicContact

Contact information for an identified visitor.

Property

Type

PublicWebsiteResponse

Website configuration and agent availability information.

Property

Type

HumanAgent

Information about a human support agent.

Property

Type

AIAgent

Information about an AI support agent.

Property

Type

CossistantClient

The underlying client instance for direct API access. Used for advanced programmatic control.

Property

Type

IdentifyParams

Parameters for the identify() function.

Property

Type

VisitorMetadata

Key-value pairs for storing custom data about contacts.

Property

Type

Type Definition: Record<string, string | number | boolean | null>

SenderType

Enum defining who can send messages.

Property

Type

Type Definition: "visitor" | "team_member" | "ai"