The chat surface accepts two credentials and behaves differently for each. A project API key acts as a server — full scopes, may act for any user in the project. A chat token acts as one client — its identity and scopes come from the signature and the request body cannot widen either.
See Chat authentication for what that means in practice.
Endpoints
POST /v1/chat/attachments/{attachmentId}/complete
Confirm the upload finished, making the attachment sendable
Credential Project API key or chat token
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
attachmentId | path | string | Yes |
GET /v1/chat/attachments/{attachmentId}/download-url
Short-lived signed download URL for an attachment you can see
Credential Project API key or chat token
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
attachmentId | path | string | Yes |
GET /v1/chat/conversations
List the project's conversations
Credential Project API key or chat token
No parameters.
POST /v1/chat/conversations
Create a conversation, optionally attached to an RTC room
Credential Project API key or chat token
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
name | body | string | Yes | 1–128 chars, pattern-checked — Unique within the project. Doubles as a human-readable handle for chat.connect(). |
type | body | ConversationType | No | Ignored when roomId is set — attaching an RTC room always produces a ROOM conversation. |
roomId | body | string | No | Attach this conversation to an existing RTC room, giving that video call a chat panel. |
retentionDays | body | number | No | 1–3650 — Overrides CHAT_RETENTION_DAYS for this conversation. |
members | body | ConversationMemberDto[] | No | array |
metadata | body | Record<string, unknown> | No | Arbitrary developer-owned JSON. Size-capped like message metadata. |
GET /v1/chat/conversations/{room}
Get one conversation by conv_ id, uuid, RTC room id, or name
Credential Project API key or chat token
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
room | path | string | Yes |
PATCH /v1/chat/conversations/{room}
Rename, archive, or re-configure retention for a conversation
Credential Project API key or chat token
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
room | path | string | Yes | |
name | body | string | No | 1–128 chars, pattern-checked |
status | body | ConversationStatus | No | |
retentionDays | body | number | No | 1–3650 |
metadata | body | Record<string, unknown> | No |
POST /v1/chat/conversations/{room}/attachments
Get a signed upload URL
Credential Project API key or chat token
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
room | path | string | Yes | |
filename | body | string | Yes | 1–255 chars |
mimeType | body | string | Yes | 0–255 chars, pattern-checked |
size | body | number | Yes | 1–1024 — Declared size in bytes, checked against STORAGE_MAX_ATTACHMENT_BYTES before a URL is issued. |
uploaderId | body | string | No | 0–128 chars — API-key callers only — ignored for browser chat tokens. |
metadata | body | Record<string, unknown> | No | Developer-owned JSON, e.g. image dimensions. |
GET /v1/chat/conversations/{room}/members
List active members
Credential Project API key or chat token
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
room | path | string | Yes |
POST /v1/chat/conversations/{room}/members
Add or re-activate a member
Credential Project API key or chat token
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
room | path | string | Yes | |
userId | body | string | Yes | 1–128 chars — Your own user identity string — Livqeno never owns end-user accounts. |
role | body | ChatMemberRole | No | |
metadata | body | Record<string, unknown> | No |
DELETE /v1/chat/conversations/{room}/members/{userId}
Remove a member (soft — their messages keep a resolvable author)
Credential Project API key or chat token
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
room | path | string | Yes | |
userId | path | string | Yes |
GET /v1/chat/conversations/{room}/messages
Message history, newest first, cursor-paginated
Credential Project API key or chat token
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
room | path | string | Yes | |
limit | query | number | No | 1–100 |
before | query | string | No | 0–256 chars — Opaque cursor from a previous page's nextCursor — walks backwards into history. Cursor-based, not offset-based, so pages stay stable while new messages arrive. |
after | query | string | No | 0–256 chars — Opaque cursor that walks forward toward newer messages. This is how a client catches up on what it missed while disconnected. |
threadRootId | query | string | No | 0–64 chars — Restrict to one thread, by the root message's public id. |
senderId | query | string | No | 0–128 chars — Restrict to one sender. |
includeDeleted | query | boolean | No | Include soft-deleted messages as tombstones (no text). Useful for moderation views. |
POST /v1/chat/conversations/{room}/messages
Send a message
Credential Project API key or chat token
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
room | path | string | Yes | |
text | body | string | No | Required for text messages. Length capped by CHAT_MAX_TEXT_LENGTH. |
type | body | string | No | "system" and "event" are server-only — a browser chat token cannot send them. |
replyTo | body | string | No | 0–64 chars — Public id of the message being replied to. Must be in the same conversation. |
clientMessageId | body | string | No | 0–128 chars — Idempotency key. Retrying a send with the same key returns the original message instead of creating a duplicate — which is what makes a reconnect-and-retry safe. |
attachmentId | body | string | No | 0–64 chars — Public id of an already-uploaded attachment (att_...). |
metadata | body | Record<string, unknown> | No | Developer-owned JSON. Capped by CHAT_MAX_METADATA_BYTES. |
senderId | body | string | No | 0–128 chars — API-key callers only: the user this message is attributed to. Ignored for browser chat tokens, which always send as the token subject. |
clientSentAt | body | number | No | 0–∞ — Client send timestamp (epoch ms), used only for latency measurement. Never trusted as createdAt — the server stamps that. |
GET /v1/chat/conversations/{room}/presence
Who is present right now. Ephemeral — never read from Postgres.
Credential Project API key or chat token
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
room | path | string | Yes |
GET /v1/chat/conversations/{room}/read-receipts
Every member's read position — what a "seen by" row is built from
Credential Project API key or chat token
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
room | path | string | Yes |
GET /v1/chat/conversations/{room}/read-state
Your read position and unread count for this conversation
Credential Project API key or chat token
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
room | path | string | Yes |
GET /v1/chat/conversations/{room}/typing
Who is typing right now
Credential Project API key or chat token
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
room | path | string | Yes |
DELETE /v1/chat/messages/{messageId}
Soft-delete a message; emits message.deleted
Credential Project API key or chat token
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
messageId | path | string | Yes |
GET /v1/chat/messages/{messageId}
Get one message
Credential Project API key or chat token
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
messageId | path | string | Yes |
PATCH /v1/chat/messages/{messageId}
Edit a message — sets editedAt and returns edited: true
Credential Project API key or chat token
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
messageId | path | string | Yes | |
text | body | string | No | |
metadata | body | Record<string, unknown> | No |
POST /v1/chat/messages/{messageId}/reactions
Add a reaction (idempotent per user+emoji)
Credential Project API key or chat token
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
messageId | path | string | Yes |
DELETE /v1/chat/messages/{messageId}/reactions/{emoji}
Remove a reaction
Credential Project API key or chat token
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
messageId | path | string | Yes | |
emoji | path | string | Yes |
POST /v1/chat/messages/{messageId}/read
Mark this message — and everything before it — as read
Credential Project API key or chat token
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
messageId | path | string | Yes |
GET /v1/chat/messages/{messageId}/thread
Every message in this message's thread, oldest first
Credential Project API key or chat token
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
messageId | path | string | Yes |
POST /v1/chat/tokens
Mint a short-lived chat token for one of your users
Credential Project API key or chat token
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
userId | body | string | Yes | 1–128 chars, pattern-checked — The end user this token speaks for. Everything they send is attributed to this identity — the browser can never override it. |
conversations | body | string[] | No | array — Conversation references (conv_ id, uuid, or name) this token may touch. Omit to allow every conversation the user is a member of. |
scopes | body | string[] | No | array — Narrows the token below what the user's role allows. Can only ever remove permissions — listing "chat:manage" here does not grant it. |
ttlSeconds | body | number | No | 60–21600 — Lifetime in seconds. Defaults to CHAT_TOKEN_DEFAULT_TTL_SECONDS, capped at CHAT_TOKEN_MAX_TTL_SECONDS. There is no non-expiring chat token. |
GET /v1/projects/{projectId}/chat/connections
Chat WebSocket sessions, newest first
Credential Dashboard session (JWT)
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
projectId | path | string | Yes |
GET /v1/projects/{projectId}/chat/conversations
Conversations with message counts and last activity
Credential Dashboard session (JWT)
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
projectId | path | string | Yes |
GET /v1/projects/{projectId}/chat/conversations/{conversationId}
One conversation — metadata only, no message content
Credential Dashboard session (JWT)
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
conversationId | path | string | Yes | |
projectId | path | string | Yes |
GET /v1/projects/{projectId}/chat/conversations/{conversationId}/members
Members of one conversation
Credential Dashboard session (JWT)
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
conversationId | path | string | Yes | |
projectId | path | string | Yes |
GET /v1/projects/{projectId}/chat/conversations/{conversationId}/messages
Message metadata for one conversation — id, sender, timing, status. Never content.
Credential Dashboard session (JWT)
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
conversationId | path | string | Yes | |
projectId | path | string | Yes |
GET /v1/projects/{projectId}/chat/conversations/{conversationId}/presence
Who is present in one conversation right now (read from Redis, not Postgres)
Credential Dashboard session (JWT)
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
conversationId | path | string | Yes | |
projectId | path | string | Yes |
GET /v1/projects/{projectId}/chat/overview
Chat activity for this project — real counters, never estimates
Credential Dashboard session (JWT)
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
projectId | path | string | Yes |
Next steps
- Conventions — base path, error envelope, request ids, pagination.
- Errors — every code this API can return.
- All endpoints — the whole surface on one page.