SDK Integration
Core Concepts

Core Concepts


A playthrough represents a particular instance of playing a story. It's a wrapper around all the data that is local to each playthrough, such as the characters' emotions, memories, and chat history. Usually, each individual player will create their own playthrough, but it's possible to share the same playthrough between players if you'd like multiple players to share in the same instance of the experience.

A player can play through the story an unlimited number of times within the same playthrough. Each playthrough has a unique ID.

A playthrough is permanently scoped to a version of a story. For example, if you create a playthrough of your draft story version, it will not be possible to then change the referenced story version to a published story version later down the track. You will instead need to create a new playthrough.

Connecting to a playthrough sets up a websocket connection between the client and Charisma, and most interactions are sent over this websocket.

Playthrough Token

A playthrough token is a way to access a playthrough. Once a playthrough token is generated, it can be saved by the client in a storage mechanism and then used to authenticate to the Charisma Play API. Playthrough tokens currently expire after 20 years.


You can have multiple simultaneous conversations happening within a single playthrough. This is useful, for example, if you have an IM-style application like Messenger, where you have multiple different "threads" of conversations with multiple characters at once. However, typically, there's only a single conversation in a playthrough.