Group Chat
Several characters sharing one conversation
Experimental
Group chat is currently an experimental feature. Its request and response shape may change.
Send multiple IDs in the characterIds array to run a group scene using the /chat endpoint. The characters share a single conversation history, and the system automatically determines the speaker order.
{
"characterIds": [
"cmrkiw4f100017k7sfnicq08e",
"cmrkiwj2k00037k7sxnpvs9p3"
],
"message": "What do you two make of the storm rolling in?"
}The response contains an entry for each speaker in order:
{
"sessionId": "cmdruuvyr0000jr04lteh35te",
"messages": [
{ "characterId": "cmrkiw4f...", "name": "Aria", "lines": [{ "text": "Nothing good.", "emotion": "CONCERNED" }], "actions": [], "flowState": "" },
{ "characterId": "cmrkiwj2k...", "name": "Bram", "lines": [{ "text": "You always say that.", "emotion": "AMUSED" }], "actions": [], "flowState": "" }
],
"metadata": []
}Plan requirement
A group chat with two or more characters requires a Pro or Team plan. Using a single character behaves like a standard single-character chat and is supported on all plans.
| You send | What happens |
|---|---|
message | The system determines the response order, up to maxTurns responses. |
message + speakerCharacterId | Forces the specified character to respond. |
No message | Triggers an ambient turn where characters talk to each other without player input. |
The maxTurns parameter caps the number of responses returned in a single turn. The default and maximum value is 5.
{
"characterIds": ["cmrkiw4f100017k7sfnicq08e", "cmrkiwj2k00037k7sxnpvs9p3"],
"sessionId": "cmdruuvyr0000jr04lteh35te",
"maxTurns": 3
}Dynamic cast
The characterIds array defines the active cast for each turn. Modifying this array updates the scene state:
- Adding a character: The character joins the conversation and is recognized by other characters in the session.
- Removing a character: The character leaves the conversation. Other characters will acknowledge their departure and stop addressing them.
No separate join or leave endpoints are required. Provide the same sessionId to maintain the conversation context.
Late joiner context history
A character that joins a session in progress only receives the conversation history starting from the turn they joined. They do not have access to messages sent prior to their arrival. Characters present from the beginning retain full history.
Player personas
Use the playAs parameter to map the player to a specific character. Other characters will address the player by that character's name and recognize their persona.
{
"characterIds": ["cmrkiw4f100017k7sfnicq08e"],
"playAs": "cmrkiwj2k00037k7sxnpvs9p3",
"message": "Well met. I have travelled far to find you."
}The persona is persisted on the session. Send "playAs": null to clear it. The character ID must belong to your team and cannot be included in characterIds.
If no persona is set, the player defaults to being addressed as Player.