查询多个消息会话的消息

同时查询多个消息会话中的消息。

请求 URL

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

请求参数

参数 是否必填 类型 说明
page_size 是 Integer 定义每页显示几项查询结果。
ids 是 String 消息会话的唯一 ID。
注：

响应参数

参数 类型 说明
errcode Integer 返回错误码。
  • 0：请求成功。
  • 非零值：请求失败。
注： 更多错误码和错误信息说明，请参见 错误码 & 错误信息。
errmsg String 返回信息。
  • SUCCESS：请求成功。
  • FAILURE：请求失败。
data Array<Messages> 查询到的消息的详情。
Messages
参数 类型 说明
session_id Integer 消息会话的唯一 ID。
records Array<Msg_Record> 消息记录。
Msg_Record
参数 类型 说明
session_id Integer 消息会话的唯一 ID。
msg_id Integer 消息的唯一 ID。
delivery_status Integer 消息发送状态。
  • 0：发送中。
  • 1：发送成功。
  • 2：发送失败。
sender Object<Sender_Info> 发送者的信息。
msg_kind Integer 消息的类别。
  • 0：普通消息。
  • 1：WhatsApp 模板消息。
msg_type Integer 消息内容的类型。
  • 0：用户消息。
  • 1：会话被转移的系统消息 (转移至分机或第三方分析平台)。
  • 2：会话被手动关闭的系统消息。
  • 3：会话被自动关闭的系统消息。
  • 4：不支持的消息类型的系统消息。
  • 5：会话被接管的系统消息。
  • 6：会话被转移的系统消息 (转移至消息队列)。
  • 7：访客手动关闭会话的系统消息。
  • 8：会话中通话相关的系统消息。
msg_body String 消息内容。
msg_files String 消息文件的信息，以 JSON 字符串格式返回。

该字符串为由 File_Info 对象组成的数组 (JSON 格式)。更多详情，请参见 File_Info 表格。
send_time Integer 消息发送时间的 Unix 时间戳 (秒)。
receive_time Integer 消息接收时间的 Unix 时间戳 (秒)。
param String 附加的消息相关参数，以 JSON 字符串格式返回。

此参数根据 msg_type 返回不同信息。

  • 若 msg_type 为 1 或 6，此参数返回会话转移信息。
  • 若 msg_type 为 8，此参数返回通话信息。

更多详情，请参见 Param 表格。
send_error String 消息发送失败的错误类型。
  • invalid_webhook_request：无效请求。
  • unsupported_callback_type：不支持的回调类型。
  • resource_not_found：资源不存在。
  • invalid_did_number：DID 号码无效。
  • auth_fail：鉴权失败。
  • auth_not_exit：鉴权信息不存在。
  • request_fail：请求失败。
  • send_fail：发送失败。
  • exceeds_size_limit：消息内容超过大小限制。
  • too_many_request：请求过多。
  • unsupport_media_type：不支持的媒体类型。
  • invalid_param：无效参数。
  • invalid_phone_number：电话号码无效。
  • exceeds_time_limit：超过时间限制。
  • service_unavailable：第三方服务不可用。
  • service_error：第三方服务错误。
  • unknown_error：位置错误。
  • template_not_exist：WhatsApp 模板不存在。
  • msg_exceed：WhatsApp 消息内容文本超过限制。
send_error_msg String 消息发送失败时第三方那个返回的错误提示信息。
tag String 分配给 Facebook 消息的标签，用于指示其类别或用途。
  • ACCOUNT_UPDATE：账户相关更新。
  • CONFIRMED_EVENT_UPDATE：确认事件更新。
  • HUMAN_AGENT：由人工坐席发送的消息。
  • POST_PURCHASE_UPDATE：交易完成后的最新动态。
whatsapp_msg_param String

消息参数，其中包含要填充到 WhatsApp 消息模板中的参数，为 JSON 字符串格式。
Sender_Info
参数 类型 说明
user_id Integer 会话中内部分机用户的 ID。
user_no String 会话中用户的标识。
  • 对于分机用户，此参数返回分机号码。
  • 对于第三方分析平台，此参数返回固定值 api。
  • 对于外部客户，此参数返回客户的 ID 或电话号码。
user_type Integer 用户类型。
  • 1：分机用户。
  • 2：SMS 用户。
  • 3：WhatsApp 用户。
  • 4：Facebook 用户。
  • 5：在线咨询 (Live Chat) 用户。
  • 8：消息群发活动收信人。
  • 9：第三方分析平台 (消息通过二次开发接口传递)。
avatar String 用户头像的 ID。
username String 用户名。
File_Info
参数 类型 说明
id String 文件 ID。
name String 文件名称，
uri String 用于访问文件的 URI。
type String 文件类型。
size Integer 文件大小 (单位：字节)。
Param
参数 类型 说明
会话转移信息
from String 转移消息会话的成员的名称。
  • 若为分机用户，此参数返回用户的分机名称。
  • 若为第三方分析平台，此参数返回固定值 Third-Party Message Analytics Platform (Transmitted via API)。
from_type String 转移消息会话的成员的类型。
  • extension：分机用户。
  • api：第三方分析平台。
to String 消息会话转移目的地的名称。
  • 若为内部分机用户，此参数返回分机号码。
  • 若为消息队列，则不返回此参数。
  • 若为第三方分析平台，此参数返回固定值 api。
to_id Integer 消息会话转移目的地的 ID。
  • 若为内部分机用户 / 第三方分析平台，此参数返回系统分配给会话成员的序列 ID。
  • 若为消息队列，此参数返回消息队列的唯一 ID。
to_no String 消息会话转移目的地的标识。
  • 若为内部分机用户，此参数返回分机号码。
  • 若为消息队列，则不返回此参数。
  • 若为第三方分析平台，此参数返回固定值 api。
to_type String 消息会话转移目的地的类型。
  • extension：分机用户。
  • queue：消息队列。
  • api：第三方分析平台 (消息通过二次开发接口传递)
通话信息 (仅适用于在线咨询会话)
from String 发起通话的成员的名称。
  • 若为内部分机用户，此参数返回用户的分机名称。
  • 若为外部客户，此参数返回固定值 Website Visitor。
to String 被叫成员的名称。
  • 若为内部分机用户，此参数返回用户的分机名称。
  • 若为外部客户，此参数返回固定值 Website Visitor。
to_type Integer 被叫成员的类型。
  • 1：分机用户。
  • 5：在线咨询用户 (即访客)。
to_member_id Integer 系统分配给会话成员的序列 ID，此处返回被叫成员的 ID。
cdr_uid String 通话记录 (CDR) 的唯一 ID。
duration String 通话时长。

示例

请求示例

查询两个消息会话 (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

响应示例

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
                }
            ]
        }
    ]
}