APIs

客源多开放 APIs 提供工作台对话、客户、留言、素材等资源的查询与操作能力，适用于企业自有系统对接、数据同步、消息自动回复等场景。

使用前提：本接口面向具备后端开发能力的技术人员。调用前需在「设置中心 - 开发者 - APIs」中获取 APPID 和密钥 secret，后续调用以下 APIs 时都需要使用。

鉴权说明

所有 API 请求的 Header 需要带上以下参数：

参数 类型 说明
accountid int 账号 id
appid string 在「设置中心 - 开发者 - APIs」获取的 APPID
secret string 在「设置中心 - 开发者 - APIs」获取的密钥

获取单个会话

通过 HTTP Post 方式请求 /api/open/getsession。

请求参数

参数 类型 说明
visitorid string 访客 id

响应示例

{
    error_code: 0, // 错误码
    description: "success",
    data: {
        // 单个会话信息，具体参数可去 Webhooks 中查找会话模型
    }
}

获取单个客户

通过 HTTP Post 方式请求 /api/open/getcustomer。

请求参数

参数 类型 说明
visitorid string 访客 id

响应示例

{
    "data": {
        "id":         "标识id",
        "visitorid":  "访客id",
        "name":       "姓名",
        "sex": 0,        // 性别
        "age": 0         // 年龄
    },
    "error_code": 0,
    "description": "success"
}

回复消息

通过 HTTP Post 方式请求 /api/open/replymsg。

请求参数

参数 类型 说明
visitorid string 访客 id
sessionid string 会话 id
content json 消息内容 json，结构见下表

消息内容（content）

消息类型 参数值 说明
文本消息 { type: 0, text: "内容" }
图片消息 { type: 1, url: "图片路径", thumburl: "缩略图路径" } 缩略图路径可以为空
素材消息 { type: 2, material_id: "素材id" }
type 值说明

2：小红书笔记

3：小红书落地页

4：小红书名片

5：小红书留资卡

6：小红书交易卡

7：抖音留资卡

8：抖音小程序卡

9：抖音一键留资卡

10：快手留资卡

11：快手链接卡

12：快手门店卡

13：快手企微卡

响应示例

{
    "error_code": 0, // 错误码
    "description": ""
}

错误码说明

error_code 参数值 说明
error_code 1001 参数不合法。一般为 accountid、appid、secret、visitorid、sessionid、content 有为空的情况
error_code 1002 服务器错误，请联系管理员
error_code 1003 账号过期
error_code 1004 账号无效
error_code 1027 appid 有误
error_code 1049 secret 有误
error_code 1042 请求接口达到频控限制，默认为 30 次/分
error_code 1012 会话不存在，请查看对话列表里面是否有对话
error_code 1016 发送图片大小超过 2M
error_code 1019 会话状态不在对话中
error_code
description		 1001
material_id error		 素材 id 为空
error_code
description		 1007
material error		 要发送的素材不存在

获取单个留言消息

通过 HTTP Post 方式请求 /api/open/getleavemessages。

请求参数

参数 类型 说明
sessionid string 访客会话 id

响应示例

{
    "data": [{
        "createtime":    "创建时间",
        "contenttype":   "内容类型",
        "msgtype":       "消息类别",
        "content":       "留言内容",
        "operatorid":    "客服id",
        "groupid":       "客服组",
    }],
    "error_code": 0,
    "description": "success"
}

获取留言会话（翻页查询）

通过 HTTP Post 方式请求 /api/open/getleavesessions。

请求参数

参数 类型 说明
page int 页码，从 1 开始
size int 每页行数
timebegin datetime 时间范围 - 开始
timeend datetime 时间范围 - 结束

响应示例

{
    "data": {
        "page":  "页码",
        "count": "总数",
        "items": "留言会话列表" // 数据格式见留言会话模型
    },
    "error_code": 0,
    "description": ""
}

留言消息模型

参数 类型 说明
createtime datetime 留言创建时间
contenttype int 留言内容类别
msgtype int 消息类别
content string 留言内容，根据消息类别存储为 json 格式
operatorid int 最后处理客服 id
groupid int 最后处理客服分组 id

留言会话模型

参数 类型 说明
sessionid string 会话 id
visitorid string 访客永久身份
createtime datetime 留言创建时间
accessway int 会话接入方式/渠道
int 值说明

100：网站H5

101：微信公众号

102：微信小程序

103：企业微信

104：抖音企业号

105：微博

106：小程序客服插件

107：app 接入

108：百度BCP

109：微信客服

110：头条小程序客服

111：快手

112：Messenger

113：WhatsApp

114：Line

115：飞书

116：Telegram

117：小红书

118：微信小店
nickname string 访客昵称
remark string 访客备注
appid string 应用接入 appid
appname string 应用名称
email string 客人邮箱地址
status int 处理状态
updateby int 更新人
updatetime datetime 最后修改时间
operatorid int 最后处理客服 id
groupid int 最后处理客服分组 id

获取素材

通过 HTTP Post 方式请求 /api/open/getmaterials。

请求 Header 参数

参数 类型 说明
accountid int 账号 id
appid string appid
secret string 密钥
content-type 固定值 "application/json"

Body 参数

参数 类型 说明
type int
type 值说明

1：小红书笔记

2：小红书落地页

3：小红书名片

4：小红书留资卡

5：小红书交易卡

6：抖音留资卡

7：抖音小程序卡

8：抖音一键留资卡

9：快手留资卡

10：快手链接卡

11：快手门店卡

12：快手企微卡
authid string 非必填，授权账号 id，即 session 中的 appid（应用接入 appid）。
多个号使用逗号（","）分割，
例如：6719ae69000000000b0322e1,6719ae690000aaaa00b0322e1
page int 非必填，查询小红书笔记时传入，最小 1
size int 非必填，查询小红书笔记时传入，最大 50

响应示例

{
    "data": {
        "list": [
            {
                "type":         素材类型,
                "appid":        "授权账号id，session中的appid（应用接入 appid）",
                "material_id":  "素材id",
                "title":        "素材title",
                "content": {                // string，素材展示的详细信息
                    "title": "",
                    "image": ""
                }
            }
        ]
    },
    "error_code": 0,
    "description": "success"
}

错误码说明

error_code 参数值 说明
error_code 1001 参数不合法。一般为 accountid、appid、secret 有为空的情况
error_code 1002 服务器错误，请联系管理员
error_code 1003 账号过期
error_code 1004 账号无效
error_code 1027 appid 有误
error_code 1042 请求接口达到频控限制，默认为 30 次/分
error_code 1049 secret 有误
error_code
description		 1001
type error		 素材类型有误
error_code
description		 1001
authid error		 授权账号有误
error_code
description		 1001
page error		 查询小红书笔记，页码有误
error_code
description		 1001
size error		 查询小红书笔记，页数有误
相关文档： Webhooks（接收客源多主动推送的对话/客户/消息事件，与 APIs 的主动查询互补，二者配合可实现双向数据同步）
本篇目录