> ## Documentation Index > Fetch the complete documentation index at: https://developer.rocket.chat/llms.txt > Use this file to discover all available pages before exploring further. # List DM Messages > List all the messages in a DM. ### Changelog | Version | Description | | ---------------- | ------------| | 7.0.0 | Added `mentionIds`, `starredIds`, `pinned` query parameters.| |0.59.0 | Added | ## OpenAPI ````json GET /api/v1/dm.messages { "openapi": "3.0.0", "info": { "version": "1.0.0", "title": "Messaging" }, "servers": [ { "url": "https://apiexplorer.support.rocket.chat" } ], "tags": [ { "name": "Chat" }, { "name": "DM" }, { "name": "Auto-Translate" } ], "paths": { "/api/v1/dm.messages": { "get": { "tags": [ "DM" ], "summary": "List DM Messages", "description": "List all the messages in a DM. \n\n### Changelog\n| Version | Description | \n| ---------------- | ------------|\n| 7.0.0 | Added `mentionIds`, `starredIds`, `pinned` query parameters.| \n|0.59.0 | Added |", "operationId": "get-api-v1-im.messages", "parameters": [ { "$ref": "#/components/parameters/Auth-Token" }, { "$ref": "#/components/parameters/UserId" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/count" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/query" }, { "name": "roomId", "in": "query", "description": "The room ID of the DM. It is required if `username` is not provided.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Optional-Username" }, { "name": "mentionIds", "in": "query", "description": "Filter the messages where a user has been mentioned by the userId. For a set of userIds, use an array (`[\"838ndhd79w\", \"dud0wu900\"]`).", "schema": { "type": "string" }, "example": "838ndhd79w" }, { "name": "starredIds", "in": "query", "description": "Filter the messages a user have starred by userId. For a set of userIds, use an array (`[\"838ndhd79w\", \"dud0wu900\"]`).", "schema": { "type": "string" }, "example": "dud0wu900" }, { "name": "pinned", "in": "query", "description": "Filter pinned messages.", "schema": { "type": "string" }, "example": "true" }, { "schema": {}, "in": "query", "name": "sort", "description": "Sort the order in which messages are returned, ascending (`1`) or descending (`-1`). The options are:\n * `ts`: Sort by message timestamp. For example, `{\"ts\": -1}`, this is the default sorting mechanism.\n * `u.username`: Sort by username. For example, `{\"u.username\": 1}`.\n * `msg`: Sort by message content. For example, `{\"msg\": 1}`.\n * `_id`: Sort by message ID. For example, `{\"_id\": -1}`.\n * `mentions._id`: Sort by mentioned user IDs. For example, `{\"mentions._id\": 1}`." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "rid": { "type": "string" }, "msg": { "type": "string" }, "ts": { "type": "string" }, "u": { "type": "object", "properties": { "_id": { "type": "string" }, "username": { "type": "string" }, "name": { "type": "string" } } }, "_updatedAt": { "type": "string" }, "urls": { "type": "array", "items": { "type": "object" } }, "mentions": { "type": "array", "items": { "type": "object" } }, "channels": { "type": "array", "items": { "type": "object" } }, "md": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "value": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "value": { "type": "string" } } } } } } } } } }, "count": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" }, "success": { "type": "boolean" } } }, "examples": { "Example": { "value": { "messages": [ { "_id": "dGNzxH29pFm4Qhufh", "rid": "5fRTXMt7DMJbpPJfhgzvcvpov9G4TxbGFS", "msg": "DO we have any updates today?", "ts": "2023-11-01T23:20:57.357Z", "u": { "_id": "5fRTXMt7DMJbpPJfh", "username": "test.john", "name": "Test John" }, "_updatedAt": "2023-11-01T23:20:57.406Z", "urls": [], "mentions": [], "channels": [], "md": [ { "type": "PARAGRAPH", "value": [ { "type": "PLAIN_TEXT", "value": "DO we have any updates today?" } ] } ] }, { "_id": "aiaCSRkxPcNGHqvtC", "rid": "5fRTXMt7DMJbpPJfhgzvcvpov9G4TxbGFS", "msg": "Hows it going?", "ts": "2023-11-01T23:20:51.504Z", "u": { "_id": "5fRTXMt7DMJbpPJfh", "username": "test.john", "name": "Test John" }, "_updatedAt": "2023-11-01T23:20:51.549Z", "urls": [], "mentions": [], "channels": [], "md": [ { "type": "PARAGRAPH", "value": [ { "type": "PLAIN_TEXT", "value": "Hows it going?" } ] } ] }, { "_id": "dLjcNr8ovyeCqqJW5", "rid": "5fRTXMt7DMJbpPJfhgzvcvpov9G4TxbGFS", "msg": "Hi buddy", "ts": "2023-11-01T23:20:47.991Z", "u": { "_id": "5fRTXMt7DMJbpPJfh", "username": "test.john", "name": "Test John" }, "_updatedAt": "2023-11-01T23:20:48.085Z", "urls": [], "mentions": [], "channels": [], "md": [ { "type": "PARAGRAPH", "value": [ { "type": "PLAIN_TEXT", "value": "Hi buddy" } ] } ] } ], "count": "3", "offset": "0", "total": "3", "success": "true" } } } } } }, "401": { "$ref": "#/components/responses/authorizationError" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "error": { "type": "string" }, "errorType": { "type": "string" } } }, "examples": { "Missing Parameter": { "value": { "success": "false", "error": "must have required property 'roomId'\n must have required property 'username'\n must match exactly one schema in oneOf [invalid-params]", "errorType": "invalid-params" } }, "Invalid Channel": { "value": { "success": "false", "error": "[invalid-channel]", "errorType": "invalid-channel" } } } } } } } } } }, "components": { "parameters": { "Auth-Token": { "name": "X-Auth-Token", "in": "header", "description": "The `authToken` of the authenticated user.", "required": "true", "schema": { "type": "string" }, "example": "RScctEHSmLGZGywfIhWyRpyofhKOiMoUIpimhvheU3f" }, "UserId": { "name": "X-User-Id", "in": "header", "description": "The `userId` of the authenticated user.", "required": "true", "schema": { "type": "string" }, "example": "rbAXPnMktTFbNpwtJ" }, "offset": { "name": "offset", "in": "query", "description": "Number of items to \"skip\" in the query, i.e. requests return count items, skipping the first offset items. Refer to the [official documentation](https://developer.rocket.chat/apidocs/query-parameters#pagination) to learn more.", "required": "false", "schema": { "type": "integer" }, "example": "50" }, "count": { "name": "count", "in": "query", "description": "The number of items to return. Refer to the [official documentation](https://developer.rocket.chat/apidocs/query-parameters#pagination) to learn more.", "required": "false", "schema": { "type": "integer" }, "example": "50" }, "fields": { "name": "fields", "in": "query", "description": "This parameter accepts a JSON object with properties that have a value of 1 or 0 to include or exclude them in the response. For example, to only retrieve the usernames of users: fields=`{ \"username\": 1 }`. Refer to the [official documentation](https://developer.rocket.chat/apidocs/query-parameters#query-and-fields) to learn more.", "required": "false", "schema": { "type": "string" } }, "query": { "name": "query", "in": "query", "description": "This parameter allows you to use MongoDB query operators to search for specific data. For example, to query users with a name that contains the letter \"g\": query=`{ \"name\": { \"$regex\": \"g\" }}`. Refer to the [official documentation](https://developer.rocket.chat/apidocs/query-parameters#query-and-fields) to learn more.", "required": "false", "schema": {} }, "Optional-Username": { "name": "username", "in": "query", "description": "The username of the user in the DM. It is required if `roomId` is not provided.", "required": "false", "schema": { "type": "string" } } }, "responses": { "authorizationError": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "Authorization Error": { "value": { "status": "error", "message": "You must be logged in to do this." } } } } } } } } } ````