Messages

Read and send messages, update reactions, and track send requests.

6 endpoints API 0.5.1-rc.3

Read the usage guide

Page through conversation messages

Operation ID: listMessages

relayToken

GET/v1/conversations/{conversation_id}/messages

Reactions are nested under their target messages. URL previews can be folded into the preceding text message.

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}]+$

Query parameters

limitintegerOptional

Maximum number of items in this page.

Default: 50

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}]+$

include_attachmentsstringOptional

Include attachment metadata in messages and attachment parts. 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])$

qstringOptional

Case-insensitive search of decoded message text in this conversation.

search_modestringOptional

Text search matching mode.

Default: "contains"

Allowed:"contains""exact"

Responses

200A page of messages.

Content type application/json

PaginatedResponseOfMessage

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.

Submit a message send

Operation ID: sendMessage

relayToken

POST/v1/messages

Provide exactly one non-null destination. Every resolved participant must be allowlisted. Participant sends require text and do not support media or reply_to. Use an existing conversation for native replies. Reuse the same idempotency key for retries. A changed normalized request returns 409. A 202 response is not proof of delivery. Poll poll_url for correlation and lifecycle status.

Request

Request headers

Idempotency-KeystringOptional

Trimmed before use. Blank means no key. At most 128 UTF-8 bytes without control characters. The same key and normalized request return the stored result without dispatching again.

Validation rules

Maximum length: 128

Body Required

A destination, text or uploaded media, and an optional reply target.

Content type application/json

SendMessageRequest

Example

{
  "text": "Hello",
  "to": "friend@example.com"
}

Responses

202Accepted send with a durable poll URL and correlation state.

Content type application/json

SendMessageResponse

400, 401, 403, 404, 409, 413, 422, 500, 501, 502, 503Error responses

400: Malformed JSON, query parameter, cursor, destination selection, or resource identifier.
401: Missing or invalid bearer token.
403: One or more destination recipients are not allowlisted.
404: The requested resource was not found.
409: A conflicting request, ambiguous conversation, or protected typing draft prevents the operation.
413: The request body or media exceeds its configured size limit.
422: A destination, payload field, filename, or media file failed validation.
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.

Read one message

Operation ID: getMessage

relayToken

GET/v1/messages/{message_id}

Request

Path parameters

message_idstringRequired

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

Validation rules

Minimum length: 1
Pattern: ^[^\p{Cc}\p{Cf}]+$

Responses

200The message and its provider metadata.

Content type application/json

Message

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.

Set the local sender's reaction

Operation ID: setReaction

relayToken

PUT/v1/messages/{message_id}/reaction

Uses the provider's default message part. Repeating the same reaction returns unchanged. Success follows observation of the resulting outgoing reaction row. Refetch after a 502 result.

Request

Path parameters

message_idstringRequired

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

Validation rules

Minimum length: 1
Pattern: ^[^\p{Cc}\p{Cf}]+$

Body Required

The reaction to set.

Content type application/json

SetReactionRequest

Example

{
  "reaction": "love"
}

Responses

200The resulting local reaction state.

Content type application/json

ReactionWriteResponse

400, 401, 404, 409, 413, 422, 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.
413: The request body or media exceeds its configured size limit.
422: A destination, payload field, filename, or media file failed validation.
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.

Clear the local sender's reaction

Operation ID: clearReaction

relayToken

DELETE/v1/messages/{message_id}/reaction

No request body. Clearing an absent reaction returns unchanged. A successful result contains reaction: null.

Request

Path parameters

message_idstringRequired

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

Validation rules

Minimum length: 1
Pattern: ^[^\p{Cc}\p{Cf}]+$

Responses

200The resulting local reaction state.

Content type application/json

ReactionWriteResponse

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.

Read durable send request status

Operation ID: getSendRequest

relayToken

GET/v1/requests/{request_id}

Retries provider-message identification for pending or partial correlation, then refreshes identified message lifecycle states. Durable request state survives relay restarts. Polling never sends the message again.

Request

Path parameters

request_idstringRequired

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

Validation rules

Minimum length: 1
Pattern: ^[^\p{Cc}\p{Cf}]+$

Responses

200The current durable send result.

Content type application/json

SendMessageResponse

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.