Query Messages in a Message Session

Query messages in a specific message session.

Request URL

GET {base_url}/{api_path}/message/get?access_token={access_token}

Request parameters


Parameter	Required	Type	Description
page_size	Yes	Integer	Define how many records per page.
id	Yes	Integer	The unique ID of the message session. Note: You can query the message session ID using Search Specific Message Sessions.
last_msg_id	No	Integer	The ID of the last message in this query. Note: This parameter is used for pagination. When specified, messages earlier than the message specified by this ID (excluding this message) are returned. For example, after querying a page of messages, use the earliest message ID (`msg_id`) from that page in the next request to retrieve the previous page of messages.

Response parameters


Parameter	Type	Description
errcode	Integer	Returned error code. `0`: Succeed. Non-zero value: Failed. Note: You can check the error code and error message in Error Code and Error Message.
errmsg	String	Returned message. `SUCCESS`: Succeed. `FAILURE`: Failed.
data	Object<Messages>	The information of the queried messages.

Messages


Parameter	Type	Description
session_id	Integer	The unique ID of the message session.
records	Array<Msg_Record>	Message records.

Msg_Record


Parameter	Type	Description
session_id	Integer	The unique ID of the message session.
msg_id	Integer	The unique ID of the message.
delivery_status	Integer	Message delivery status. `0`: Sending. `1`: Sent successfully. `2`: Failed to send.
sender	Object<Sender_Info>	The information of the sender.
msg_kind	Integer	The category of the message. `0`: Normal message. `1`: WhatsApp template message.
msg_type	Integer	The type of the message content. `0`: User message. `1`: Transfer message (transferred to extension or third-party message analytics platform). `2`: Manually closed message. `3`: Automatically closed message. `4`: Unsupported message type message. `5`: Session pickup message. `6`: Transfer message (transferred to message queue). `7`: Visitor manually closed session message. `8`: Call-related message.
msg_body	String	Message content.
msg_files	String	The information of message files, which is returned as a JSON-formatted string. The string represents an array of `File_Info` objects. For more details, see the File_Info table.
send_time	Integer	The Unix timestamp (in seconds) when the message was sent.
receive_time	Integer	The Unix timestamp (in seconds) when the message was received.
param	String	Additional message-related parameters, which is returned as a JSON-formatted string. The returned value varies depending on the `msg_type`. If `msg_type` is `1` or `6`, this parameter returns session transfer information. If `msg_type` is `8`, this parameter returns call information. For more details, see the Param table.
send_error	String	The type of error that occurred when sending a message. `invalid_webhook_request`: Invalid request. `unsupported_callback_type`: Unsupported callback type. `resource_not_found`: Resource not found. `invalid_did_number`: Invalid DID number. `auth_fail`: Authentication failed. `auth_not_exit`: Authentication information does not exist. `request_fail`: Request failed. `send_fail`: Sending failed. `exceeds_size_limit`: Message exceeded size limit. `too_many_request`: Too many requests. `unsupport_media_type`: Unsupported media type. `invalid_param`: Invalid parameter. `invalid_phone_number`: Invalid phone number. `exceeds_time_limit`: Exceeded time limit. `service_unavailable`: Third-party service unavailable. `service_error`: Third-party service error. `unknown_error`: Unknown error. `template_not_exist`: WhatsApp template does not exist. `msg_exceed`: WhatsApp message text exceeds the allowed limit.
send_error_msg	String	The error message returned by third-party services when message sending fails.
tag	String	The tag assigned to the Facebook message, indicating its category or purpose. `ACCOUNT_UPDATE`: Account-related updates. `CONFIRMED_EVENT_UPDATE`: Confirm event updates. `HUMAN_AGENT`: Message sent by a human agent. `POST_PURCHASE_UPDATE`: Updates after a purchase.
whatsapp_msg_param	String	Parameters to be inserted into the WhatsApp message template, provided as a JSON-formatted string.

Sender_Info


