Query Messages in Multiple Message Sessions

Query messages in multiple message sessions simultaneously.

Request URL

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

Request parameters

Parameter Required Type Description
page_size Yes Integer Define how many records per page.
ids Yes String The unique ID(s) of the message sessions.
Note:

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 Array<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 record.
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 two message sessions (ID: 2874 & 3086).

GET /openapi/v1.0/message/query?page_size=10&access_token=ct7tuz0q8QE6DTNdPUXCQW3N3IYj2SPX&ids=2874,3086 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
            }
        ]
    },
    {
            "session_id": 3086,
            "records": [
                {
                    "session_id": 3086,
                    "msg_id": 10322,
                    "delivery_status": 1,
                    "sender": {
                        "user_id": 39,
                        "user_no": "59996",
                        "user_type": 1,
                        "avatar": "HEEsqLBtF2VJ4wV85f2ef07f-15ab-4e62-bffb-1200a54a3209",
                        "username": "Jane Smith"
                    },
                    "msg_type": 0,
                    "msg_body": "{\"id\":392,\"template_id\":\"1293546285747227\",\"name\":\"campaign_notification\",\"parameter_format\":\"NAMED\",\"language\":\"en\",\"category\":\"MARKETING\",\"sub_category\":\"CUSTOM\",\"omnichannel_id\":3,\"components\":[{\"type\":\"HEADER\",\"format\":\"IMAGE\"},{\"type\":\"BODY\",\"text\":\"Hello! 👋\\n\\nAs a valued VIP member, we’re excited to share a special DISCOUNT with you! 🎁\\nEnjoy 20% OFF for all products —available until 2025/9/30.\\n\\nIf you have any questions or want to redeem your offer, simply reply to this message or contact our team.\\n\\nThank you for choosing Sale_Mart! 💙\"},{\"type\":\"BUTTONS\",\"buttons\":[{\"type\":\"FLOW\",\"text\":\"Redeem Offer\",\"flow_id\":657693363952373,\"flow_action\":\"NAVIGATE\",\"navigate_screen\":\"SIGN_UP\"},{\"type\":\"URL\",\"text\":\"Visit website\",\"url\":\"https://test.com/\"},{\"type\":\"VOICE_CALL\",\"text\":\"Contact us\"}]}]}",
                    "msg_files": "",
                    "send_time": 1758591592,
                    "param": "",
                    "send_error": "",
                    "send_error_msg": "",
                    "tag": "",
                    "receive_time": 1758591592,
                    "whatsapp_msg_param": "{\"id\":392,\"template_id\":\"1293546285747227\",\"name\":\"campaign_notification\",\"language\":{\"code\":\"en\"},\"components\":[{\"type\":\"HEADER\",\"parameters\":[{\"type\":\"IMAGE\",\"file_list\":[{\"id\":\"ee6b4017010b401c88a02aeb9cfcd4d2\",\"name\":\"images.jpg\",\"uri\":\"20250923/ee6b4017010b401c88a02aeb9cfcd4d2\",\"type\":\"image/jpeg\",\"size\":7163}]}]},{\"type\":\"BODY\",\"parameters\":[{\"type\":\"TEXT\",\"text\":\"\",\"parameter_name\":\"customertier\"},{\"type\":\"TEXT\",\"text\":\"\",\"parameter_name\":\"offertype\"},{\"type\":\"TEXT\",\"text\":\"\",\"parameter_name\":\"offerdetails\"},{\"type\":\"TEXT\",\"text\":\"\",\"parameter_name\":\"expirydate\"},{\"type\":\"TEXT\",\"text\":\"11\",\"parameter_name\":\"companyname\"}]},{\"type\":\"BUTTONS\",\"parameters\":[{\"type\":\"FLOW\",\"text\":\"\"},{\"type\":\"URL\",\"text\":\"\"},{\"type\":\"VOICE_CALL\",\"text\":\"\"}]}],\"parameter_format\":\"NAMED\"}",
                    "msg_kind": 1
                },
                {
                    "session_id": 3086,
                    "msg_id": 10321,
                    "delivery_status": 1,
                    "sender": {
                        "user_id": 39,
                        "user_no": "59996",
                        "user_type": 1,
                        "avatar": "HEEsqLBtF2VJ4wV85f2ef07f-15ab-4e62-bffb-1200a54a3209",
                        "username": "Jane Smith"
                    },
                    "msg_type": 0,
                    "msg_body": "Your order is scheduled to be delivered tomorrow. You’ll receive a notification once it’s out for delivery.",
                    "msg_files": "",
                    "send_time": 1758591565,
                    "param": "",
                    "send_error": "",
                    "send_error_msg": "",
                    "tag": "",
                    "receive_time": 1758591565,
                    "whatsapp_msg_param": "",
                    "msg_kind": 0
                },
                {
                    "session_id": 3086,
                    "msg_id": 10319,
                    "delivery_status": 1,
                    "sender": {
                        "user_id": 0,
                        "user_no": "+8618159207827",
                        "user_type": 3,
                        "avatar": "",
                        "username": ""
                    },
                    "msg_type": 0,
                    "msg_body": "Thanks! Can you tell me when it will be delivered?",
                    "msg_files": "",
                    "send_time": 1758549891,
                    "param": "",
                    "send_error": "",
                    "send_error_msg": "",
                    "tag": "",
                    "receive_time": 1758549889,
                    "whatsapp_msg_param": "",
                    "msg_kind": 0
                },
                {
                    "session_id": 3086,
                    "msg_id": 10318,
                    "delivery_status": 1,
                    "sender": {
                        "user_id": 39,
                        "user_no": "59996",
                        "user_type": 1,
                        "avatar": "HEEsqLBtF2VJ4wV85f2ef07f-15ab-4e62-bffb-1200a54a3209",
                        "username": "Jane Smith"
                    },
                    "msg_type": 0,
                    "msg_body": "Thank you. I’m checking the details for order 123456 now.",
                    "msg_files": "",
                    "send_time": 1758549851,
                    "param": "",
                    "send_error": "",
                    "send_error_msg": "",
                    "tag": "",
                    "receive_time": 1758549848,
                    "whatsapp_msg_param": "",
                    "msg_kind": 0
                },
                {
                    "session_id": 3086,
                    "msg_id": 10317,
                    "delivery_status": 1,
                    "sender": {
                        "user_id": 0,
                        "user_no": "+8618159207827",
                        "user_type": 3,
                        "avatar": "",
                        "username": ""
                    },
                    "msg_type": 0,
                    "msg_body": "Sure, my order number is 123456.",
                    "msg_files": "",
                    "send_time": 1758549724,
                    "param": "",
                    "send_error": "",
                    "send_error_msg": "",
                    "tag": "",
                    "receive_time": 1758549722,
                    "whatsapp_msg_param": "",
                    "msg_kind": 0
                },
                {
                    "session_id": 3086,
                    "msg_id": 10316,
                    "delivery_status": 1,
                    "sender": {
                        "user_id": 39,
                        "user_no": "59996",
                        "user_type": 1,
                        "avatar": "HEEsqLBtF2VJ4wV85f2ef07f-15ab-4e62-bffb-1200a54a3209",
                        "username": "Jane Smith"
                    },
                    "msg_type": 0,
                    "msg_body": "Hello! I'd be happy to assist you. Could you please provide your order number?",
                    "msg_files": "",
                    "send_time": 1758549548,
                    "param": "",
                    "send_error": "",
                    "send_error_msg": "",
                    "tag": "",
                    "receive_time": 1758549547,
                    "whatsapp_msg_param": "",
                    "msg_kind": 0
                },
                {
                    "session_id": 3086,
                    "msg_id": 10315,
                    "delivery_status": 1,
                    "sender": {
                        "user_id": 0,
                        "user_no": "+8618159207827",
                        "user_type": 3,
                        "avatar": "",
                        "username": ""
                    },
                    "msg_type": 0,
                    "msg_body": "Hi, I need help with my recent order.",
                    "msg_files": "",
                    "send_time": 1758549500,
                    "param": "",
                    "send_error": "",
                    "send_error_msg": "",
                    "tag": "",
                    "receive_time": 1758549496,
                    "whatsapp_msg_param": "",
                    "msg_kind": 0
                }
            ]
        }
    ]
}