Conversations API

The conversations API manages the agent's web-chat interface. Each conversation has its own room in the runtime's memory system, allowing independent message histories. The API supports both streaming (SSE) and synchronous message delivery.

Endpoints

GET /api/conversations

List all conversations, sorted by most recently updated first.

Response

{
  "conversations": [
    {
      "id": "uuid",
      "title": "Morning Chat",
      "roomId": "uuid",
      "createdAt": "2025-06-01T10:00:00.000Z",
      "updatedAt": "2025-06-01T12:30:00.000Z"
    }
  ]
}

POST /api/conversations

Create a new conversation with its own room.

Request Body

Response

{
  "conversation": {
    "id": "uuid",
    "title": "New Chat",
    "roomId": "uuid",
    "createdAt": "2025-06-01T12:00:00.000Z",
    "updatedAt": "2025-06-01T12:00:00.000Z"
  }
}

GET /api/conversations/:id/messages

Retrieve up to 200 messages for a conversation, sorted oldest first. Messages with empty text content (such as action-log memories) are automatically filtered out.

Response

{
  "messages": [
    {
      "id": "uuid",
      "role": "user",
      "text": "Hello!",
      "timestamp": 1718000000000
    },
    {
      "id": "uuid",
      "role": "assistant",
      "text": "Hey there! How can I help?",
      "timestamp": 1718000001000
    },
    {
      "id": "uuid",
      "role": "user",
      "text": "What's going on in Discord?",
      "timestamp": 1718000002000,
      "source": "discord",
      "from": "Alice",
      "fromUserName": "alice#1234",
      "avatarUrl": "https://cdn.discordapp.com/avatars/..."
    }
  ]
}

Errors

POST /api/conversations/:id/messages

Send a message and get the agent's response synchronously (non-streaming).

Request Body

Response

{
  "text": "Here's what I think...",
  "agentName": "Eliza"
}

Errors

POST /api/conversations/:id/messages/stream

Send a message and receive the agent's response via Server-Sent Events (SSE). Each token is streamed as it is generated, followed by a final done event.

Request Body

Same as POST /api/conversations/:id/messages.

SSE Events

Token events (append semantics — each text chunk extends the reply):

data: {"type":"token","text":"Here's"}
data: {"type":"token","text":" what"}
data: {"type":"token","text":" I think..."}

Snapshot events (replace semantics — used when action callbacks update the reply in-place):

data: {"type":"token","fullText":"Here's what I think...\n\nSearching for track..."}

When a fullText field is present, it is authoritative and the client should replace the entire assistant message text rather than appending.

Final event:

data: {"type":"done","fullText":"Here's what I think...","agentName":"Eliza"}

The conversation title is auto-generated in the background if it is still "New Chat", and a conversation-updated WebSocket event is broadcast. If AI title generation fails, the title falls back to the first five words of the user's message.

Error recovery

If the model provider fails after tokens have already been streamed to the client, the server preserves the streamed text. The done event's fullText contains the text that was already delivered rather than a generic error message. This prevents the client from losing a partially complete reply.

If the failure occurs before any text is streamed, the done event's fullText contains a fallback error description (e.g. provider connectivity issue) so the user still receives feedback.

In both cases, an error SSE event may also be emitted if the reply cannot be persisted:

data: {"type":"error","message":"Failed to persist message"}

POST /api/conversations/:id/messages/truncate

Truncate (delete) messages in a conversation starting from a specific message. By default, deletes messages after the specified message; set inclusive to also delete the specified message itself.

Request Body

Response

{
  "ok": true,
  "deletedCount": 5
}

Errors

POST /api/conversations/:id/greeting

Generate a greeting message for a new conversation. Picks a random postExample from the agent's character definition — no model call, no latency. The greeting is stored as an agent message for persistence.

Response

{
  "text": "gm. ready to go viral today or what.",
  "agentName": "Eliza",
  "generated": true
}

PATCH /api/conversations/:id

Update conversation metadata: rename, auto-generate a title, or update structured metadata.

Request Body

Response

{
  "conversation": {
    "id": "uuid",
    "title": "Updated Title",
    "roomId": "uuid",
    "createdAt": "2025-06-01T10:00:00.000Z",
    "updatedAt": "2025-06-01T14:00:00.000Z"
  }
}

Errors

POST /api/conversations/:id/messages/truncate

Truncate messages in a conversation starting from a given message ID. Useful for "edit and regenerate" flows where the user wants to discard messages from a certain point onward.

Request Body

Response

{
  "ok": true,
  "deletedCount": 3
}

Errors

DELETE /api/conversations/:id

Delete a conversation. Messages remain in the runtime memory but the conversation metadata is removed.

Response

{
  "ok": true
}

POST /api/conversations/cleanup-empty

Delete all conversations that have no messages. Optionally keep a specific conversation.

Request Body

Response

{
  "deleted": ["uuid1", "uuid2"]
}

POST /api/conversations/cleanup-empty

Delete all conversations that have no user messages. Useful for clearing auto-created conversations that were never used. Optionally keep a specific conversation.

Request Body

Response

{
  "deleted": ["uuid-1", "uuid-2"]
}

Common Error Codes