# Get message history (/en/api-reference/api-ref/signaling/message-history)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

Retrieves historical messages from a specified channel.

- OpenAPI: /openapi/rtm/signaling-rest.en.yaml
- Operation ID: get-message-history
- Method: GET
- Path: /rtm/v2/history/{appId}/userId/{userId}/channelType/{channelType}/channel/{channelName}
- Endpoint: https://api.sd-rtn.com/rtm/v2/history/{appId}/userId/{userId}/channelType/{channelType}/channel/{channelName}

## Servers

- https://api.sd-rtn.com

Retrieves historical messages from the specified channel.


## Authorization

This endpoint requires authentication.

- `basicAuth`

## Parameters

- `appId` (path, required, string) - The App ID of your Agora project.
- `userId` (path, required, string) - The user ID for the operation.

 - 26 lowercase English letters: a-z
 - 26 uppercase English letters: A-Z
 - 10 numbers: 0-9
 - Space
 - Special characters: !, #, $, %, &, (, ), +, -, :, ;, <, =, ., >, ?, @, [, ], ^, _, {, }, |, ~

  :::warning[Caution]
  Character length must be between 1 and 64.
  :::
- `channelType` (path, required, string) - The type of channel to retrieve messages from. `message` for a message channel, `user` for a user channel.
  - Allowed: `message` | `user`
- `channelName` (path, required, string) - The name of the channel.

 - 26 lowercase English letters: a-z
 - 26 uppercase English letters: A-Z
 - 10 numbers: 0-9
 - Space
 - Special characters: !, #, $, %, &, (, ), +, -, :, ;, <, =, ., >, ?, @, [, ], ^, _, {, }, |, ~

  :::warning[Caution]
  Character length must be between 1 and 64.
  :::
- `start` (query, optional, integer) - The start timestamp of the historical message query. Defaults to `0` if not specified.
  - Default: `0`
  - Format: `int64`
- `end` (query, optional, integer) - The end timestamp of the historical message query. Defaults to `0` if not specified.
  - Default: `0`
  - Format: `int64`
- `messageCount` (query, optional, integer) - The maximum number of messages to return in a single query. The value must be in the range `(0, 100]`. Defaults to `100`.
  - Default: `100`
  - Format: `int32`
  - Range: `(0, 100]`

## Request body

No request body.

## Request examples

### curl

```bash
curl -L 'https://api.sd-rtn.com/rtm/v2/history/{appId}/userId/Tony/channelType/message/channel/chatroom?start=17809876 & end = 1781000 & messageCount = 100' \
      -H 'Accept: application/json'
```

### Python

```python
import requests

    url = "https://api.sd-rtn.com/rtm/v2/history/{:appId}/userId/Tony/channelType/message/channel/chatroom"

    params = {
      'start': 17809876,
      'end': 1781000,
      'messageCount': 100
    }

    headers = {
      'Accept': 'application/json',
      'Authorization': 'agora token=007xxxxx'
    }

    try:
      response = requests.get(url, params=params, headers=headers)
      print(response.json())
    except Exception as error:
      print(error)
```

### Node.js

```javascript
const axios = require('axios');

    let config = {
        method: 'get',
        maxBodyLength: Infinity,
        url: 'https://api.sd-rtn.com/rtm/v2/history/{:appId}/userId/Tony/channelType/message/channel/chatroom?start=17809876 & end = 1781000 & messageCount = 100',
        headers: {
            'Accept': 'application/json'
            'Authorization': 'agora token=007xxxxx'
            }
        };

    axios.request(config)
    .then((response) => {
      console.log(JSON.stringify(response.data));
    })
    .catch((error) => {
      console.log(error);
    });
```


### Response

- If the returned status code is `200`, the request was successful. The response body contains the result of the request.

- If the returned status code is not `200`, the request failed. The response body includes the error code and description. Refer to [status codes](/en/realtime-media/rtm/reference/error-codes#restful-api-error-codes) to understand the possible reasons for failure.


## Responses

### 200

The request was successful. The response body contains the result of the request.

- `errorCode` (integer) - The status code of the request. `200` indicates success.
- `error` (boolean) - Indicates whether the request failed. `false` if it succeeded, `true` if it failed.
- `requestId` (string) - The unique ID associated with the request.
- `operation` (string) - The specific operation performed by the request.
- `reason` (string) - A short explanation of the reason for the error.
- `timestamp` (integer) - The time the request was sent, as a Unix timestamp in milliseconds.

The time the request was sent, represented as a Unix timestamp in milliseconds.
- `data` (object) - The response payload.

The response payload. Contains the following fields:
  - `data.messageList` (array) - An array of message objects.
    - `data.messageList.items` (object)
      - `data.messageList.items.messageType` (string) - The type of message content. `STRING` uses the `message` field directly; `BINARY` is base64-encoded in the `message` field.
      - `data.messageList.items.message` (string) - The content of the message.
      - `data.messageList.items.customType` (string) - The custom message type.
      - `data.messageList.items.publisher` (string) - The user ID of the message sender.
      - `data.messageList.items.timestamp` (integer) - The time the message was sent, as a Unix timestamp.
  - `data.count` (integer) - The total number of messages retrieved.
  - `data.newStart` (integer) - The start timestamp for the next batch of messages.
### default

The request failed. The response body includes the error code and description.

No schema.

## Response examples

### 200

```json
{
  "errorCode": 200,
  "error": false,
  "requestId": "1121_1234231",
  "operation": "getMessage",
  "reason": "",
  "timestamp": 1234567,
  "data": {
    "messageList": [
      {
        "messageType": "STRING",
        "message": "Hello, how are you?",
        "customType": "text",
        "publisher": "Tony",
        "timestamp": 1234567890
      }
    ],
    "count": 1,
    "newStart": 1234567892
  }
}
```