APIs V2.0

Access Token

您需要在【设置 / 开发者 / APIs】中获取工作台的 Access Token，后续调用以下 APIs 时都需要使用 Token。目前 Token 的有效期是永久，重复获取将导致上次获取的 Token 失效。

对话

对话是在线客服与顾客沟通的载体。顾客或客服发送消息后，会以对话的形式显示在对话页。

对话模型

查询单个对话

curl https://api.meiqia.com/v1/conversations/<conv_id>

请求

请注意：【access_token】和【app_id、sign】只需要任选其一即可完成请求。

响应

请求成功后，响应会包含相应对话的对话模型。

查询多个对话（V1.0）

您可以从对话结束时间的维度，查询某个时间段的多个对话。每次查询时，接口规则：

• offset 对话的偏移量。例如，第一次查询时 offset 是 0，limit 是10，那么第二次查询时，offset 要设置为 10，则能查询剩余的对话。
• limit 每次请求查询的对话数，上限是 20，如果超过 20，请求将失败。

curl https://api.meiqia.com/v1/conversations

请求

请注意：【access_token】和【app_id、sign】只需要任选其一即可完成请求。

响应

请求成功后，响应会包含相应对话的对话模型，对话按 conv_id 升序排列。

查询多个对话（V2.0）

V2.0 在 V1.0 的基础上提高了安全性，优化了批量查询的逻辑。您可以从对话结束时间维度，查询某个时间段的多个对话，每次查询时，接口规则：

• page_token 查询时使用，初始时设置为 page_token = “”，之后每次设置request.page_token 等于上次 response.next_page_token；当某一次 response.next_page_token == “” 时，说明对话已被全部拉取，查询结束。

• limit 每次请求查询的对话数，上限是 20，如果超过 20，请求将失败。

curl https://api.meiqia.com/v2/conversations

请求

请注意：【access_token】和【app_id、sign】只需要任选其一即可完成请求。

响应

请求成功后，响应会包含相应对话的对话模型，顾客按 conv_id 升序排列。

响应中会带有 next_page_token ，用于做下一次请求的 page_token。

顾客

顾客是通过各个对话渠道，与客服进行沟通的人。如果顾客拥有了电话号码、微信、QQ、微博四种联系方式里其中一个时，您可以通过接口访问到该顾客资源。

顾客模型

顾客模型包含顾客的自定义参数，响应中不会包含值为空的自定义参数。

根据创建时间查询多个顾客

您可以从顾客创建时间的维度，查询某个时间段的多个顾客。每次查询时，接口规则：

• page_token 查询时使用，初始时设置为 page_token = “”，之后每次设置request.page_token 等于上次 response.next_page_token；当某一次 response.next_page_token == “” 时，说明顾客已被全部拉取，查询结束。
• limit 每次请求查询的顾客数，上限是 20，如果超过 20，请求将失败。

curl https://api.meiqia.com/v2/clients

请求

请注意：【access_token】和【app_id、sign】只需要任选其一即可完成请求。

响应

请求成功后，响应会包含相应顾客的顾客模型，顾客按 ticket_id 升序排列。

响应中会带有 next_page_token ，用于做下一次请求的 page_token。

根据最后更新时间查询多个顾客

您可以从顾客最后更新时间维度，查询某个时间段的多个顾客。每次查询时，接口规则：

• page_token 查询时使用，初始时设置为 page_token = “”，之后每次设置request.page_token 等于上次 response.next_page_token；当某一次 response.next_page_token == “” 时，说明顾客已被全部拉取，查询结束。
• limit 每次请求查询的顾客数，上限是 20，如果超过 20，请求将失败。

curl https://api.meiqia.com/v2/clients/updated

请求

请注意：【access_token】和【app_id、sign】只需要任选其一即可完成请求。

响应

请求成功后，响应会包含相应顾客的顾客模型，顾客按 track_id 升序排列。

响应中会带有 next_page_token ，用于做下一次请求的 page_token。

留言

留言模型

查询单条留言

curl https://api.meiqia.com/v1/tickets/<track_id>

请求

请注意：【access_token】和【app_id、sign】只需要任选其一即可完成请求。

响应

请求成功后，响应会包含相应留言的留言模型。

查询多个留言

您可以从留言创建时间维度，查询某个时间段的多个留言。每次查询时，接口规则：

• offset 留言的偏移量。例如，第一次查询时 offset 是 0，limit 是10，那么第二次查询时，offset 要设置为 10，则能查询剩余的留言。
• limit 每次请求查询的留言数，上限是 20，如果超过 20，请求将失败。

curl https://api.meiqia.com/v1/tickets

请求

请注意：【access_token】和【app_id、sign】只需要任选其一即可完成请求。

响应

请求成功后，响应会包含相应留言的留言模型，留言按 ticket_id 升序排列。

报表

在线时长

GET /unified-api/datagateway/v1/reports/agent_online_stats

{
    "rows": [
        {
            "agent_id": 10004906, // 客服ID
            "agent_name": "超级管理员x", // 客服名称
            "group_id": 4372, // 客服组ID
            "group_name": "默认分组", // 客服组名称
            "work_num": "", // 工号
            "online_offduty": 0, // 隐身时长
            "online_onduty": 0, // 在线时长
            "pns_onduty": 0, // 推送开启时长
            "pns_offduty": 0, // 推送关闭时长
            "offline": 50400 // 离线时长
        }
    ]
}

客服评价

GET /unified-api/datagateway/v1/reports/agent_evaluation

{
    "rows": [
        {
            "agent_id": 10004906,
            "agent_name": "超级管理员x",
            "group_id": 4372,
            "group_name": "默认分组",
            "work_num": "",
            "conv_cnt": 0, // 对话数
            "effective_conv_cnt": 0, // 有效对话数
            "good_conv_cnt": 0, // 好评数
            "medium_conv_cnt": 0, // 中评数
            "bad_conv_cnt": 0, // 差评数
            "solveed_cnt": 0, // 解决数
            "unsolved_cnt": 0 // 未解决数
        }
    ]
}

客服服务量

GET /unified-api/datagateway/v1/reports/agent_service

{
    "rows": [
        {
            "agent_id": 10004906,
            "agent_name": "超级管理员x",
            "group_id": 4372,
            "group_name": "默认分组",
            "work_num": "",
            "conv_cnt": 0, // 对话数
            "effective_conv_cnt": 0, // 有效对话数
            "missed_conv_cnt": 0, // 遗漏对话数
            "delayed_conv_cnt": 0, // 延误对话数
            "msg_cnt": 0, // 消息数
            "duration_time": 0, // 对话持续时长
            "conv_first_response_wait_time": 0, // 对话首次响应时长
            "agent_first_response_wait_time": 0, // 客服首次响应时长
            "avg_response_wait_time": 0, // 平均响应时长
            "gold_conv_cnt": 0, // 金牌对话数
            "silver_conv_cnt": 0, // 银牌对话数
            "bronze_conv_cnt": 0, // 铜牌对话数
            "nograde_conv_cnt": 0, // 无评级对话数
            "good_conv_cnt": 0, // 好评数
            "medium_conv_cnt": 0, // 中评数
            "bad_conv_cnt": 0, // 差评数
            "clues_cnt": 0, // 线索数
            "remark_cnt": 0, // 备注数
            "transfer_in_cnt": 0, // 被动转接数
            "transfer_out_cnt": 0, // 主动转接数
            "clue_conv_cnt": 0 // 线索对话数
        }
    ]
}

错误提示

请求 APIs 出错时美洽会返回错误码以及响应的错误提示。