API call description
- You can query the read status for up to 20 recipients of a single one-on-one chat message at a time.
- If you send an HTTP request directly, URL-encode the
processQueryKeyparameter first, and then append the encoded value to the URL.
Request
Basic information
| Field | Value |
|---|---|
| HTTP URL | https://api.dingtalk.io/v1.0/robot/oToMessages/readStatus |
| HTTP Method | GET |
| Supported app types | appType-Internal app appType-Third-party enterprise app |
| Required permissions | permission-qyapi_robot_sendmsg-Permission to send messages from bots within your organization |
Request headers
| Name | Type | Required | Description |
|---|---|---|---|
| x-acs-dingtalk-access-token | String | Yes | The access credential used to call this API. Obtain it as follows: - For an internal app, call the Get the access token of an internal app API. - For a third-party enterprise app, call the Get the access token of an authorized enterprise for a third-party app API. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
| robotCode | String | Yes | The bot code. For details, see Bot ID. |
| processQueryKey | String | Yes | The unique identifier of the message. You can obtain it from the processQueryKey field returned by the Batch send bot messages in one-on-one chats API. You can query the read status using processQueryKey within 24 hours after the message is sent. Queries are not supported after 24 hours. |
Request example
HTTPResponse
Response body
| Name | Type | Description |
|---|---|---|
| sendStatus | String | The message sending status: - SUCCESS: The message was sent successfully. - RECALLED: The message has been recalled. - PROCESSING: The message is being processed. |
| messageReadInfoList | Array | The read status of the message. |
| name | String | The name of the message recipient. |
| userId | String | The userId of the message recipient. |
| readStatus | String | The read status: - READ: Read. - UNREAD: Unread. |
| readTimestamp | Long | Not supported at this time. |
Response body example
Error codes
If an error occurs when you call this API, look up the error message in the Global error codes document for the solution.| HttpCode | Error code | Error message | Description |
|---|---|---|---|
| 400 | invalidParameter.robotCode.empty | %s | The bot robotCode is invalid. |
| 400 | invalidParameter.param.invalid | %s | Invalid parameter. Check whether the parameter is empty. |
| 400 | invalidParameter.robotCode.notExsit | %s | The bot does not exist. |
| 400 | unknown.send.result | %s | Unknown send result. |
| 400 | invalidParameter.robotCode.missing | %s | The robotCode is missing. |
| 400 | invalidParameter.processQueryKey.missing | %s | The processQueryKey is missing. |
| 400 | invalidParameter.robotCode.invalid | %s | The bot does not exist. Check whether the bot corresponding to robotCode is installed in your organization. |
| 400 | invalid.processQueryKey | %s | Invalid processQueryKey. Check whether the processQueryKey is correct. |
| 400 | template.not.existed | %s | The bot template does not exist. |
| 400 | template.stopped | %s | The bot template has been disabled. |
| 400 | processQueryKey.expireTime | %s | The processQueryKey has not yet generated message query data or has expired. The message cannot be queried. |
| 500 | system.error | %s | The system is busy. Try again later. |