Hooks

🔧 Core Call Management

useCVICall

Essential hook for joining and leaving video calls.

npx @tavus/cvi-ui@latest add use-cvi-call

Description
Code

A React hook that provides comprehensive call management functionality for video conversations. This hook handles the core lifecycle of video calls, including connection establishment, room joining, and proper cleanup when leaving calls.Purpose:

Manages call join/leave operations with proper state management
Handles connection lifecycle and cleanup
Provides simple interface for call control

Return Values:

joinCall (function): Function to join a call by URL - handles Daily.co room connection
leaveCall (function): Function to leave the current call - properly disconnects and cleans up resources

import { useCVICall } from './hooks/use-cvi-call';

const CallManager = () => {
  const { joinCall, leaveCall } = useCVICall();

  const handleJoin = () => {
    joinCall({ url: 'https://your-daily-room-url' });
  };

  return (
    <div>
      <button onClick={handleJoin}>Join Call</button>
      <button onClick={leaveCall}>Leave Call</button>
    </div>
  );
};

useStartHaircheck

A React hook that manages device permissions and camera initialization for the hair-check component.

npx @tavus/cvi-ui@latest add use-start-haircheck

Description
Code

A React hook that manages device permissions and camera initialization for the hair-check component.Purpose:

Monitors device permission states
Starts camera and microphone when appropriate
Provides permission state for UI conditional rendering
Handles permission request flow

Return Values:

isPermissionsPrompt (boolean): Browser is prompting for device permission
isPermissionsLoading (boolean): Permissions are being processed or camera is initializing
isPermissionsGranted (boolean): Device permission granted
isPermissionsDenied (boolean): Device permission denied
requestPermissions (function): Function to request camera and microphone permissions

import { useStartHaircheck } from './hooks/use-start-haircheck';

const HairCheckComponent = () => {
  const {
    isPermissionsPrompt,
    isPermissionsLoading,
    isPermissionsGranted,
    isPermissionsDenied,
    requestPermissions
  } = useStartHaircheck();

  useEffect(() => {
    requestPermissions();
  }, []);

  return (
    <div>
      {isPermissionsLoading && <InitializingSpinner />}
      {isPermissionsPrompt && <PermissionPrompt />}
      {isPermissionsDenied && <PermissionDeniedMessage />}
      {isPermissionsGranted && <VideoPreview />}
    </div>
  );
};

🎥 Media Controls

useLocalCamera

A React hook that provides local camera state and toggle functionality.

npx @tavus/cvi-ui@latest add use-local-camera

Description
Code

A React hook that provides local camera state and toggle functionality.Purpose:

Manages local camera state (on/off)
Tracks camera permission and ready state

Return Values:

onToggleCamera (function): Function to toggle camera on/off
isCamReady (boolean): Camera permission is granted and ready
isCamMuted (boolean): Camera is currently turned off
localSessionId (string): Local session ID

import { useLocalCamera } from './hooks/use-local-camera';

const CameraControls = () => {
  const { onToggleCamera, isCamReady, isCamMuted } = useLocalCamera();

  return (
    <button
      onClick={onToggleCamera}
      disabled={!isCamReady}
    >
      {isCamMuted ? 'Turn Camera On' : 'Turn Camera Off'}
    </button>
  );
};

useLocalMicrophone

A React hook that provides local microphone state and toggle functionality.

npx @tavus/cvi-ui@latest add use-local-microphone

Description
Code

A React hook that provides local microphone state and toggle functionality.Purpose:

Manages local microphone state (on/off)
Tracks microphone permission and ready state

Return Values:

onToggleMicrophone (function): Function to toggle microphone on/off
isMicReady (boolean): Microphone permission is granted and ready
isMicMuted (boolean): Microphone is currently turned off
localSessionId (string): Local session ID

import { useLocalMicrophone } from './hooks/use-local-microphone';

const MicrophoneControls = () => {
  const { onToggleMicrophone, isMicReady, isMicMuted } = useLocalMicrophone();

  return (
    <button
      onClick={onToggleMicrophone}
      disabled={!isMicReady}
    >
      {isMicMuted ? 'Unmute' : 'Mute'}
    </button>
  );
};

useLocalScreenshare

A React hook that provides local screen sharing state and toggle functionality.

npx @tavus/cvi-ui@latest add use-local-screenshare

Description
Code

A React hook that provides local screen sharing state and toggle functionality.Purpose:

Manages screen sharing state (on/off)
Provides screen sharing toggle function
Handles screen share start/stop with optimized display media options

Return Values:

onToggleScreenshare (function): Function to toggle screen sharing on/off
isScreenSharing (boolean): Whether screen sharing is currently active
localSessionId (string): Local session ID

Display Media Options: When starting screen share, the hook uses the following optimized settings:

