Inbox API - Eliza — ContextQMD

The inbox API provides a read-only, time-ordered view of messages from every connector channel the agent participates in — iMessage, Telegram, Discord, WhatsApp, WeChat, Slack, Signal, and SMS — merged into a single feed. Dashboard web-chat messages are excluded since they are already accessible via the conversations API.

Endpoints

Method	Path	Description
GET	`/api/inbox/messages`	List recent messages across all connector channels
GET	`/api/inbox/chats`	List connector chat threads (one row per room)
GET	`/api/inbox/sources`	List distinct connector source tags

GET /api/inbox/messages

List the most recent messages across all connector channels in a time-ordered feed (newest first).

Query parameters

Parameter	Type	Required	Default	Description
`limit`	integer	No	100	Maximum messages to return (hard cap 500)
`sources`	string	No	All inbox sources	Comma-separated source filter (e.g. `discord,telegram`)
`roomId`	string	No	—	Scope to a single room ID for thread-level views

Response

json

{
  "messages": [
    {
      "id": "uuid",
      "role": "user",
      "text": "Hey, check this out!",
      "timestamp": 1718000000000,
      "source": "discord",
      "roomId": "room-uuid",
      "from": "Alice",
      "fromUserName": "alice#1234",
      "avatarUrl": "https://cdn.discordapp.com/avatars/..."
    }
  ],
  "count": 1
}

Field	Type	Description
`messages[].id`	string	Memory UUID
`messages[].role`	string	`user` or `assistant`
`messages[].text`	string	Message text content
`messages[].timestamp`	number	Unix timestamp (ms) when the message was created
`messages[].source`	string	Connector source tag (e.g. `imessage`, `telegram`, `discord`)
`messages[].roomId`	string	External chat room ID for threading
`messages[].from`	string\|undefined	Best-effort display name of the sender entity
`messages[].fromUserName`	string\|undefined	Username or handle of the sender (e.g. Discord username)
`messages[].avatarUrl`	string\|undefined	Sender avatar URL when the connector provides one

For Discord messages, from, fromUserName, and avatarUrl are enriched from the live Discord user profile when available.

GET /api/inbox/chats

List connector chat threads — one row per external chat room. Used by the sidebar to display a chat list alongside dashboard conversations.

Query parameters

Parameter	Type	Required	Default	Description
`sources`	string	No	All inbox sources	Comma-separated source filter

Response

json

{
  "chats": [
    {
      "id": "room-uuid",
      "source": "discord",
      "title": "#general",
      "lastMessageText": "Hey, check this out!",
      "lastMessageAt": 1718000000000,
      "messageCount": 42
    }
  ],
  "count": 1
}

Field	Type	Description
`chats[].id`	string	Room ID (stable across polls, used as selection key)
`chats[].source`	string	Connector source tag for badge rendering
`chats[].title`	string	Display title — channel name, contact name for DMs, or fallback `"<source> chat"`
`chats[].lastMessageText`	string	Preview of the most recent message (truncated to 140 characters)
`chats[].lastMessageAt`	number	Epoch ms timestamp of the most recent message
`chats[].messageCount`	number	Total messages in this room at scan time

Chat titles are resolved in the following priority order:

Live Discord channel name (fetched from the Discord client for Discord sources)
Stored room name (set by the connector plugin when the room was created)
Latest sender name (for DM rooms)
Fallback: "<source> chat"

GET /api/inbox/sources

List the distinct set of connector source tags the agent currently has messages for. Use this to build dynamic source filter chips in the UI without hardcoding connector names.

Response

json

{
  "sources": ["imessage", "telegram", "discord", "whatsapp"]
}

Field	Type	Description
`sources`	string[]	Array of distinct source tags present in agent message history

Supported sources

The inbox includes messages from these connector sources by default:

Source tag	Platform
`imessage`	iMessage
`telegram`	Telegram
`discord`	Discord
`gmail`	Gmail
`whatsapp`	WhatsApp
`wechat`	WeChat
`slack`	Slack
`signal`	Signal
`sms`	SMS

Messages from client_chat (dashboard web chat) and internal sources (system events, knowledge ingestion) are excluded from the inbox feed.

Common error codes

Status	Code	Description
500	`INTERNAL_ERROR`	Failed to load inbox data