Parameter	Type	Description
user_id	Integer	The ID of the internal extension user in the session.
user_no	String	The identifier of the user in the session. For internal extension user, this parameter returns the extension number. For Third-party message analytics platform, this parameter returns a fixed value `api`. For external customer, this parameter returns the ID or phone number of the customer.
user_type	Integer	User type. `1`: Extension user. `2`: SMS user. `3`: WhatsApp user. `4`: Facebook user. `5`: Live Chat user. `8`: Message campaign recipient. `9`: Third-party message analytics platform (transmitted via API)
avatar	String	The ID of the user's avatar.
username	String	User name.

File_Info


Parameter	Type	Description
id	String	The ID of the file.
name	String	The name of the file.
uri	String	The URI for accessing the file.
type	String	File type.
size	Integer	File size (Unit: Byte).

Param


Parameter	Type	Description
Session transfer information
from	String	The name of the member who transfer the message session. For extension user, this parameter returns the caller ID name of the extension. For third-party message analytics platform, this parameter returns a fixed value `Third-Party Message Analytics Platform (Transmitted via API)`.
from_type	String	The type of the member who transfer the message session. `extension`: Extension user. `api`: Third-party message analytics platform.
to	String	The name of the transfer destination. For internal extension user, this parameter returns the extension number. For message queue, this parameter is not returned. For Third-party message analytics platform, this parameter returns a fixed value `api`.
to_id	Integer	The ID of the transfer destination. For internal extension user / third-party message analytics platform, this parameter returns the system-assigned sequence ID of the session member. For message queue, this parameter returns the unique ID of the message queue.
to_no	String	The identifier of the transfer destination. For internal extension user, this parameter returns the extension number. For message queue, this parameter is not returned. For Third-party message analytics platform, this parameter returns a fixed value `api`.
to_type	String	The type of the transfer destination. `extension`: Extension user. `queue`: Message queue. `api`: Third-party message analytics platform.
Call information (Applicable to Live Chat session only)
from	String	The name of the member who initiate the call. For internal extension user, this parameter returns the caller ID name of the extension. For external customer, this parameter returns a fixed value `Website Visitor`.
to	String	The name of the called member. For internal extension user, this parameter returns the caller ID name of the extension. For external customer, this parameter returns a fixed value `Website Visitor`.
to_type	Integer	The type of the member who was called. `1`: Extension user. `5`: Live Chat user (namely the website visitor).
to_member_id	Integer	The system-assigned sequence ID of the session member who was called.
cdr_uid	String	The unique ID of the CDR.
duration	String	Call duration.

Examples

Request example

Query the messages in a Live Chat session (ID: 2874).

GET /openapi/v1.0/message/get?page_size=10&access_token=d8lxvXmhnvMoqw79pUfsdJXyHal6jqIT&id=2874 HTTP/1.1

Host: yeastardocs.example.yeastarcloud.com

Response example

