Conversations

Find conversations, mark them as read, and manage typing indicators.

5 endpoints · API 0.5.1-rc.3

Read the usage guide ↗

Page through conversations

#

Operation ID: listConversations

relayToken↗

GET/v1/conversations

Newest messages sort first. Cursor values are opaque and bound to this exact filter and database.

Request

Query parameters

limitintegerOptional

Maximum number of items in this page.

Default: 20

Validation rules

Minimum

1

Maximum

200

cursorstringOptional

Opaque next_cursor from the previous page, bound to the route, query, and database.

Validation rules

Minimum length

1

Pattern

^[^\p{Cc}\p{Cf}]+$

unread_onlystringOptional

Return only conversations with unread messages. Accepts true, false, 1, or 0. Word spellings are case-insensitive.

Default: "false"

Validation rules

Pattern

^([Tt][Rr][Uu][Ee]|[Ff][Aa][Ll][Ss][Ee]|[01])$

participantstringOptional

Exact normalized phone number or email address. Email matching is case-insensitive.

Responses

200A page of conversations.

Content type application/json

PaginatedResponseOfConversation ↗

400, 401, 422, 500, 503Error responses

400

Malformed JSON, query parameter, cursor, destination selection, or resource identifier.

401

Missing or invalid bearer token.

422

A destination, payload field, filename, or media file failed validation.

500

The request failed.

503

The database, sender, Messages access, or request store is unavailable.

Content type application/json

APIError ↗

Headers on every response

X-Request-IDstringRequired

Request correlation identifier.

Read one conversation

#

Operation ID: getConversation

relayToken↗

GET/v1/conversations/{conversation_id}

Request

Path parameters

conversation_idstringRequired

Percent-encoded public resource identifier, not a database row ID.

Validation rules

Minimum length

1

Pattern

^[^\p{Cc}\p{Cf}]+$

Responses

200The conversation.

Content type application/json

Conversation ↗

400, 401, 404, 500, 503Error responses

400

Malformed JSON, query parameter, cursor, destination selection, or resource identifier.

401

Missing or invalid bearer token.

404

The requested resource was not found.

500

The request failed.

503

The database, sender, Messages access, or request store is unavailable.

Content type application/json

APIError ↗

Headers on every response

X-Request-IDstringRequired

Request correlation identifier.

Mark a conversation as read

#

Operation ID: markConversationRead

relayToken↗

PUT/v1/conversations/{conversation_id}/read

No request body. Success follows confirmation in chat.db. Stops active typing before the native action. This confirms local state, not remote read receipt delivery. A 502 result requires a refetch before retrying.

Request

Path parameters

conversation_idstringRequired

Percent-encoded public resource identifier, not a database row ID.

Validation rules

Minimum length

1

Pattern

^[^\p{Cc}\p{Cf}]+$

Responses

200The applied or unchanged read state.

Content type application/json

ConversationReadResponse ↗

400, 401, 404, 409, 500, 501, 502, 503Error responses

400

Malformed JSON, query parameter, cursor, destination selection, or resource identifier.

401

Missing or invalid bearer token.

404

The requested resource was not found.

409

A conflicting request, ambiguous conversation, or protected typing draft prevents the operation.

500

The request failed.

501

The sender or platform does not support the requested capability.

502

The native operation result is uncertain. Refetch its resource before retrying.

503

The database, sender, Messages access, or request store is unavailable.

Content type application/json

APIError ↗

Headers on every response

X-Request-IDstringRequired

Request correlation identifier.

Start or refresh a typing lease

#

Operation ID: startTyping

relayToken↗

PUT/v1/conversations/{conversation_id}/typing

No request body. The local lease lasts five seconds. Refresh about every three seconds. Starting a lease stops the previous conversation's lease. A protected draft returns 409 without changing it. Local active status does not prove remote delivery of an indicator.

Request

Path parameters

conversation_idstringRequired

Percent-encoded public resource identifier, not a database row ID.

Validation rules

Minimum length

1

Pattern

^[^\p{Cc}\p{Cf}]+$

Responses

200The active typing lease.

Content type application/json

ConversationTypingResponse ↗

400, 401, 404, 409, 500, 501, 502, 503Error responses

400

Malformed JSON, query parameter, cursor, destination selection, or resource identifier.

401

Missing or invalid bearer token.

404

The requested resource was not found.

409

A conflicting request, ambiguous conversation, or protected typing draft prevents the operation.

500

The request failed.

501

The sender or platform does not support the requested capability.

502

The native operation result is uncertain. Refetch its resource before retrying.

503

The database, sender, Messages access, or request store is unavailable.

Content type application/json

APIError ↗

Headers on every response

X-Request-IDstringRequired

Request correlation identifier.

Stop a typing lease

#

Operation ID: stopTyping

relayToken↗

DELETE/v1/conversations/{conversation_id}/typing

No request body. Clears only the relay-owned one-space marker. Does not discard a user's draft.

Request

Path parameters

conversation_idstringRequired

Percent-encoded public resource identifier, not a database row ID.

Validation rules

Minimum length

1

Pattern

^[^\p{Cc}\p{Cf}]+$

Responses

200The inactive typing state.

Content type application/json

ConversationTypingResponse ↗

400, 401, 404, 409, 500, 501, 502, 503Error responses

400

Malformed JSON, query parameter, cursor, destination selection, or resource identifier.

401

Missing or invalid bearer token.

404

The requested resource was not found.

409

A conflicting request, ambiguous conversation, or protected typing draft prevents the operation.

500

The request failed.

501

The sender or platform does not support the requested capability.

502

The native operation result is uncertain. Refetch its resource before retrying.

503

The database, sender, Messages access, or request store is unavailable.

Content type application/json

APIError ↗

Headers on every response

X-Request-IDstringRequired

Request correlation identifier.