帮助中心,常见问题与用户指南

API 目前不开放

请注意，API 功能目前仅有限开放。此文档仅供已开通 API 的用户参考使用。

对话

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

对话模型

参数	类型	说明
enterprise_id	Integer	来鼓定义的企业唯一标识
dev_client_id	String	第三方系统定义并传递给来鼓的顾客唯一标识
visitor_tags	List	顾客的顾客标签
client_id	Integer	第三方系统定义并传递给来鼓的顾客唯一标识
client_info	Object	顾客的详细信息
agent_account	String	客服的账号邮箱
agent_name	String	客服的名字
agent_ID	String	来鼓定义的客服唯一标识
agent_nick_name	String	客服的昵称
group_id	String	来鼓定义的客服组 ID
group_name	String	客服组的名称
conv_id	Integer	来鼓定义的对话唯一标识
advertiser_id	String	广告ID
advertiser_name	String	广告名称
campaign_id	String	计划ID
campaign_name	String	计划名称
creativity_id	String	创意ID
creativity_name	String	创意名称
conv_start_tm	String	对话的创建时间
conv_end_tm	String	对话的结束时间
conv_first_resp_wait_in_secs	Integer	对话的首次响应时长，单位为秒
conv_content	List	对话的消息
conv_agent_msg_count	String	客服在对话中发送的消息数
conv_visitor_msg_count	String	顾客在对话中发送的消息数
conv_quality_grade	String	对话的评级
conv_leads	String	对话中收集的线索
conv_tags	String	对话的对话标签
summary_content	String	对话小结的内容
summary_update_at	String	对话小结的最后更新时间
source_type	String	对话的访问来源类型
source_field	String	对话的访问来源的值
agent_resp_duration	String	客服平均响应时长
effective	String	对话是有效对话还是无效对话
missed	String	对话是否为遗漏对话
converse_duration	String	对话的持续时长
app_name	String	部署了 SDK 的 App 名称，SDK 渠道特有
main_channel	String	对话渠道
sub_channel	String	对话子渠道

Conversation Object

查询单个对话

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

请求

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

参数	能否为空	说明
enterprise_id	不能	来鼓定义的企业唯一标识
app_id	不能	来鼓定义的工作台唯一标识
sign	不能	来鼓定义的工作台访问签名
conv_id	不能	来鼓定义的对话ID

请求的 Path 需要带上以上参数

响应

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

查询多个对话（V1.0）

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

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

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

请求

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

参数	能否为空	说明
enterprise_id	不能	来鼓定义的企业唯一标识
app_id	不能	来鼓定义的工作台唯一标识
sign	不能	来鼓定义的工作台访问签名
offset	不能	对话的偏移量
limit	不能	每次请求拉取对话的最大数量
conv_start_from_tm	不能	对话时间段的开始时间
conv_start_to_tm	不能	对话时间段的结束时间

请求的 Path 需要带上以上参数

响应

请求成功后，响应会包含相应对话的对话模型，对话按 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.laigu.com/v2/conversations

请求

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

参数	能否为空	说明
X-App-ID	不能	来鼓定义的工作台唯一标识
X-Sign	不能	来鼓定义的工作台访问签名

请求的 Header 需要带上以上参数

参数	能否为空	说明
enterprise_id	不能	来鼓定义的企业唯一标识
limit	不能	每次请求拉取的最大数量
from_tm	不能	对话结束时间段开始时间，可以精确到秒或微秒 us
to_tm	不能	对话结束时间段结束时间，可以精确到秒或微秒 us
page_token	不能	查询使用的 token

请求的 Path 需要带上以上参数

响应

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

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

访客 #

访客是通过各个对话渠道，与客服进行沟通的人，您可以通过接口访问到该访客资源

访客模型 #

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

