Rocket.Chat Messaging API

The Messaging APIs let you send, manage, and search messages across every kind of room. This section covers the Chat endpoints (messages in channels, groups, and threads), Direct Messages, and Auto-Translate.

The message object

Message endpoints accept and return a message object. A trimmed example from Get Message:

{
  "message": {
    "_id": "CeXwh5eBbdrtvnqG6",
    "rid": "agh2Sucgb54RQ8dDo",
    "msg": "s",
    "ts": "2018-10-05T13:48:21.616Z",
    "u": {
      "_id": "KPkEYwKKBKZnEEPpt",
      "username": "marc.pow",
      "name": "Marc Pow"
    },
    "reactions": {
      ":frowning2:": { "usernames": ["marcos.defendi"] }
    },
    "mentions": [],
    "channels": []
  },
  "success": true
}

Fields you use most often:

• _id: The message ID. Pass it as msgId or messageId when updating, reacting, pinning, or deleting.

• rid: The ID of the room the message belongs to. Most message endpoints require it.

• msg: The message text.

• u: The user who sent the message.

• tmid: Set when the message belongs to a thread — it holds the thread's parent message ID.

Common workflows

Post and manage a message

1. Post a message to a room using its roomId or channel name.

2. Update the message, react to it, or pin it.

3. Delete the message when it is no longer needed.

Start a direct message

1. Create the direct message session with one or more users.

2. Post messages using the returned room ID.

3. Close the session to hide it from your room list.

Work with threads

1. Send a message with tmid set to the parent message ID to reply in a thread.

2. List a room's threads and read a thread's messages.

3. Mark the thread as read when you finish processing it.

Translate messages

1. Get the supported languages.

2. Translate the message to the target language.

Conventions

• Post Message accepts a channel name or ID and can send to multiple channels; Send Message targets one room and lets you set a custom message _id and thread fields.

• Message endpoints identify rooms by roomId (rid). Message-level actions take the message ID from the message object.

• List endpoints such as Search Message support count and offset query parameters.