Audio: Disabled (false)
Self Browser Surface: Excluded
Surface Switching: Included
Video Resolution: 1920x1080

import { useLocalScreenshare } from './hooks/use-local-screenshare';

const ScreenShareControls = () => {
  const { onToggleScreenshare, isScreenSharing } = useLocalScreenshare();

  return (
    <button
      onClick={onToggleScreenshare}
      className={isScreenSharing ? 'active' : ''}
    >
      {isScreenSharing ? 'Stop Sharing' : 'Share Screen'}
    </button>
  );
};

useRequestPermissions

A React hook that requests camera and microphone permissions with optimized audio processing settings.

npx @tavus/cvi-ui@latest add use-request-permissions

Description
Code

A React hook that requests camera and microphone permissions with optimized audio processing settings.Purpose:

Requests camera and microphone permissions from the user
Starts camera and audio with specific configuration
Applies noise cancellation audio processing
Provides a clean interface for permission requests

Return Values:

requestPermissions (function): Function to request camera and microphone permissions

Configuration: When requesting permissions, the hook uses the following settings:

Video: Started on (startVideoOff: false)
Audio: Started on (startAudioOff: false)
Audio Source: Default system audio input
Audio Processing: Noise cancellation enabled

import { useRequestPermissions } from './hooks/use-request-permissions';

const PermissionRequest = () => {
  const requestPermissions = useRequestPermissions();

  const handleRequestPermissions = async () => {
    try {
      await requestPermissions();
      console.log('Permissions granted successfully');
    } catch (error) {
      console.error('Failed to get permissions:', error);
    }
  };

  return (
    <button onClick={handleRequestPermissions}>
      Request Camera & Microphone Permissions
    </button>
  );
};

👥 Participant Management

useReplicaIDs

A React hook that returns the IDs of all Tavus replica participants in a call.

npx @tavus/cvi-ui@latest add use-replica-ids

Description
Code

A React hook that returns the IDs of all Tavus replica participants in a call.Purpose:

Filters and returns participant IDs where user_id includes ‘tavus-replica’

Return Value:

string[] — Array of replica participant IDs

import { useReplicaIDs } from './hooks/use-replica-ids';

const ids = useReplicaIDs();
// ids is an array of participant IDs for Tavus replicas

useRemoteParticipantIDs

A React hook that returns the IDs of all remote participants in a call.

npx @tavus/cvi-ui@latest add use-remote-participant-ids

Description
Code

A React hook that returns the IDs of all remote participants in a call.Purpose:

Returns participant IDs for all remote participants (excluding local user)

Return Value:

string[] — Array of remote participant IDs

import { useRemoteParticipantIDs } from './hooks/use-remote-participant-ids';

const remoteIds = useRemoteParticipantIDs();
// remoteIds is an array of remote participant IDs

💬 Conversation & Events

useObservableEvent

A React hook that listens for CVI app messages and provides a callback mechanism for handling various conversation events.

npx @tavus/cvi-ui@latest add cvi-events-hooks

Description
Code

A React hook that listens for CVI app messages and provides a callback mechanism for handling various conversation events.Purpose:

Listens for app messages from the Daily.co call mapped to CVI events
Handles various conversation event types (utterances, tool calls, speaking events, etc.)
Provides type-safe event handling for CVI interactions

Parameters:

callback (function): Function called when app messages are received

Event Types: This hook handles all CVI conversation events. For detailed information about each event type, see the Tavus Interactions Protocol Documentation.

import { useObservableEvent } from './hooks/cvi-events-hooks';

const ConversationHandler = () => {
  useObservableEvent((event) => {
    switch (event.event_type) {
      case 'conversation.utterance':
        console.log('Speech:', event.properties.speech);
        break;
      case 'conversation.replica.started_speaking':
        console.log('Replica started speaking');
        break;
      case 'conversation.user.stopped_speaking':
        console.log('User stopped speaking');
        break;
    }
  });

  return <div>Listening for conversation events...</div>;
};

useClosedCaption

A React hook that returns the latest closed caption with the speaker’s role and text.

npx @tavus/cvi-ui@latest add use-closed-caption

Description
Code

A React hook that returns the latest closed caption with the speaker’s role and text. Subscribes to conversation.utterance.streaming events for both user and replica roles and exposes the latest caption to your UI.Purpose:

Streams captions for both the user and the replica from conversation.utterance.streaming
Updates progressively as either party speaks
Auto-clears the caption 2 seconds after a final utterance
Returns null when no caption is currently being shown

Return Value:

ClosedCaption | null where ClosedCaption is { role: "user" | "replica"; text: string }

import { useClosedCaption } from './hooks/use-closed-caption';

const Captions = () => {
  const caption = useClosedCaption();

  if (!caption) return null;

  return (
    <div role="status" aria-live="polite">
      <span>{caption.role === 'replica' ? 'Replica' : 'You'}</span>
      <span>{caption.text}</span>
    </div>
  );
};