参数	类型	说明
advertiser_id	String	广告ID
advertiser_name	String	广告名称
campaign_id	String	计划ID
campaign_name	String	计划名称
creativity_id	String	创意ID
creativity_name	String	创意名称
source	String	来源：redbook-小红书，douyin-抖音
sub_source	String	用户来源子渠道ID
sub_source_name	String	用户来源子渠道名称，例如来源小红书账号名称
customer_channel	String	企业微信提供的字段，用于匹配用户
name	String	访客的姓名
age	String	访客的年龄
gender	String	访客的性别
avatar	String	头像
qq	String	访客的 QQ
tel	String	访客的电话号码
weixin	String	微信号
address	String	访客的地址
comment	String	访客的备注
created_on	String	创建时间
updated_on	String	更新时间
track_id	String	来鼓定义的顾客唯一标识
tags	Array	标签ID
tags_detail	Json	标签明细，key为标签ID，value为标签名称
incoming_note_id	String	来源笔记的ID
incoming_note_title	String	来源笔记的标题

访客event枚举

cus.upsert 访客更新

访客更新示例

{
    "id": "sub_2025eef64324f49b2693970043e558d6_1753767660_1088",
    "event": "cus.upsert",
    "enterprise_token": "b6bd473a003a99216d3f63cc329869b3",
    "created_at": 1753767660,
    "body": {
        "custom": {
            "自定义字段1": [
                "checkbox1",
                "checkbox2"
            ],
            "自定义字段2": "2024-09-20T09:23:12.916Z"
        },
        "updated_on": "2025-07-29T05:40:58.46Z",
        "created_on": "2025-07-29T05:40:58.46Z",
        "advertiser_id": "111",
        "advertiser_name": "微亿璀璨（来鼓）1",
        "campaign_id": "222",
        "campaign_name": "客资收集_计划2",
        "creativity_id": "333",
        "creativity_name": "客资收集_计划3",
        "source": "redbook",
        "sub_source": "62b1fcaf000000001b0260c1",
        "sub_source_name": "小来鼓软件",
        "customer_channel": "",
        "tel": "18827773666",
        "weixin": "test_wx",
        "address": "test_address",
        "comment": "测试备注",
        "track_id": "2ldmFOXB7aDMXHSs7upv5PMZsa0",
        "qq": "",
        "name": "小黄鸭",
        "age": "19",
        "gender": "F",
        "avatar": "https://laigu-tenant-upload-qa.oss-cn-zhangjiakou.aliyuncs.com/widget/104/0ZIX/gaMZnhi9PwwQjIrHh5kd.jpg",
        "wecom_link_id": "",
        "wecom_link_name": "",
        "tags": [
            2285,
            1519,
            1520
        ],
        "tags_detail": {
            "1519": "已留资",
            "1520": "跟进中",
            "2285": "测试"
        },
        "incoming_note_id": "",
        "incoming_note_title": ""
    }
}

顾客 #

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

顾客模型

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

参数	类型	说明
advertiser_id	String	广告ID
advertiser_name	String	广告名称
campaign_id	String	计划ID
campaign_name	String	计划名称
creativity_id	String	创意ID
creativity_name	String	创意名称
source	String	来源：redbook-小红书，douyin-抖音
sub_source	String	子渠道ID
sub_source_name	String	用户来源子渠道名称，例如来源小红书账号名称
customer_channel	String	企业微信提供的字段，用于匹配用户
name	String	顾客的姓名
age	String	顾客的年龄
gender	String	顾客的性别
avatar	String	头像
qq	String	顾客的 QQ
tel	String	顾客的电话号码
weixin	String	微信号
address	String	顾客的地址
comment	String	顾客的备注
created_on	String	创建时间
updated_on	String	更新时间
enterprise_token	String	来鼓定义的企业唯一标识
track_id	String	来鼓定义的顾客唯一标识
tags	Array	标签ID
tags_detail	Json	标签明细，key为标签ID，value为标签名称
incoming_note_id	String	来源笔记的ID
incoming_note_title	String	来源笔记的标题

顾客event枚举

client.created 顾客创建
client.updated 顾客更新
client.deleted 顾客删除

顾客更新示例

