Charisma for React

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.

Setup in Charisma

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.

Try the Demo App

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.

SDK Documentation

The best way to get started with this SDK is to use the demo project located in demos/chat.

Playthrough

The <Playthrough> component handles the connection to charisma.ai. This component is a context provider so anything inside has access to the usePlaythroughContext hook.

Props

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.

usePlaythroughContext

Hook that provides access to the Playthrough context.

const { connectionStatus, playthrough, playthroughToken, playerSessionId } = usePlaythroughContext();

Conversation

The <Conversation> component handles the conversation. This component is a context provider so anything inside has access to the useConversationContext hook.

Props

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.

useConversationContext

Hook that provides access to the Conversation context.

const {isRestarting, isTyping, messages, mode, start, reply, tap, action, resume, restart} = useConversationContext()

Values

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.

AudioManagerProvider

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>

Options

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.

useAudioManager

Hook that provides access to the AudioManagerProvider context.

Values

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.

createPlaythroughToken

Use this to set up a new playthrough.

• storyId (number): The id of 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): The version of 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 -1 and an apiKey.
• apiKey (string, optional): To access draft, test or unpublished versions of your story, pass an apiKey. 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-47 languageCode. For example, to play in Italian, use it.

Returns a promise that resolves with the token.

const { token } = await createPlaythroughToken({
  storyId: 12,
  version: 4,
  apiKey: '...',
  languageCode: 'en',
});

createConversation

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 with createPlaythroughToken.

---

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.