搜索特定消息会话

搜索特定目标 (分机用户或第三方分析平台) 的消息会话。

请求 URL

GET {base_url}/{api_path}/message_session/search?access_token={access_token}

请求参数

参数 是否必填 类型 说明
page_size 是 Integer 定义每页显示几项查询结果。
user_type 是 Integer 查询目标的类型。
取值范围：
  • 1：分机用户
  • 9：第三方分析平台。
user_no 否 String 查询目标的标识。
取值范围：
  • 若 user_type 设为 1，则此参数必填，用于指定具体的分机号码。
  • 若 user_type 设为 9，则将此参数设为 api 或留空。
collection 否 String 消息会话的合集。
取值范围：
  • all：查询所有会话 (包括群发活动会话和非群发活动会话)。
  • campaign：仅查询群发活动会话。
注： 若未传递或留空此参数，则仅返回非群发活动会话。
first_msg_id 否 Integer 要查询的首条消息的 ID。
注： 此参数可用于分页查询。如需获取下一页数据，请将此参数设置为上一个查询结果中，最后一个消息会话的最后一条消息的 ID (last_msg_id)。
is_archived 否 Integer 根据存档状态筛选消息会话。
取值范围：
  • 0：仅查询未存档的消息会话。
  • 1：仅查询已存档的消息会话。
  • 2：查询所有消息会话 (包括已存档和未存档的会话)。
is_closed 否 Integer 根据关闭状态筛选消息会话。

取值范围：

  • 0：仅查询未关闭的消息会话。
  • 1：仅查询已关闭的消息会话。
  • 2：查询所有消息会话 (包括已关闭和未关闭的会话)。
is_pickup 否 Integer 根据接管状态筛选消息会话。
取值范围：
  • 0：查询所有消息会话。
  • 1：仅查询已接管的消息会话。
  • 2：仅查询未接管的消息会话。
search_value 否 String 搜索关键字。

响应参数

参数 类型 说明
errcode Integer 返回错误码。
  • 0：请求成功。
  • 非零值：请求失败。
注： 更多错误码和错误信息说明，请参见 错误码 & 错误信息。
errmsg String 返回信息。
  • SUCCESS：请求成功。
  • FAILURE：请求失败。
list Array<Session_Info> 消息会话的信息。
Session_Info
参数 类型 说明
id Integer 消息会话的唯一 ID。
type String 消息会话的类型。
  • sms：SMS 会话。
  • whatsapp：WhatsApp 会话。
  • facebook：Facebook 会话。
  • livechat：在线咨询会话。
is_close Integer 消息会话是否已关闭。
  • 0：未关闭。
  • 1：已关闭。
is_archived Integer 消息会话是否已存档。
  • 0：未存档。
  • 1：已存档。
to Object<Customer_Info> 消息会话中外部客户的信息。
expire Integer 距离接收到外部入站消息后 24 小时会话超时的剩余时间 (秒)。
注： 此参数仅在 WhatsApp 会话和 Facebook 会话信息中返回数值。
  • -1：永不超时。
  • 0：已超时。
  • 大于 0 的值：距离超时剩余的秒数。
did_number String 消息会话使用的 DID 号码。
origin String 消息会话的来源。
  • campaign：该会话由消息群发活动创建。
注： 若返回为空，则表示该会话由分机用户或第三方分析平台通过 API 创建。
collection String 消息会话的合集。
  • campaign：群发活动会话。
注： 若返回为空，则表示该会话为非群发活动会话。
last_msg_id Integer 消息会话中最后一条消息的 ID。
queue_id Integer 处理该会话消息的消息队列的 ID。
pickup_member_id Integer 从消息队列中接管消息会话的坐席的 ID。
注： 若 queue_id 有返回信息，且此参数返回为 0，则表示消息会话仍在队列中，未被坐席接管。
Customer_Info
参数 类型 说明
user_id Integer 消息会话中内部用户的 ID。
注： 此参数始终返回 0。
user_no String 外部客户的 ID 或电话号码。
user_type Integer 外部客户的类型。
  • 2：SMS 用户。
  • 3：WhatsApp 用户。
  • 4：Facebook 用户。
  • 5：在线咨询 (Live Chat) 用户。
  • 8：消息群发活动收信人。
avatar String 外部客户头像的 ID。
username String 外部客户用户名。

示例

请求示例

使用客户的 Facebook ID，搜索分机 59996 的相关会话。

GET /openapi/v1.0/message_session/search?access_token=6Un1hR5FL8L2sP5IlM43ynnemjseR7EO&page_size=10&user_type=1&user_no=59996&search_value=24982205021378108 HTTP/1.1

Host: yeastardocs.example.yeastarcloud.com

响应示例

HTTP/1.1 200 OK
{
    "errcode": 0,
    "errmsg": "SUCCESS",
    "list": [
        {
            "id": 3069,
            "type": "facebook",
            "is_close": 0,
            "is_archived": 0,
            "to": {
                "user_id": 0,
                "user_no": "24982205021378108",
                "user_type": 4,
                "avatar": "ICPiaN3BIrvKHTJkl1snmhh9H4ZcbQYTdz8OTBOVN_4",
                "username": "William Smith"
            },
            "expire": 19751,
            "did_number": "197745966764205",
            "origin": "",
            "collection": "",
            "last_msg_id": 10253,
            "queue_id": 0,
            "pickup_member_id": 0
        }
    ]
}