{
    "id": "sub_2025eef64324f49b2693970043e558d6_1753767660_1088",
    "event": "client.updated",
    "enterprise_token": "b6bd473a003a99216d3f63cc329869b3",
    "created_at": 1753767660,
    "client": {
        "custom": {
            "自定义字段1": [
                "checkbox1",
                "checkbox2"
            ],
            "自定义字段2": "2024-09-20T09:23:12.916Z"
        },
        "updated_on": "2025-07-29T05:40:58.46Z",
        "created_on": "2025-07-29T05:40:58.46Z",
        "advertiser_id": "111",
        "advertiser_name": "微亿璀璨（来鼓）1",
        "campaign_id": "222",
        "campaign_name": "客资收集_计划2",
        "creativity_id": "333",
        "creativity_name": "客资收集_计划3",
        "source": "redbook",
        "sub_source": "62b1fcaf000000001b0260c1",
        "sub_source_name": "小来鼓软件",
        "customer_channel": "",
        "tel": "18827773666",
        "weixin": "test_wx",
        "address": "test_address",
        "comment": "测试备注",
        "track_id": "2ldmFOXB7aDMXHSs7upv5PMZsa0",
        "qq": "",
        "name": "小黄鸭",
        "age": "19",
        "gender": "F",
        "avatar": "https://laigu-tenant-upload-qa.oss-cn-zhangjiakou.aliyuncs.com/widget/104/0ZIX/gaMZnhi9PwwQjIrHh5kd.jpg",
        "wecom_link_id": "",
        "wecom_link_name": "",
        "tags": [
            2285,
            1519,
            1520
        ],
        "tags_detail": {
            "1519": "已留资",
            "1520": "跟进中",
            "2285": "测试"
        },
        "incoming_note_id": "",
        "incoming_note_title": ""
    }
}

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

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

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

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

请求

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

参数	能否为空	说明
X-App-ID	不能	来鼓定义的工作台唯一标识
X-Sign	不能	来鼓定义的工作台访问签名

请求的 Header 需要带上以上参数

参数	能否为空	说明
enterprise_id	不能	来鼓定义的企业唯一标识
limit	不能	每次请求拉取的最大数量
from_tm	不能	顾客信息创建时间段开始时间，可以精确到秒或微秒 us
to_tm	不能	顾客信息创建时间段结束时间，可以精确到秒或微秒 us
page_token	不能	查询使用的 token

请求的 Path 需要带上以上参数

响应

请求成功后，响应会包含相应顾客的顾客模型，顾客按 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.laigu.com/v2/clients/updated

请求

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

参数	能否为空	说明
X-App-ID	不能	来鼓定义的工作台唯一标识
X-Sign	不能	来鼓定义的工作台访问签名

请求的 Header 需要带上以上参数

参数	能否为空	说明
enterprise_id	不能	来鼓定义的企业唯一标识
limit	不能	每次请求拉取对话的最大数量
from_tm	不能	顾客信息更新时间段开始时间，可以精确到秒或微秒 us
to_tm	不能	顾客信息更新时间段结束时间，可以精确到秒或微秒 us
page_token	不能	查询使用的 token

请求的 Path 需要带上以上参数

响应

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

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

报表

在线时长

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

请求参数	能否为空	说明
from_tm	不能	开始时间 (yyyy-mm-dd hh-mm-sss)
to_tm	不能	结束时间 (yyyy-mm-dd hh-mm-sss)

Plain Text
{
    “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_service

请求参数	能否为空	说明
from_tm	不能	开始时间 (yyyy-mm-dd hh-mm-sss)
to_tm	不能	结束时间 (yyyy-mm-dd hh-mm-sss)

Plain Text
{
    “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 出错时美洽会返回错误码以及响应的错误提示。

errno	errmsg
10011	Authentication failed. Please check app_id and sign.
10012	URL is error. Please check url.
10013	The param of limit in request is xxx, exceed max value xxx.
10014	Request api exceed specified times. Please request later.
10015	Server-side internal logic error. Please try again later.
10016	The param of xxx is invalid.

错误码以及对应的错误提示

常见问题

在线客服

AI员工

开发指南

APIs V2.0

访客 #

访客模型 #

顾客 #

这篇文章能帮助到你吗？

产品

公司与条款

联系我们