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
"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
"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
"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
Use the
IdentifySupportVisitor
component for a simpler, declarative approach to visitor identification in Server Components.
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"