# Get chat history

Obtains chat history (chat records) of chats (including private chats and group chats).

## Prerequisites

- The application needs to enable [bot capability](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-enable-bot-ability).
- When getting messages, the robot must be in the group being queried.

## Request

Facts | &nbsp;
---|---
HTTP URL | https://open.feishu.cn/open-apis/im/v1/messages
HTTP Method | GET
Rate Limit | [1000 per minute & 50 per second](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
Supported app types | Custom App、Store App
Required scopes<br>**To use this API, you must have at least 1 of the listed scopes.**<br>Enable any scope from the list | Read and send direct messages and group chat messages(im:message)<br>Read direct messages and group chat messages(im:message:readonly)<br>Read chat history for direct messages and group chats(im:message.history:readonly)<br>**Notice**：1. **Obtain messages as the app**<br>1. To get messages from a p2p chat, enable any one of the following three permissions: **Read and send direct messages and group chat messages** (im:message) **Read direct messages and group chat messages** (im:message:readonly) **Read chat history for direct messages and group chats [Scope of older version]** (im:message.history:readonly).<br>2. To get messages from a group chat, first request any one of the permissions for the p2p chat scenario above. In addition, the app must also enable the **Read all messages in associated group chat** (im:message.group_msg) permission.<br>2. **Obtain messages as the user**<br>1. For all chat types, enable either one of the following two permissions first: **Read and send direct messages and group chat messages** (im:message) **Read direct messages and group chat messages** (im:message:readonly)<br>2. Enable additional permissions based on the chat type:<br>1. To get messages from a p2p chat, enable the **Get direct messages as user** (im:message.p2p_msg:get_as_user) permission<br>2. To get messages from a group chat, enable the **Get group chat messages as user** (im:message.group_msg:get_as_user) permission

### Request header

Parameter | Type | Required | Description
---|---|---|---
Authorization | string | Yes | `tenant_access_token`<br>or<br>`user_access_token`<br>**Value format**: "Bearer `access_token`"<br>**Example value**: "Bearer u-7f1bcd13fc57d46bac21793a18e560"<br>[How to choose and get access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)

### Query parameters

Parameter | Type | Required | Description
---|---|---|---
container_id_type | string | Yes | Container type.<br>**Optional values**:<br>- `chat`: includes single chat (p2p) and group chat (group)<br>- `thread`: thread<br>**Note**: For thread messages in **normal conversation groups**, only the root message of the thread can be obtained through the `chat` container type. You can obtain all messages in the thread reply by specifying the container type as `thread`.<br>**Example value**: chat
container_id | string | Yes | Container ID. The ID type is the same as the value of container_id_type.<br>- For how to obtain the ID of a group chat or a single chat, see [Group ID Description](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-id-description).<br>- For how to obtain the topic ID, see the **How ​​to obtain thread_id** section of [Topic Overview](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/thread-introduction).<br>**Example value**: oc_234jsi43d3ssi993d43545f
start_time | string | No | The start time of the historical information to be queried, in seconds.<br>**Notice**: The `thread` container type does not currently support obtaining messages within a specified time range.<br>**Example value**: 1608594809
end_time | string | No | The end time of the historical information to be queried, in seconds.<br>**Notice**: The `thread` container type does not currently support obtaining messages within a specified time range.<br>**Example value**: 1609296809
sort_type | string | No | Message sorting method.<br>**Notice**: When using `page_token` for paging requests, the sorting method (`sort_type`) is the same as the first request, and changing the sorting method midway is not supported.<br>**Example value**: ByCreateTimeAsc<br>**Optional values are**:<br>- ByCreateTimeAsc：Sort by message creation time ascending<br>- ByCreateTimeDesc：Sort by message creation time descending<br>**Default value**: `ByCreateTimeAsc`
page_size | int | No | The page size is the number of data items returned in a single request.<br>**Example value**: 20<br>**Default value**: `20`<br>**Data validation rules**:<br>- Value range: `1` ～ `50`
page_token | string | No | Page identifier. It is not filled in the first request, indicating traversal from the beginning; when there will be more groups, the new page_token will be returned at the same time, and the next traversal can use the page_token to get more groups<br>**Example value**: GxmvlNRvP0NdQZpa7yIqf_Lv_QuBwTQ8tXkX7w-irAghVD_TvuYd1aoJ1LQph86O-XImC4X9j9FhUPhXQDvtrQ
card_msg_content_type | string | No | The `card_msg_content_type` parameter only controls the return format of card messages and does not affect the return format of other message types.<br>1. **If not provided (default)**: The returned card structure follows the card message structure in [Receive message content structure](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/im-v1/message/events/message_content), and returning the original card JSON used when sending is not supported.<br>2. **If `user_card_content` is provided**: Returns the original card JSON used when sending the message. For Card 1.0, refer to [Card JSON 1.0 structure](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-json-structure); for Card 2.0, refer to [Card JSON 2.0 structure](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-json-v2-structure).<br>* **Version distinction**: When the returned message body is a card, you can use the `schema` field to distinguish whether the card is version 1.0 or 2.0. For details, refer to [Card JSON v2.0 breaking changes & release notes](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-json-v2-breaking-changes-release-notes).<br>> **Note: If the passed value of the `card_msg_content_type` parameter changes, please ensure you handle return format compatibility in your code.**<br>**Example value**: user_card_content

## Response

### Response body

Parameter | Type | Description
---|---|---
code | int | Error codes, fail if not zero
msg | string | Error descriptions
data | \- | \-
has_more | boolean | Whether the response body has more parameters
page_token | string | Page identifier, when has_more is true, a new page_token will also be returned. Otherwise, page_token will not be returned
items | message\[\] | Historical message data.
message_id | string | Message ID, a unique ID generated by the system. This ID is required for subsequent management and maintenance operations on the message.
root_id | string | The root message ID. In a message tree with multiple replies, `root_id` is the `message_id` of the root message. If the reply is to a topic, `root_id` is the `message_id` of the root message within the topic. For more information about `root_id`, see [Message Management Overview](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/intro).
parent_id | string | The ID of the parent message. In a message tree with multiple replies, `parent_id` is the `message_id` of the message above the current message. If the reply is to a topic, `parent_id` is always the `message_id` of the root message in the topic. For more information about `parent_id`, see [Message Management Overview](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/intro).
thread_id | string | The thread ID to which the message belongs (not returned indicates that the message is not a thread message).  For the description, refer to [Thread Introduction](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/thread-introduction)
msg_type | string | Message type. For details of each type, refer to [Receive message content](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/im-v1/message/events/message_content).
create_time | string | Message generation timestamp (in ms)
update_time | string | Message update timestamp (in ms)
deleted | boolean | Whether the message is recalled or deleted.<br>- true, if it is a recalled message, the content parameter will always return `This message was recalled`.<br>- false
updated | boolean | Whether the message is updated.<br>- true<br>- false
chat_id | string | The group ID to which the message belongs. You can call the [get group information](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat/get) interface to obtain group details based on the group ID.
sender | sender | The sender information of the current message.
id | string | This field identifies the sender's ID
id_type | string | This field identifies the sender's ID type<br>**Optional values are:**<br>- `open_id`<br>- `app_id`
sender_type | string | This field identifies the sender type<br>**Optional values are:**<br>- `user`<br>- `app`<br>- `anonymous`<br>- `unknown`
tenant_key | string | The unique ID of the tenant. This ID is used to identify the tenant and can also be used to obtain the tenant access credential (tenant_access_token).
body | message_body | Returns the current message content via the `content` parameter in `body`.
content | string | Message content, a string serialized from a JSON structure. Different message types (`msg_type`) correspond to different contents.<br>**Note**: The card message content is inconsistent with the card JSON obtained in the card building tool. Returning the original card JSON is not currently supported.
mentions | mention\[\] | List of IDs of the mentioned users or bots
key | string | Serial number of the mentioned user or bot; for example, for the third mentioned member, the value is "@_user_3"
id | string | open_id of the mentioned user or bot
id_type | string | ID type of the mentioned user or bot; currently, only `open_id` is supported ([What is Open ID?](https://open.feishu.cn/document/home/user-identity-introduction/open-id))
name | string | Name of the mentioned user or bot
tenant_key | string | The unique ID of the tenant. This ID is used to identify the tenant of the @ user or robot, and can also be used to obtain the tenant access credential (tenant_access_token).
upper_message_id | string | message_id in the upper level of the combined and forwarded message; for the description, refer to [Message ID description](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/intro#ac79c1c2)

### Response body example
```json
{
	"code": 0,
	"msg": "success",
	"data": {
		"has_more": true,
		"page_token": "GxmvlNRvP0NdQZpa7yIqf_Lv_QuBwTQ8tXkX7w-irAghVD_TvuYd1aoJ1LQph86O-XImC4X9j9FhUPhXQDvtrQ",
		"items": [{
			"message_id": "om_dc13264520392913993dd051dba21dcf",
			"root_id": "om_40eb06e7b84dc71c03e009ad3c754195",
			"parent_id": "om_d4be107c616aed9c1da8ed8068570a9f",
			"msg_type": "interactive",
			"create_time": "1615380573411",
			"update_time": "1615380573411",
			"deleted": false,
			"updated": false,
			"chat_id": "oc_5ad11d72b830411d72b836c20",
			"sender": {
				"id": "cli_9f427eec54ae901b",
				"id_type": "app_id",
				"sender_type": "app",
				"tenant_key": "736588c9260f175e"
			},
			"body": {
				"content": "{\"text\":\"test content\"}"
			},
			"mentions": [{
				"key": "@_user_1",
				"id": "ou_155184d1e73cbfb8973e5a9e698e74f2",
				"id_type": "open_id",
				"name": "Tom",
				"tenant_key": "736588c9260f175e"
			}],
			"upper_message_id": "om_40eb06e7b84dc71c03e009ad3c754195"
		}]
	}
}
```

### Error code

HTTP status code | Error code | Description | Troubleshooting suggestions
---|---|---|---
400 | 230001 | Your request contains an invalid request parameter. | Parameter error: Check whether the input parameters are filled in correctly based on the error information actually returned by the interface and the interface documentation.
400 | 230002 | The bot can not be outside the group. | The robot is not in the corresponding group. You need to add the application robot to the group that receives the message. For how to add a robot, refer to the [Robot User Guide](https://open.feishu.cn/document/ukTMukTMukTM/uATM04CMxQjLwEDN).
400 | 230006 | Bot ability is not activated. | The application does not have bot capability enabled. For more information, see [How to enable bot capability](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-enable-bot-ability).
400 | 230013 | Bot has NO availability to this user. | The target user (the message recipient specified by the user's user_id/open_id/union_id/email) or the single chat user (the message recipient specified by the chat_id of the group chat, but the group chat type corresponding to the chat_id is single chat `p2p`) is not within the available range of the app bot, or is within the disabled range of the app.<br>**Notice**: If the target user has left the company, error 230013 will also be reported.<br>Solution:<br>1. Log in to [Developer Console](https://open.feishu.cn/app), find and enter the specified app details page.<br>2. In the left navigation bar, go to **App Versions** > **Version Management & Release** page, and click **Create a version**.<br>3. On the **Version Details** page, find the **Availability** area and click **Edit**.<br>4. In the dialog box that pops up, configure the available range of the app and add the user to the available range.<br>5. Click **Save** at the bottom of the page and publish the app to make the configuration effective.<br>6. (Optional) If an error message still appears after completing the above configuration, you need to contact the enterprise administrator to log in to the [Admin](https://feishu.cn/admin), enter the specified app details page in **Workplace** > **App Management**, and check whether the user is set as a **Blocked members** in **App availability**.<br>For specific operations, see [Configure app availability](https://open.feishu.cn/document/home/introduction-to-scope-and-authorization/availability).
400 | 230027 | Lack of necessary permissions. | >You are not authorized to perform this operation. Possible reasons are:<br>1. Lack of corresponding permissions, please troubleshoot according to the error message.<br>2. User authorization information was not checked.<br>3. If the bot needs to operate in external groups, you must first enable external sharing capabilities for it. For more details, refer to [Bot support for external groups and chats with external users](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/develop-robots/add-bot-to-external-group).
400 | 230073 | The thread is invisible to the operator. | This topic is not visible to the current operator. If the group chat has disabled **New members can view historical messages** and this topic was created before the current operator entered the group chat, the topic will only be visible to the operator after the operator passively subscribes (such as other users @ the operator in the topic).
400 | 230110 | Action unavailable as the message has been deleted. | Action unavailable as the message has been deleted.
400 | 231203 | The chat type is not supported. | The group type does not support obtaining messages. For example, if the secret mode is turned on in the group settings to prohibit copying messages, messages cannot be obtained.
400 | 231204 | The app type is not supported. | Apps with external sharing or associated organizations enabled do not support requesting this interface as a user

For other unlisted error codes, please refer to [Server Error Codes](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN).

