Chat API

The Chat API is available under /apis/v1/chat and requires a Ration bearer token. Every response is scoped to the authenticated user's tenant and room membership.

Authorization: Bearer <ration_access_token>
Accept: application/json

Response models

Room

Field	Type	Description
id	String	Room identifier.
name	String	Room or meeting name.
chat_type	String	personal, group, team, or meeting.
room_type	String or null	meeting for a meeting room, when set.
parties	Array	Room participants, including party_id and role data.
last_message	Message or null	Most recent message, when available.
unseen, unread	Number, Boolean	Current caller's unread state.
inserted_at, updated_at, last_message_at	String	Timestamps, when available.
meeting_mode, broadcast_mode, livestream_type	String or null	Meeting configuration, when applicable.
scheduled_start_at, scheduled_end_at	String or null	Scheduled meeting times, when applicable.

Message

Field	Type	Description
id	String	Message identifier.
room_id	String	Parent room identifier.
body	String	Text body.
sending_party, name	String	Sender identifier and display name.
message_type	String	Message type; REST-created messages are text.
inserted_at	String	Creation timestamp.
attachments	Array	Attached-file metadata.
reply_to	Object or null	Referenced message summary, when this is a reply.
edited, deleted	Boolean	Message state.
reactions	Array	Grouped reaction data.

Identity and rooms

Get the current chat identity

GET /apis/v1/chat/user

Returns the caller's chat-facing identity.

Response field	Type	Description
id, name, username, address	String	User identifiers and display details.
image, location, mobile, alternate, dob, gender	String or null	Profile details, when set.
language	String	Preferred language, when set.

List tenant users

GET /apis/v1/chat/users

User-directory query parameters are passed to the tenant directory lookup.

Response field	Type	Description
users	Array	User objects in the same shape as GET /chat/user.
total	Number	Number of matching users.
page	Number	Current page, when returned.
nextCursor, previousCursor	String or null	Directory pagination cursors.

List rooms

GET /apis/v1/chat/rooms

Name	In	Type	Required	Description
chat_type	Query	String	No	Limit rooms to a type, such as personal, group, or meeting.
limit	Query	Integer	No	Page size.
next_pointer	Query	String	No	Pointer from the prior response.

Response: { "results": [Room], "has_more": Boolean, "next_pointer": String | null }.

Create a room

POST /apis/v1/chat/rooms

{
  "name": "Design review",
  "chat_type": "group",
  "party_ids": ["user_123", "user_456"]
}

Name	Type	Required	Description
name	String	No*	Room name. Required for chat_type: "meeting".
chat_type	String	No	Defaults to personal; use group, team, or meeting as appropriate.
party_ids	String array	No	Additional participant IDs. The caller is included automatically.
room_type	String	No	Set to meeting for a meeting room; inferred for chat_type: "meeting".
meeting_mode	String	No	Meeting mode; defaults to instant for meetings.
broadcast_mode	String	No	broadcast (default) or livestream.
livestream_type	String	No	public (default) or private for livestream meetings.
scheduled_start_at, scheduled_end_at	String	No	Scheduled meeting start and end values.
meeting_reminder, reminder	String or Integer	No	Optional meeting reminder.

Response: a Room object. A request for a meeting without a name returns 422 { "error": "meeting_name_required" }; livestream creation without the required plan capability returns 403 { "error": "livestream_not_entitled" }.

Read, update, or remove a room

GET|PUT|DELETE /apis/v1/chat/rooms/:id

GET returns a Room. PUT accepts room fields such as name, party_ids, and the meeting fields listed for creation, then returns the updated room. Send { "hide_options": true } to hide the room for the caller; it returns the text Successful.

DELETE removes the room from the caller's active view and returns the text Successful when the caller belongs to it.

Messages

List messages

GET /apis/v1/chat/rooms/:id/messages

Name	In	Type	Required	Description
id	Path	String	Yes	Room identifier.
per_page	Query	Integer	No	Page size; defaults to 25, maximum 200.
next_pointer	Query	String	No	Message ID returned by the preceding page.

Response: { "results": [Message], "has_more": Boolean, "next_pointer": String | null }.

Send a message

POST /apis/v1/chat/rooms/:id/messages

{
  "body": "Please review the latest draft.",
  "reply_to_message_id": "message_123",
  "client_token": "optional-client-correlation-id"
}

Name	Type	Required	Description
body	String	Yes	Non-empty text message body.
reply_to_message_id	String	No	Message to reply to.
client_token	String	No	Client correlation value; echoed in a successful response.

Response: a Message object. An empty body returns 422 { "error": "empty_body" }.

Delete a message

DELETE /apis/v1/chat/rooms/:id/messages/:message_id

Response: the updated/deleted Message object.

Membership and attachments

Add or remove group/meeting members

POST /apis/v1/chat/rooms/:id/members

{ "member_ids": ["user_123", "user_456"] }

party_ids is accepted as an alias for member_ids. The room must be a group or meeting; the caller must already belong to the room. Response: the updated Room.

DELETE /apis/v1/chat/rooms/:id/members/:member_id removes one member and returns the updated room. A caller cannot remove themself with this endpoint.

Upload a chat attachment

POST /apis/v1/chat/attachments

Send multipart/form-data with one required file part. The maximum upload size is 25,000,000 bytes.

Response field	Type	Description
attachment.url	String	Authenticated file URL.
attachment.secure_id	String	Stored-file identifier.
attachment.filename	String	Original filename.
attachment.content_type	String	MIME type.
attachment.size	Number	File size in bytes.
attachment.type	String	image for image MIME types; otherwise file.

Errors

Status	Error	Meaning
401	Authentication error	Missing, expired, or invalid bearer token.
403	not_authorized	Caller is not a member of the room or cannot perform the operation.
404	room_not_found, message_not_found, member_not_found	The requested resource does not exist in the caller's tenant context.
422	empty_body, invalid_message_id, missing_member_ids, unsupported_room, cannot_remove_self, update_failed	Request could not be applied.
500	message_fetch_failed, message_send_failed, message_delete_failed	Server-side chat operation failed.

Calls, meetings, and guest access

Meeting recordings, call-token minting, and external guest invite flows use related /apis/v1/meetings, /apis/v1/call, and invite-token routes. They are documented separately from ordinary room messaging because their authorization and lifecycle differ.