Chat

Send messages to NPCs and receive AI-generated responses within a session.

Overview

The Chat API handles real-time conversations with published personas. Initialize a session, send messages, and receive NPC responses along with state transition data and scoring metadata.

ℹNote

Web chat endpoints require a signed-in user. Players must create an account or sign in before starting a conversation. Each player gets their own independent session.

Initialize Session

POST /api/v1/chat/{persona_id}/init-session

Starts a new chat session with the specified persona. Returns the NPC's opening message and a session ID for subsequent requests.

Query Parameters

Parameter	Type	Required	Description
`machine_id`	string	No	Target a specific state machine. Defaults to the persona's primary machine.

Request Body

Field	Type	Required	Description
`user_session_id`	string	Yes	Unique identifier for the player's session
`player_name`	string	Yes	The player's display name, used in NPC responses
`player_gender`	string	Yes	One of `female`, `male`, or `non-binary`

Response

Field	Type	Description
`message`	string	The NPC's opening message
`session_id`	string	Server-assigned session identifier
`user_session_id`	string	Echoed player session identifier
`persona_name`	string	Name of the persona
`persona_description`	string \| null	Description of the persona
`player_name`	string	Echoed player name
`player_gender`	string	Echoed player gender
`machine_id`	string	The active state machine ID

Send Message

POST /api/v1/chat/{persona_id}/message

Sends a player message to the NPC and returns the response along with state machine metadata including current state, score, and outcome information.

Query Parameters

Parameter	Type	Required	Description
`machine_id`	string	No	Target a specific state machine

Request Body

Field	Type	Required	Description
`message`	string	Yes	The player's message text
`user_session_id`	string	Yes	Session identifier from init

Response

Field	Type	Description
`message`	string	The NPC's response text
`current_state`	string	The current state machine state key
`score`	number	Current cumulative score for the session
`outcome`	string \| null	Outcome label if a terminal state was reached
`decision`	string \| null	Transition decision made by the AI
`follow_up`	boolean	Whether the NPC expects a follow-up message
`redirect_count`	number \| null	Number of redirects used in the current state
`session_id`	string	The active session identifier
`scoring_mode`	string	The scoring mode for this persona
`machine_completed`	boolean	Whether the state machine has reached a terminal state
`unlocked_machines`	array	List of newly unlocked machine IDs, if any

Get Chat History

GET /api/v1/chat/{persona_id}/history

Retrieves the full message history for a session.

Query Parameters

Parameter	Type	Required	Description
`user_session_id`	string	Yes	The session to retrieve history for
`machine_id`	string	No	Filter history to a specific state machine

Reset Session

POST /api/v1/chat/{persona_id}/reset

Resets a chat session, clearing all history and returning the state machine to its initial state.

Query Parameters

Parameter	Type	Required	Description
`user_session_id`	string	Yes	The session to reset
`machine_id`	string	No	Reset only a specific state machine

Example: Full Conversation Flow

Here's a complete example of initializing a session and sending a message.

1. Initialize the session

curl -X POST https://api.foilengine.io/api/v1/chat/abc123/init-session \
  -H "Content-Type: application/json" \
  -d '{
    "user_session_id": "player-session-001",
    "player_name": "Alex",
    "player_gender": "non-binary"
  }'

Response:

{
  "message": "Well, well... another traveler. What brings you to the Hollow Market, Alex?",
  "session_id": "sess_7f8a9b2c",
  "player_name": "Alex",
  "player_gender": "non-binary",
  "machine_id": "machine_main"
}

2. Send a message

curl -X POST https://api.foilengine.io/api/v1/chat/abc123/message \
  -H "Content-Type: application/json" \
  -d '{
    "message": "I heard you have something rare for sale.",
    "user_session_id": "player-session-001"
  }'

Response:

{
  "message": "Rare? Everything here is rare, friend. But the real question is — can you afford it? Not everything costs gold.",
  "current_state": "negotiation",
  "score": 1,
  "outcome": null,
  "decision": "pass",
  "follow_up": true,
  "session_id": "sess_7f8a9b2c",
  "scoring_mode": "scoring",
  "machine_completed": false,
  "unlocked_machines": []
}

Previous← Authentication NextPersonas API →