Messaging

Messaging endpoints are read-only in Public API v1. They expose chat and message DTOs for integrations that need conversation context, without unread-state internals, push tokens, participant auth fields, raw media URLs, moderation state, or delivery provider payloads. The authenticated company is always derived from the Bearer token. Requests must not include companyId.

Scopes

Scope	Allows
`messages:read`	List client chat threads and read sanitized message DTOs.

List client chats

GET /public/v1/clients/{clientId}/chats?page=1&limit=50
Authorization: Bearer <access_token>

Required scope: messages:read Validation:

Parameter	Type	Required	Rule
`clientId`	ObjectId string	yes	Client must belong to the authenticated company.
`page`	integer	no	Minimum `1`.
`limit`	integer	no	Default `50`, maximum `100`.

Response fields:

Field	Type	Nullable	Description
`data.page`	integer	no	Current page.
`data.limit`	integer	no	Page size after server cap.
`data.total`	integer	no	Total chat threads for this client.
`data.totalPages`	integer	no	Total pages, minimum `1`.
`data.hasNextPage`	boolean	no	Whether another page exists.
`data.hasPrevPage`	boolean	no	Whether a previous page exists.
`data.chats[].chatId`	string	no	Chat thread ID.
`data.chats[].createdAt`	string	yes	Chat creation timestamp.
`data.chats[].participants[]`	array	no	Public participant summaries.
`data.chats[].participants[].userId`	string	no	Participant user ID.
`data.chats[].participants[].role`	string	no	Participant role.
`data.chats[].participants[].name`	string	no	Display name.

Not exposed: participant email, device tokens, unread counters, muted states, deletion markers, role permissions, or raw participant documents.

List chat messages

GET /public/v1/clients/{clientId}/chats/{chatId}/messages?page=1&limit=50
Authorization: Bearer <access_token>

Required scope: messages:read Validation:

Parameter	Type	Required	Rule
`clientId`	ObjectId string	yes	Client must belong to the authenticated company.
`chatId`	ObjectId string	yes	Chat must include the client and belong to the authenticated company.
`page`	integer	no	Minimum `1`.
`limit`	integer	no	Default `50`, maximum `100`.

Response fields:

Field	Type	Nullable	Description
`data.page`	integer	no	Current page.
`data.limit`	integer	no	Page size after server cap.
`data.total`	integer	no	Total matching messages.
`data.totalPages`	integer	no	Total pages, minimum `1`.
`data.hasNextPage`	boolean	no	Whether another page exists.
`data.hasPrevPage`	boolean	no	Whether a previous page exists.
`data.messages[].messageId`	string	no	Message ID.
`data.messages[].senderRole`	string	no	Public sender role.
`data.messages[].type`	string	no	Message type.
`data.messages[].text`	string	no	Text body when the message is text-based.
`data.messages[].hasMedia`	boolean	no	Whether media is attached.
`data.messages[].fileName`	string	no	Safe file name when stored.
`data.messages[].sentAt`	string	yes	Sent timestamp.
`data.messages[].editedAt`	string	yes	Last edit timestamp.

Not exposed: raw attachment URLs, storage keys, upload metadata, push delivery state, read receipts, internal moderation fields, deleted-message audit data, provider payloads, or staff-only support context.

Rate limits

Messaging endpoints use the standard Public API client rate limit: 10 requests per second per OAuth client. Responses include the standard RateLimit-* and X-RateLimit-* headers documented in Contracts.

Start here

Public API guides

Access Devices

Scopes

List client chats

List chat messages

Rate limits

​Scopes

​List client chats

​List chat messages

​Rate limits

Scopes

List client chats

List chat messages

Rate limits