useSendAppMessage

A React hook that provides a function to send CVI app messages to other participants in the call.

npx @tavus/cvi-ui@latest add cvi-events-hooks

Description
Code

A React hook that provides a function to send CVI app messages to other participants in the call.Purpose:

Sends various types of conversation messages to the CVI system
Supports echo, respond, interrupt, and context management messages
Provides type-safe message sending with proper validation
Enables real-time communication with Tavus replicas and conversation management

Return Value:

(message: SendAppMessageProps) => void - Function that sends the message when called

Message Types: This hook supports all CVI interaction types. For detailed information about each interaction type and their properties, see the Tavus Interactions Protocol Documentation.

import { useSendAppMessage } from './hooks/cvi-events-hooks';

const MessageSender = () => {
  const sendMessage = useSendAppMessage();

  // Send a text echo
  const sendTextEcho = () => {
    sendMessage({
      message_type: "conversation",
      event_type: "conversation.echo",
      conversation_id: "conv-123",
      properties: {
        modality: "text",
        text: "Hello, world!",
        audio: "",
        sample_rate: 16000,
        inference_id: "inf-456",
        done: true
      }
    });
  };

  // Send a text response
  const sendResponse = () => {
    sendMessage({
      message_type: "conversation",
      event_type: "conversation.respond",
      conversation_id: "conv-123",
      properties: {
        text: "This is my response to the conversation."
      }
    });
  };

  return (
    <div>
      <button onClick={sendTextEcho}>Send Text Echo</button>
      <button onClick={sendResponse}>Send Response</button>
    </div>
  );
};

useChat

A React hook that powers a chat experience on top of the live conversation. It tracks the running transcript and provides a function to send a user turn back to the replica.

npx @tavus/cvi-ui@latest add use-chat

Description
Code

A React hook that powers a chat experience on top of the live conversation. Subscribes to Daily app messages and tracks conversation.utterance events from both user and replica roles, and exposes a sendMessage function that dispatches conversation.respond.Purpose:

Builds a chronological transcript of user and replica messages from conversation.utterance events
Optimistically appends locally sent messages so the UI updates immediately, then reconciles each pending message with the matching server-side utterance using inference_id
Dispatches conversation.respond when the user sends a chat message
Designed to back the Chat components (ChatProvider, ChatPanel, ChatButton)

Return Values:

messages (ChatMessage[]): Ordered transcript where ChatMessage is { id: string; role: "user" | "replica"; text: string; inference_id?: string; pending?: boolean }
sendMessage ((text: string) => void): Sends a user turn — appends a pending local echo to messages and dispatches conversation.respond. The pending entry is reconciled (and pending cleared) when the matching utterance arrives by inference_id.

import { useChat } from './hooks/use-chat';

const Chat = () => {
  const { messages, sendMessage } = useChat();
  const [draft, setDraft] = useState('');

  const onSubmit = () => {
    const text = draft.trim();
    if (!text) return;
    sendMessage(text);
    setDraft('');
  };

  return (
    <div>
      <ul>
        {messages.map((m) => (
          <li key={m.id} aria-busy={m.pending || undefined}>
            <strong>{m.role === 'replica' ? 'Replica' : 'You'}:</strong> {m.text}
          </li>
        ))}
      </ul>
      <textarea
        value={draft}
        onChange={(e) => setDraft(e.target.value)}
      />
      <button onClick={onSubmit}>Send</button>
    </div>
  );
};

Getting started

Build

Deploy

Debug

Guides

Resources

🔧 Core Call Management

useCVICall

useStartHaircheck

🎥 Media Controls

useLocalCamera

useLocalMicrophone

useLocalScreenshare

useRequestPermissions

👥 Participant Management

useReplicaIDs

useRemoteParticipantIDs

💬 Conversation & Events

useObservableEvent

useClosedCaption

useSendAppMessage

useChat

Getting started

Build

Deploy

Debug

Guides

Resources

Documentation Index

​🔧 Core Call Management

​useCVICall

​useStartHaircheck

​🎥 Media Controls

​useLocalCamera

​useLocalMicrophone

​useLocalScreenshare

​useRequestPermissions

​👥 Participant Management

​useReplicaIDs

​useRemoteParticipantIDs

​💬 Conversation & Events

​useObservableEvent

​useClosedCaption

​useSendAppMessage

​useChat

🔧 Core Call Management

useCVICall

useStartHaircheck

🎥 Media Controls

useLocalCamera

useLocalMicrophone

useLocalScreenshare

useRequestPermissions

👥 Participant Management

useReplicaIDs

useRemoteParticipantIDs

💬 Conversation & Events

useObservableEvent

useClosedCaption

useSendAppMessage

useChat