HTTP/1.1 200 OK
{
    "errcode": 0,
    "errmsg": "SUCCESS",
    "data": {
        "session_id": 2874,
        "records": [
            {
                "session_id": 2874,
                "msg_id": 9263,
                "delivery_status": 1,
                "sender": {
                    "user_id": 0,
                    "user_no": "1cc0546496ae42eabf50a54a97fff976",
                    "user_type": 5,
                    "avatar": "",
                    "username": "Website Visitor"
                },
                "msg_type": 7,
                "msg_body": "The session has been closed by visitor.",
                "msg_files": "",
                "send_time": 1753238892,
                "param": "",
                "send_error": "",
                "send_error_msg": "",
                "tag": "",
                "receive_time": 1753238892,
                "whatsapp_msg_param": "",
                "msg_kind": 0
            },
            {
                "session_id": 2874,
                "msg_id": 9211,
                "delivery_status": 1,
                "sender": {
                    "user_id": 39,
                    "user_no": "59996",
                    "user_type": 1,
                    "avatar": "HEEsqLBtF2VJ4wV85f2ef07f-15ab-4e62-bffb-1200a54a3209",
                    "username": "Jane Smith"
                },
                "msg_type": 6,
                "msg_body": "Jane Smith has transferred the session to Tech Support queue.",
                "msg_files": "",
                "send_time": 1753232835,
                "param": "{\"from\":\"Jane Smith\",\"to\":\"Tech Support queue\",\"to_id\":6,\"to_type\":\"queue\"}",
                "send_error": "",
                "send_error_msg": "",
                "tag": "",
                "receive_time": 1753232835,
                "whatsapp_msg_param": "",
                "msg_kind": 0
            },
            {
                "session_id": 2874,
                "msg_id": 9209,
                "delivery_status": 1,
                "sender": {
                    "user_id": 39,
                    "user_no": "59996",
                    "user_type": 1,
                    "avatar": "HEEsqLBtF2VJ4wV85f2ef07f-15ab-4e62-bffb-1200a54a3209",
                    "username": "Jane Smith"
                },
                "msg_type": 8,
                "msg_body": "Jane Smith initiates a call to the Website Visitor. Call duration: 00:05:00. CDR ID: 20250723090642A9FDF.",
                "msg_files": "",
                "send_time": 1753232811,
                "param": "{\"from\":\"Jane Smith\",\"to\":\"Website Visitor\",\"to_type\":5,\"to_member_id\":10832,\"cdr_uid\":\"20250723090642A9FDF\",\"duration\":\"00:05:00\"}",
                "send_error": "",
                "send_error_msg": "",
                "tag": "",
                "receive_time": 1753232811,
                "whatsapp_msg_param": "",
                "msg_kind": 0
            },
            {
                "session_id": 2874,
                "msg_id": 9208,
                "delivery_status": 1,
                "sender": {
                    "user_id": 0,
                    "user_no": "1cc0546496ae42eabf50a54a97fff976",
                    "user_type": 5,
                    "avatar": "",
                    "username": "Website Visitor"
                },
                "msg_type": 8,
                "msg_body": "Website Visitor initiates a call to the Jane Smith. Call duration: 00:03:02. CDR ID: 20250723090632258BB.",
                "msg_files": "",
                "send_time": 1753232798,
                "param": "{\"from\":\"Website Visitor\",\"to\":\"Jane Smith\",\"to_type\":1,\"to_member_id\":10833,\"cdr_uid\":\"20250723090632258BB\",\"duration\":\"00:03:02\"}",
                "send_error": "",
                "send_error_msg": "",
                "tag": "",
                "receive_time": 1753232798,
                "whatsapp_msg_param": "",
                "msg_kind": 0
            },
            {
                "session_id": 2874,
                "msg_id": 9207,
                "delivery_status": 1,
                "sender": {
                    "user_id": 39,
                    "user_no": "59996",
                    "user_type": 1,
                    "avatar": "HEEsqLBtF2VJ4wV85f2ef07f-15ab-4e62-bffb-1200a54a3209",
                    "username": "Jane Smith"
                },
                "msg_type": 5,
                "msg_body": "Jane Smith picked up the session from message queue Customer Query queue",
                "msg_files": "",
                "send_time": 1753232778,
                "param": "{\"from\":\"Customer Query queue\",\"from_id\":4,\"to\":\"Jane Smith\"}",
                "send_error": "",
                "send_error_msg": "",
                "tag": "",
                "receive_time": 1753232778,
                "whatsapp_msg_param": "",
                "msg_kind": 0
            },
            {
                "session_id": 2874,
                "msg_id": 9206,
                "delivery_status": 1,
                "sender": {
                    "user_id": 0,
                    "user_no": "1cc0546496ae42eabf50a54a97fff976",
                    "user_type": 5,
                    "avatar": "",
                    "username": "Website Visitor"
                },
                "msg_type": 0,
                "msg_body": "I'm not receiving email notifications from your system. Can you check this for me?",
                "msg_files": "",
                "send_time": 1753232747,
                "param": "",
                "send_error": "",
                "send_error_msg": "",
                "tag": "",
                "receive_time": 1753232747,
                "whatsapp_msg_param": "",
                "msg_kind": 0
            }
        ]
    }
}