Charisma.ai chat component for React.
pnpm i @charisma-ai/react
This package is a react wrapper for the Charisma AI Javascript SDK. It provides a simple way to embed a chat in your React app along with accessing conversation data. It also handles audio playback and speech to text.
After you have signed up at Charisma.ai, and logged in, make sure you have a valid licence (a free trial licence is available).
Then, on your My Stories page, click to Create a new game story.
In your story add a subplot, and a few character nodes, and player nodes.
If using a Pro story, you will need the startGraphReferenceId which is a uuid. From the story editor left navigation bar, click ... next to your subplot name, select `Edit details, and copy the reference id. If you are using a Web comic story, the story will start at the first scene automatically.
On the story overview page scroll down to Play API Access and generate and/or copy the API key. This will enable access to start playthroughs of your story.
At the top of the navbar on the left, underneath the title, your version number, or 'draft' will be displayed. You can use -1 for your most recent draft, undefined for the promoted (usually most recent) version release, or the version number for an exact version of your story.
Finally the story ID can be found in the url, eg. https://charisma.ai/stories/12345 gives you ID 12345.
From the root of this project, run pnpm install and pnpm build to install dependencies in node_modules, and create the dist directory with the compiled package respectively.
Navigate to ./demos/chat and run pnpm install to install the demos dependencies. You can now start the demo app which has a form to input your story parameters. You can launch the demo app by running pnpm run dev.
In your browser, go to localhost:3000. Once the page loads, enter your conversation parameters, and click the Submit button. This opens the chat, where you can click start, and would expect to see the first character nodes from your story start to appear on the page.
The best way to get started with this SDK is to use the demo project located in demos/chat.
The <Playthrough> component handles the connection to charisma.ai. This component is a context provider so anything inside has access to the usePlaythroughContext hook.
| Prop | Type | Description |
|---|---|---|
playthroughToken |
string or undefined | If your story is not published, this is required. |
autoconnect |
boolean | If true, the component will automatically connect to charisma.ai |
onConnectionStatus |
(connectionStatus: ConnectionStatus) => void |
If provided, this function will be called when the connection status changes. |
onError |
(error: any) => void |
If provided, this function will be called when an error occurs. |
onProblem |
(problem: { code: string, error: string}) => void |
If provided, this function will be called when a problem occurs. |
Hook that provides access to the Playthrough context.
const { connectionStatus, playthrough, playthroughToken, playerSessionId } = usePlaythroughContext();
The <Conversation> component handles the conversation. This component is a context provider so anything inside has access to the useConversationContext hook.
| Prop | Type | Description |
|---|---|---|
conversationUuid |
string or undefined | References the current conversation. This is returned from createConversation function. |
onMessage |
`(event: MessageEvent) => Promise | void` |
onStartTyping |
(event: StartTypingEvent) => void |
If provided, this function will be called when the character starts typing. |
onStopTyping |
(event: StopTypingEvent) => void |
If provided, this function will be called when the character stops typing. |
onProblem |
(event: ProblemEvent) => void |
If provided, this function will be called when a problem occurs. |
onStart |
(event: StartEvent) => void |
If provided, this function will be called when the conversation starts. |
onReply |
(event: ReplyEvent) => void |
If provided, this function will be called when a reply is received from the player. |
onResume |
() => void |
If provided, this function will be called when the conversation resumes. |
onTap |
() => void |
If provided, this function will be called when the player taps to continue the conversation. |
onAction |
(event: ActionEvent) => void |
If provided, this function will be called when an action node is executed. |
initialState |
ConversationState | If provided, this will be used as the initial state of the conversation. |
onStateChange |
(newState: ConversationState) => void |
If provided, this function will be called when the conversation state changes. |
shouldResumeOnConnect |
boolean | If true, when the conversation reconnects from a disconnection event, it will resume automatically. |
shouldStartOnConnect |
boolean | If true, when the conversation reconnects from a disconnection event, it will start from the beginning automatically. |
speechConfig |
SpeechConfig | Defines the parameters for character speech. Required if you want character speech audio. |
Hook that provides access to the Conversation context.
const {isRestarting, isTyping, messages, mode, start, reply, tap, action, resume, restart} = useConversationContext()
| Value | Type | Description |
|---|---|---|
isRestarting |
boolean | Is true when restart is called. |
isTyping |
boolean | Is true when the character is typing. |
messages |
StoredMessage[] | Contains all the messages for the current conversation. |
mode |
ChatMode | Defines the current chat mode. |
start |
(event?: StartEvent) => void |
Starts the conversation |
reply |
(event: ReplyEvent) => void |
Sends a reply to the conversation from the player. |
tap |
() => void |
Taps to continue the conversation. |
action |
(event: ActionEvent) => void |
Executes an action node. |
resume |
() => void |
Resumes the conversation. |
restart |
(eventId: string) => Promise<void> |
Restarts the conversation from the specified event. |
Provides audio. This component is a context provider and must wrap <Playthrough> and <Conversation> on order to be setup correctly. See the chat demo for a suggested structure.
<AudioManagerProvider options={options}>
...
</AudioManagerProvider>
| Option | Type | Default | Description |
|---|---|---|---|
duckVolumeLevel |
number |
0 | Volume level when ducking (0 to 1) |
normalVolumeLevel |
number |
1 | Regular volume level (0 to 1) |
sttService |
"charisma/deepgram" or "browser" |
"charisma/deepgram" |
Speech-to-text service to use (see below). |
streamTimeslice |
number |
100 | The number of milliseconds to record into each Blob. See https://developer.mozilla.org/en-US/docs/Web/API/MediaRecorder/start#timeslice |
handleError |
(error: string) => void |
console.error(error) |
Callback to handle errors. |
handleDisconnect |
(message: string) => void |
console.error(message) |
Callback to handle when the transcription service disconnects. |
handleConnect |
(message: string) => void |
console.log(message) |
Callback to handle when the transcription service connects. |
Hook that provides access to the AudioManagerProvider context.
| Value | Type | Description |
|---|---|---|
isListening |
boolean | Is true when microphone is listening for STT. |
isBrowserSupported |
boolean | Is true when the current browser supports local STT. |
initialise |
() => void |
Initialises the AudioManager. This must be called via a user interaction, such as a button click. See the chat demo for an example. |
transcript |
string | The current transcript from STT. |
recordingStatus |
RecordingStatus | The current recording status. Can be "OFF", "STARTING" or "RECORDING". |
startListening |
() => void |
Starts listening for STT. |
stopListening |
() => void |
Stops listening for STT. |
connect |
(token: string, playerSessionId: string) => void |
Connects to the AudioManager. See StartButton.tsx in the chat demo for an example. |
resetTimeout |
(timeout: number) => void |
Resets the STT timeout before the microphone automatically stops listening for STT. |
playOutput |
(audio: ArrayBuffer, playOptions: AudioOutputsServicePlayOptions) => Promise<void> or undefined |
Plays character speech from a MessageEvent. |
setOutputVolume |
(volume: number) => void |
Sets the volume of character speech. Must be between 0 and 1. |
playMediaAudio |
(audioTracks: AudioTrack[]) => void |
Plays media audio from a MessageEvent. This is used for playing background music. |
setMediaVolume |
(volume: number) => void |
Sets the volume of media audio. Must be between 0 and 1. |
toggleMediaMute |
() => void |
Toggles the mute state of media audio. |
stopAllMedia |
() => void |
Stops all media audio. |
Use this to set up a new playthrough.
-
storyId(number): Theidof the story that you want to create a new playthrough for. The story must be published, unless a Charisma.ai user token has been passed and the user matches the owner of the story. -
version(number, optional): Theversionof the story that you want to create a new playthrough for. If omitted, it will default to the most recent published version. To get the draft version of a story, pass-1and anapiKey. -
apiKey(string, optional): To access draft, test or unpublished versions of your story, pass anapiKey. The API key can be found on the story overview page. -
languageCode(string, optional): To play a story in a language other than English (en, the default), pass a BCP-47languageCode. For example, to play in Italian, useit.
Returns a promise that resolves with the token.
const { token } = await createPlaythroughToken({
storyId: 12,
version: 4,
apiKey: '...',
languageCode: 'en',
});A playthrough can have many simultaneous conversations. In order to start interacting, a conversation needs to be created, which can then be joined.
-
playthroughToken(string): The token generated withcreatePlaythroughToken.
Note: The @charisma-ai/sdk package is a peer dependency of @charisma-ai/react all of its exports are re-exported in this package. View the SDK documentation for more information.
