> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/react/useconvaiclient-hook.md). # useConvaiClient hook reference Reference for the React hook that owns a Convai client, including its parameter, every returned field, and the state it keeps for rendering. `useConvaiClient` is the React hook exported from `@convai/web-sdk/react`. It creates one `ConvaiClient` for the lifetime of the component, subscribes to its events, and returns the client's API together with React state that re-renders the component when the conversation changes. ### Signature ```ts function useConvaiClient(config?: ConvaiConfig): IConvaiClient & { connectWithPublicationGrant: ( launchToken: string, options?: PublishedChatConnectOptions, ) => Promise; activity: string; chatMessages: ChatMessage[]; isAudioMuted: boolean; isVideoEnabled: boolean; isScreenShareActive: boolean; }; ``` | Parameter | Type | Default | Description | | --------- | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `config` | `ConvaiConfig` | none | Connection config stored on first render and used by `connect()` when it is called with no argument. Later changes to this argument are ignored. Every field is listed in the [Configuration and type reference](/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/vanilla-typescript/best-practices-and-type-definitions.md). | The hook creates its client once, with `useState`. Listeners are removed and the hidden WebSocket audio element is removed when the component unmounts. The hook does not disconnect on unmount; call `disconnect()` yourself when the session should end. ### React state These fields are React state. Reading them in render keeps the component in step with the conversation. | Field | Type | Updated when | | --------------------- | ------------------- | ----------------------------------------------------------------------------------------------------- | | `state` | `ConvaiClientState` | The client emits `stateChange`, `connect`, or `disconnect`. | | `activity` | `string` | The client emits `stateChange`, `botReady`, or `disconnect`. See [Activity values](#activity-values). | | `chatMessages` | `ChatMessage[]` | The client emits `messagesChange`. Cleared to `[]` on `disconnect`. | | `userTranscription` | `string` | The client emits `userTranscriptionChange`. Holds the live, non-final transcription of your speech. | | `isBotReady` | `boolean` | Set to `true` on `botReady` and to `false` on `disconnect`. | | `isAudioMuted` | `boolean` | `audioControls` emits `audioStateChange`. Set to `true` on `disconnect`. | | `isVideoEnabled` | `boolean` | `videoControls` emits `videoStateChange`. Set to `false` on `disconnect`. | | `isScreenShareActive` | `boolean` | `screenShareControls` emits `screenShareStateChange`. Set to `false` on `disconnect`. | `activity`, `isAudioMuted`, `isVideoEnabled`, and `isScreenShareActive` exist only on the hook's return value. A `ConvaiClient` created directly does not have them. ### Activity values `activity` starts as `"Idle"`. After that the hook sets it from the client state in this order of priority: | Value | Set when | | ----------------- | ------------------------------------------------------------------- | | `"Connecting..."` | `state.isConnecting` is `true`. | | `"Disconnected"` | Not connected and not connecting, or the client emits `disconnect`. | | `"Speaking"` | The character is speaking. | | `"Listening"` | You are speaking. | | `"Thinking"` | The character is preparing a response. | | `"Connected"` | Connected with none of the above, or when `botReady` fires. | ### Client values These fields are read from the client each time the component renders. They do not trigger a render on their own. | Field | Type | Description | | ------------------------ | -------------------------------------- | ----------------------------------------------------------------------------- | | `connectionType` | `'audio' \| 'video' \| 'text' \| null` | Connection type of the current session. `null` when not connected. | | `isPublishedChatSession` | `boolean` | `true` when the client was last connected with `connectWithPublicationGrant`. | | `apiKey` | `string` | API key of the current connection. Present only when one was used. | | `authToken` | `string` | Auth token of the current connection. Present only when one was used. | | `characterId` | `string \| null` | Character ID of the current connection. | | `characterSessionId` | `string \| null` | Session ID returned by Convai for the current conversation. | | `requestTraceId` | `string \| null` | Trace ID for the most recent connection request, when Convai provided one. | | `conversationSessionId` | `number` | Turn counter used by the `conversationStart` and `turnEnd` events. | | `room` | `Room` | The LiveKit room. Pass it to `AudioContext.Provider` in a custom UI. | | `audioControls` | `AudioControls` | Microphone controls. | | `videoControls` | `VideoControls` | Camera and vision source controls. | | `screenShareControls` | `ScreenShareControls` | Screen share controls. | | `blendshapeQueue` | `BlendshapeQueue` | Buffered lip sync frames. | | `memoryManager` | `MemoryManager \| null` | Long-term memory API. `null` until connected with an `endUserId`. | ### Methods Every method is bound to the hook's client, so you can pass it directly as an event handler. Behavior, parameters, and errors are documented in the [ConvaiClient reference](/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/vanilla-typescript/convaiclient-core-api.md). | Method | Notes | | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `connect(config?)` | Connects with `config`, or with the config passed to the hook. Throws `No configuration provided. Pass config to useConvaiClient() or to connect()` when neither exists. | | `connectWithPublicationGrant(launchToken, options?)` | Connects to a published text chat with a single-use launch token. | | `disconnect()` | Ends the session. | | `reconnect()` | Connects again with the last stored config. | | `resetSession()` | Clears the conversation and starts a new session on the next connect. On a live connection, call `disconnect()` first, then `connect()` again. | | `sendUserTextMessage(text, options?)` | Sends a text message. | | `sendTriggerMessage(triggerName?, triggerMessage?)` | Fires a trigger. | | `sendInterruptMessage()` | Interrupts the character's current response. | | `sendActionResult(result)` | Returns the result of a client tool call. | | `resetIdleTimer()` | Resets the idle timer for the session. | | `updateTemplateKeys(templateKeys)` | Replaces the Narrative Design template keys. | | `updateDynamicInfo(dynamicInfo)` | Sends dynamic context text. | | `updateContext(options)` | Appends, replaces, or resets runtime context. | | `updateEmotion(stateOfMind)` | Sets or clears the character's state of mind. | | `updateSceneMetadata(items, options?)` | Sends descriptive scene items. | | `visionStatus(options?)` | Requests the vision buffer status. | | `visionTrigger(options?)` | Attaches buffered vision frames and optionally requests a response. | | `respondModeUpdate(options)` | Changes a respond mode for the session. | | `toggleTts(enabled)` | Turns speech output on or off. | | `toggleStt(enabled)` | Turns speech-to-text on or off. | | `uploadFile(file, options?)` | Sends a file over the LiveKit transport. | | `on(event, callback)` | Subscribes to a client event and returns an unsubscribe function. | | `off(event, callback)` | Removes a listener. | ### WebSocket audio playback When the session uses `transport: "websocket"`, the Pipecat transport plays the character's voice itself through Web Audio, so no extra code is needed. With the default LiveKit transport, render `AudioRenderer` or `ConvaiWidget` to hear the character. See [Build a custom UI in React](/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/react/custom-ui-and-advanced-usage.md). ### Example ```tsx import { useConvaiClient } from '@convai/web-sdk/react'; export function ConnectButton() { const client = useConvaiClient(); const connect = () => client.connect({ apiKey: 'YOUR_API_KEY', characterId: 'YOUR_CHARACTER_ID', }); return ( ); } ``` ### Related reference {% content-ref url="/pages/hoQvlTU9Xdyx4zRfPNAo" %} [ConvaiClient reference](/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/vanilla-typescript/convaiclient-core-api.md) {% endcontent-ref %} {% content-ref url="/pages/Ao6AKyD9m1Dhix32kGFx" %} [Configuration and type reference](/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/vanilla-typescript/best-practices-and-type-definitions.md) {% endcontent-ref %} {% content-ref url="/pages/i6rUAK1CuEI8BPWN76eT" %} [Web SDK event reference](/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/event-reference.md) {% endcontent-ref %} {% content-ref url="/pages/VVA0bI3FaMJjHAXp7Ce4" %} [ConvaiWidget component reference](/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/react/convaiwidget.md) {% endcontent-ref %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.convai.com/api-docs/plugins-and-integrations/web-plugins/convai-web-sdk/react/useconvaiclient-hook.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.