Products & Surfaces

Embedding the chat widget (React)

For a React application, copy the React embed code from the Ship tab on your chat Surface. The generated component initializes the chat widget and destroys it when React unmounts the component.

Get the embed code

To copy the React embed code, follow these steps:

  1. Open your Product and select the chat Surface.
  2. On the Ship tab, select React.
  3. Select or create a Client Token.
  4. Copy the generated React code.

The generated code imports @runtypelabs/persona and initializes the widget inside useEffect. It calls handle.destroy() when React unmounts the component.

Install the package

Install the Persona package with the following command:

Install Persona
$npm install @runtypelabs/persona

Use the generated component

Paste the generated code into a React component. The generated component:

  • Initializes the widget with your client token and theme.
  • Mounts the widget to the document body.
  • Calls handle.destroy() when React unmounts the component.

The Ship tab generates a complete React component. Customize the component for your application after you copy it.

Use client tokens

Use a client token instead of an API key in a chat widget. Client tokens use the ct_live_ or ct_test_ prefix and are safe to expose in client-side code. Create and manage client tokens in the Auth tab of your chat Surface.

Build a custom voice interface

For a voice interface built from your own React components, use useVoiceClient from @runtypelabs/voice/react. It manages microphone capture, playback, transcripts, and the agent’s configured interruption mode.

1import { useVoiceClient } from '@runtypelabs/voice/react'
2
3function VoiceCall({ agentId, clientToken }) {
4  const voice = useVoiceClient({ agentId, clientToken })
5  return (
6    <div>
7      <p role="status">{voice.error ?? voice.status}</p>
8      <button onClick={() => void voice.startCall()}>Start call</button>
9      <button onClick={voice.endCall}>End call</button>
10      {voice.canCancel && <button onClick={voice.cancelResponse}>Stop response</button>}
11    </div>
12  )
13}

Install with pnpm add @runtypelabs/voice. Use a browser client token authorized for the agent. Start calls from a user click in a secure browser context. The hook releases the microphone on unmount. See the voice package guide for plain JavaScript usage, staging configuration, and the Persona adapter’s widget release prerequisite.

Next steps

Choose a guide based on your next task: