帮我吧 API v1 接口文档

接口文档版本：1.0.16
最后更新：2026-04-05
历史文档：https://doc1.bangwo8.com/

一、快速入门

1.1 基本信息

API 版本: v1

请求地址: https://www.bangwo8.com/api/v1

测试环境: https://abtest.bangwo8.com/api/v1

认证方式: OAuth2 Bearer Token

1.2 认证方式

OAuth2 Bearer Token（推荐）

先获取 access_token（见 7.1 获取 Token）

在请求头中使用：

Authorization: Bearer {access_token}

示例：

Basic Auth (不推荐)

使用坐席登录账号和密码

在请求头中使用：

Authorization: Basic {d2F5LWRyZWFtOjEyMzQ1Ng==}

示例：

注意: 特殊场景下也可以使用Basic Auth，请尽可能使用 OAuth2 Bearer Token 认证方式。

1.3 公共请求头

参数名	类型	必填	说明
Authorization	string	是	认证信息
Requestid	string	否	请求唯一 ID，用于防止重复请求
Content-Type	string	POST/PUT 时必填	application/json

1.4 响应格式

成功响应

大部分接口直接返回数据对象：

{
  "supports": [...],
  "count": "10"
}

部分接口返回带 status/message 的响应：

{
  "status": "0",
  "message": "Insert ok",
  "data": false
}

错误响应

{
  "errcode": "100047",
  "errmsg": "Invalid resource URI"
}

1.5 通用状态码

状态码	说明
200	成功
401	认证失败
403	权限不足
404	资源不存在
500	服务器错误

1.6 最佳实践

使用 HTTPS: 所有生产环境请求都应使用 HTTPS

添加 Requestid: 建议在请求头中添加唯一的 Requestid，防止重复请求

合理分页: 列表接口默认分页，建议 per_page 不超过 100

错误重试: 对于 5xx 错误，可以进行适当的重试

Token 缓存: token 有效期 1 小时，建议缓存并在 3540 秒后刷新

二、核心业务实体

2.1 客户与联系人

2.1.1 联系人管理

获取联系人列表

请求参数

参数	类型	必填	说明
created_start	string	否	创建时间开始（含当天）
created_end	string	否	创建时间结束（含当天）
created_order	string	否	创建时间排序 asc-升序 desc-降序
page	string	否	页数
per_page	string	否	每页大小
updated_start	string	否	更新时间开始（含当天）
updated_end	string	否	更新时间结束（含当天）
updated_order	string	否	更新时间排序 asc-升序 desc-降序
deStat	string	否	是否包含已删除数据，0-不包含 1-包含

响应字段

字段	类型	说明
users	array	联系人列表
users[].cId	string	联系人 ID
users[].name	string	姓名
users[].mobile	string	手机号
users[].email	string	邮箱
users[].fixnumber	string	固定电话
users[].position	string	职位
users[].QQ	string	QQ 号码
users[].note	string	备注
users[].companyId	string	公司 ID
users[].supportId	string	客服 ID
users[].multiServiceList	string	多服务列表
users[].default	string	默认服务
users[].service_groupid	string	服务组 ID
users[].createDT	string	创建时间
users[].updateDT	string	更新时间
users[].tableName	string	表名
users[].uniqueId	string	唯一 ID
users[].custom_fields	array	自定义字段
users[].state	string	状态
count	string	总数
previous_page	string	上一页 URL
next_page	string	下一页 URL

响应示例

{
    "users": [
        {
            "cId": "6454743",
            "name": "",
            "mobile": "",
            "email": "",
            "fixnumber": "",
            "position": "",
            "QQ": "",
            "note": "",
            "companyId": "0",
            "supportId": "0",
            "multiServiceList": "",
            "default": "",
            "service_groupid": "0",
            "createDT": "2017-10-16 13:59:01",
            "updateDT": "2023-03-18 06:50:48",
            "tableName": "",
            "uniqueId": "",
            "custom_fields": [
                {
                    "key": "field_2",
                    "value": "0"
                }
            ],
            "state": "1"
        }
    ],
    "count": "219",
    "previous_page": "",
    "next_page": "https://preview.bangwo8.com/api/v1/users.json?per_page=5&page=2"
}

获取多个联系人详情

请求参数

参数	类型	必填	说明
userId	string	是	联系人 ID

响应字段

字段	类型	说明
user	object	联系人对象
user.userId	string	联系人 ID
user.name	string	姓名
user.mobile	string	手机号
user.email	string	邮箱
user.createrId	string	创建者 ID（系统内部字段）
user.custom_fields	array	自定义字段
user.state	string	状态

批量联系人详情

请求参数

参数	类型	必填	说明
ids	string	否	联系人 ID 列表，以逗号分隔

搜索联系人

请求参数

参数	类型	必填	说明
deStat	string	否	是否包含已删除数据，0-不包含 1-包含
query	string	否	搜索条件
sort_by	string	否	排序字段
sort_order	string	否	排序方式 asc/desc

创建联系人

请求参数

参数	类型	必填	说明
Content-Type	string	是	application/json
name	string	否	姓名
mobile	string	否	手机号
email	string	否	邮箱
fixnumber	string	否	固定电话
position	string	否	职位
QQ	string	否	QQ 号码
note	string	否	备注
companyId	string	否	公司 ID
service_groupid	string	否	服务组 ID
custom_fields	array	否	自定义字段

请求示例

修改联系人

请求参数

参数	类型	必填	说明
userId	string	是	联系人 ID
Content-Type	string	是	application/json
name	string	否	姓名
mobile	string	否	手机号
email	string	否	邮箱
custom_fields	array	否	自定义字段

删除联系人

请求参数

参数	类型	必填	说明
userId	string	是	联系人 ID

批量删除联系人

请求参数

参数	类型	必填	说明
ids	string	是	联系人 ID 列表，以逗号分隔

2.1.2 客户分组

该模块接口同时支持公司分组（2B模式）和联系人分组（2C模式）。

获取客户分组列表

请求参数

参数	类型	必填	说明
page	int	否	页码，默认 1
per_page	int	否	每页数量，默认 100

响应字段

字段	类型	说明
groupId	int	分组ID，系统自动生成
groupName	string	分组名称
type	tinyint	分组类型：1-公司分组，2-联系人分组

响应示例

{
    "customergroups": [
        {
            "groupId": "12090",
            "groupName": "trigger",
            "type": "1"
        },
        {
            "groupId": "10795",
            "groupName": "群英荟萃",
            "type": "2"
        },
        {
            "groupId": "27668",
            "groupName": "API组",
            "type": "2"
        }
    ]
}

获取客户分组详情

请求参数

参数	类型	必填	说明
id	string	是	分组 ID

批量分组详情

请求参数

参数	类型	必填	说明
ids	string	否	分组 ID 列表，以逗号分隔

创建客户分组

请求参数

参数	类型	必填	说明
Content-Type	string	是	application/json
customergroup.groupName	string	是	分组名称
customergroup.type	tinyint	是	分组类型：1-公司分组，2-联系人分组

请求示例

响应示例

{
    "customergroups": {
        "groupId": "28728",
        "groupName": "VIP客户",
        "type": "2"
    }
}

修改客户分组

请求参数

参数	类型	必填	说明
id	string	是	分组 ID
Content-Type	string	是	application/json
customergroup.groupName	string	否	分组名称
customergroup.type	tinyint	否	分组类型

请求示例

获取分组用户

请求参数

参数	类型	必填	说明
id	string	是	分组 ID

说明

2B模式下返回的是公司列表，2C模式下返回的是联系人列表。

响应字段

字段	类型	说明
customers	array	客户/联系人列表
customers[].uId	string	用户/公司 ID
customers[].companyName	string	公司名称
customers[].supportId	string	客服 ID
customers[].servicestarttime	string	服务开始时间
customers[].serviceendtime	string	服务结束时间
customers[].serviceaccount	string	服务账号
customers[].servicepassword	string	服务密码
customers[].address	string	地址
customers[].createDT	string	创建时间
customers[].updateDT	string	更新时间
customers[].custom_fields	array	自定义字段

响应示例

{
    "customers": [
        {
            "uId": "2606877",
            "companyName": "新公司",
            "supportId": "0",
            "servicestarttime": "0000-00-00",
            "serviceendtime": "0000-00-00",
            "serviceaccount": "",
            "servicepassword": "",
            "address": "",
            "createDT": "2018-08-17 16:51:46",
            "updateDT": "2023-03-18 06:50:30",
            "custom_fields": [
                {
                    "key": "field_1",
                    "value": ""
                }
            ]
        }
    ]
}

2.1.3 联系人字段

获取联系人字段列表

响应字段

字段	类型	说明
user_fields	array	联系人字段列表
user_fields[].id	string	字段 ID
user_fields[].name	string	字段名称
user_fields[].key	string	字段标识
user_fields[].type	string	字段类型
user_fields[].system	string	是否为系统字段：1-是，0-否
user_fields[].custom_field_options	array	选项列表（下拉框类型）

响应示例

{
    "user_fields": [
        {
            "id": "1",
            "name": "姓名",
            "key": "name",
            "type": "2",
            "system": "1",
            "custom_field_options": []
        },
        {
            "id": "1",
            "name": "手机号",
            "key": "mobile",
            "type": "2",
            "system": "1",
            "custom_field_options": []
        }
    ]
}

2.1.4 公司管理

获取公司列表

请求参数

参数	类型	必填	说明
created_start	string	否	创建时间开始（含当天）
created_end	string	否	创建时间结束（含当天）
created_order	string	否	创建时间排序 asc-升序 desc-降序
page	string	否	页数
per_page	string	否	每页大小
deStat	string	否	是否包含已删除数据，0-不包含 1-包含

响应字段

字段	类型	说明
companies	array	公司列表
companies[].uId	string	公司 ID
companies[].companyName	string	公司名称
companies[].province	string	省份
companies[].city	string	城市
companies[].supportId	string	客服 ID
companies[].servicestarttime	string	服务开始时间
companies[].serviceendtime	string	服务结束时间
companies[].serviceCharge	string	服务费
companies[].serviceaccount	string	服务账号
companies[].servicepassword	string	服务密码
companies[].address	string	地址
companies[].userURL	string	用户 URL
companies[].serveNote	string	服务备注
companies[].multiServiceList	string	多服务列表
companies[].service_groupid	string	服务组 ID
companies[].createDT	string	创建时间
companies[].updateDT	string	更新时间
companies[].tableName	string	表名
companies[].custom_fields	array	自定义字段

获取公司详情

请求参数

参数	类型	必填	说明
companyId	string	是	公司 ID

批量公司详情

请求参数

参数	类型	必填	说明
ids	string	否	公司 ID 列表，以逗号分隔

创建公司

请求参数

参数	类型	必填	说明
Content-Type	string	是	application/json
companyName	string	否	公司名称
province	string	否	省份
city	string	否	城市
address	string	否	地址
serveNote	string	否	服务备注
service_groupid	string	否	服务组 ID
custom_fields	array	否	自定义字段

修改公司

请求参数

参数	类型	必填	说明
id	string	是	公司 ID
Content-Type	string	是	application/json
companyName	string	否	公司名称
province	string	否	省份
city	string	否	城市
address	string	否	地址
serveNote	string	否	服务备注
custom_fields	array	否	自定义字段

删除公司

请求参数

参数	类型	必填	说明
id	string	是	公司 ID

批量删除公司

请求参数

参数	类型	必填	说明
id	string	是	公司 ID

搜索公司

请求参数

参数	类型	必填	说明
query	string	否	搜索条件
sort_by	string	否	排序字段
sort_order	string	否	排序方式 asc/desc
deStat	string	否	是否包含已删除数据，0-不包含 1-包含
page	string	否	页数
per_page	string	否	每页大小

2.1.5 公司字段

获取公司字段列表

2.1.6 获取公司联系人

请求参数

参数	类型	必填	说明
company_id	string	是	公司 ID
created_start	string	否	创建时间开始
created_end	string	否	创建时间结束
created_order	string	否	创建时间排序
page	string	否	页数
per_page	string	否	每页大小
updated_start	string	否	更新时间开始
updated_end	string	否	更新时间结束
updated_order	string	否	更新时间排序
deStat	string	否	是否包含已删除数据

2.1.7 远程 ID 管理

获取远程ID信息

请求参数

参数	类型	必填	说明
id	string	是	远程 ID

响应字段

字段	类型	说明
unique_id	object	远程 ID 对象
unique_id.id	integer	远程 ID
unique_id.remark	string	备注
unique_id.userId	string	所属联系人 ID

修改远程ID备注

请求体

{
    "unique_ids": [
        {
            "id": "987876674",
            "remark": "帮我吧的演示服务器"
        }
    ]
}

响应字段

字段	类型	说明
results	array	处理结果列表
results[].id	integer	远程 ID
results[].success	boolean	是否成功
results[].error_log	string	错误信息

远程ID绑定联系人

请求参数

参数	类型	必填	说明
Content-Type	string	是	application/json

请求体

{
    "unique_ids": [
        {
            "id": "987876674",
            "userId": "22"
        }
    ]
}

响应字段

字段	类型	说明
results	array	处理结果列表
results[].id	integer	远程 ID
results[].success	boolean	是否成功
results[].error_log	string	错误信息

解绑远程 ID

请求体

{
    "unique_ids": [
        {
            "id": "987876674"
        }
    ]
}

2.2 工单系统

2.2.1 工单管理

获取工单列表

请求参数

参数	类型	必填	说明
page	int	否	页码，默认 1
per_page	int	否	每页数量，默认 10
state	int	否	工单状态：1-新建，2-已开启，3-待回应，4-已解决，6-已关闭
groupId	int	否	客服组 ID
servicerId	int	否	客服 ID
userId	int	否	联系人 ID
companyId	int	否	公司 ID
created_start	date	否	创建时间开始
created_end	date	否	创建时间结束
updated_start	date	否	更新时间开始
updated_end	date	否	更新时间结束

获取工单详情

请求参数

参数	类型	必填	说明
ticketId	string	是	工单 ID

响应字段

字段	类型	说明
ticket	array	工单对象

批量工单详情

请求参数

参数	类型	必填	说明
ids	string	否	工单 ID 列表，以逗号分隔

搜索工单

请求参数

参数	类型	必填	说明
query	string	否	搜索关键词
sort_by	string	否	排序字段
sort_order	string	否	排序方式 asc/desc
page	string	否	页码
per_page	string	否	每页数量

创建工单

请求参数

参数	类型	必填	说明
Content-Type	string	是	application/json
ticket.subject	string	是	工单标题
ticket.ticketTemplateId	string	否	工单模板 ID
ticket.ticketReply	object	否	工单回复内容
ticket.ticketReply.replyType	int	否	回复类型
ticket.ticketReply.replyMsg	string	否	回复内容
ticket.custUser	object	否	联系人信息
ticket.custUser.mobilephone	string	否	手机号
ticket.custom_fields	array	否	自定义字段

修改工单

请求参数

参数	类型	必填	说明
ticketId	string	是	工单 ID

批量修改工单

请求参数

参数	类型	必填	说明
ids	string	是	工单 ID 列表，以逗号分隔

工单拆单

请求参数

参数	类型	必填	说明
Content-Type	string	是	application/json
ticketId	int	是	工单 ID
separatedCount	int	是	拆单数量

2.2.2 工单回复

获取工单回复列表

请求参数

参数	类型	必填	说明
ticket_id	string	是	工单 ID
sort_order	string	否	排序方式

响应字段

字段	类型	说明
ticketReplys	array	工单回复列表

2.2.3 工单附件

上传工单附件

请求参数

参数	类型	必填	说明
ticketId	string	是	工单 ID
filename	string	是	文件名
Content-Type	string	是	application/octet-stream

2.2.4 工单模板

获取工单模板列表

响应字段

字段	类型	说明
tickettemplates	array	工单模板列表
count	string	模板总数

批量工单模板

请求参数

参数	类型	必填	说明
ids	string	否	模板 ID 列表，以逗号分隔

获取工单模板详情

请求参数

参数	类型	必填	说明
tId	string	是	模板 ID

响应字段

字段	类型	说明
tickettemplate	object	工单模板对象

获取模板字段

请求参数

参数	类型	必填	说明
id	string	是	模板 ID

响应字段

字段	类型	说明
ticket_fields	array	模板字段列表

2.2.5 工单字段

获取工单自定义字段

获取工单所有字段

覆盖字段选项

请求参数

参数	类型	必填	说明
fieldId	string	是	字段 ID

请求体

[
    {"optionName": "选项1", "extendId": "001"},
    {"optionName": "选项2", "extendId": "002"}
]

响应字段

字段	类型	说明
columnId	string	列 ID
name	string	字段名称
key	string	字段标识
type	string	字段类型
custom_field_options	array	字段选项列表

更新字段选项

请求参数

参数	类型	必填	说明
columnId	string	是	列 ID

请求体

[
    {"optionName": "选项1", "extendId": "001"},
    {"optionName": "选项2", "extendId": "002"}
]

响应字段

字段	类型	说明
columnId	string	列 ID
name	string	字段名称
key	string	字段标识
type	string	字段类型
custom_field_options	array	字段选项列表

删除字段选项

请求参数

参数	类型	必填	说明
columnId	string	是	列 ID

2.2.6 工单查询器

获取工单查询器列表

获取工单查询器详情

获取查询器工单列表

获取查询器工单总数

批量获取查询器工单数量

请求参数

参数	类型	必填	说明
ids	string	否	查询器 ID 列表，以逗号分隔

响应字段

字段	类型	说明
ticketview_counts	array	查询器工单数量列表

2.3 服务记录

2.3.1 IM 服务记录

获取 IM 会话列表

请求参数

参数	类型	必填	说明
uname	string	否	用户标识，按用户筛选
servicestart_start	datetime	否	服务开始时间筛选：开始时间
servicestart_end	datetime	否	服务开始时间筛选：结束时间
serviceend_start	datetime	否	服务结束时间筛选：开始时间
serviceend_end	datetime	否	服务结束时间筛选：结束时间
page	int	否	页码，默认 1
per_page	int	否	每页大小，默认 100

说明

时间参数格式为 "2017-08-29"，结束时间包含当天

默认按会话 ID 升序返回

响应字段

字段	类型	说明
chats	array	会话列表
count	int	总会话数
next_page	string	下一页 URL
previous_page	string	上一页 URL

会话对象字段

字段	类型	说明
r_id	int	会话 ID
type	int	会话来源：1-客户端，2-网页，3-微信，4-机器人，5-客服，8-第三方
support_id	int	处理客服 ID
support_name	string	处理客服名字
uname	string	用户标识
start_time	datetime	会话开始时间
end_time	datetime	会话结束时间
client_ip	string	用户 IP
ip_info	string	用户 IP 详情
evaluate	int	评价：0-未评价，1-满意，2-一般，3-不满意
evaluate_time	datetime	评价时间
evaluate_remark	text	评价内容
end_type	int	服务结束类型：1-客户主动结束，2-客服主动结束
servicer_msg_count	int	客服发出的消息总数
client_msg_count	int	客户发出的消息总数
first_response	int	客服第一次响应时间距离服务开始时间的秒数
response_speed	int	平均响应时长（秒）
chat_clue	string	线索

请求示例

响应示例

{
    "chats": [
        {
            "r_id": 111,
            "type": "1",
            "support_id": "2321",
            "support_name": "张三",
            "uname": "u3_o2_slufdbltr0cylrmrcokice",
            "start_time": "2017-8-23 12:23:12",
            "end_time": "2017-8-23 12:23:12",
            "evaluate": "1",
            "servicer_msg_count": "23",
            "client_msg_count": "25"
        }
    ],
    "count": 42,
    "next_page": "https://www.bangwo8.com/api/v1/imchat/histories.json?per_page=40&page=2",
    "previous_page": null
}

获取指定客服的会话列表

请求参数

参数	类型	必填	说明
id	int	是	客服 ID
uname	string	否	用户标识，按用户筛选
servicestart_start	datetime	否	服务开始时间筛选：开始时间
servicestart_end	datetime	否	服务开始时间筛选：结束时间
serviceend_start	datetime	否	服务结束时间筛选：开始时间
serviceend_end	datetime	否	服务结束时间筛选：结束时间
page	int	否	页码，默认 1
per_page	int	否	每页大小，默认 100

说明

返回当前客服的所有会话记录

时间参数格式为 "2017-08-29"，结束时间包含当天

请求示例

获取 IM 聊天记录详情

请求参数

参数	类型	必填	说明
id	int	是	会话 ID
time_start	datetime	否	按聊天内容发送日期筛选：开始时间
time_end	datetime	否	按聊天内容发送日期筛选：结束时间，与 time_start 成对出现
page	int	否	分页获取，默认为 1
per_page	int	否	每页大小，默认为 100

响应字段

字段	类型	说明
im_chatrecords	object	聊天记录对象
im_chatrecords.r_id	int	会话 ID
im_chatrecords.contents	array	聊天消息列表
count	int	消息总数
next_page	string	下一页 URL
previous_page	string	上一页 URL

消息对象字段

字段	类型	说明
spokesman	string	发言人名字
spokesman_identity	int	发言人身份：1-客服，2-用户，3-机器人
msg	text	聊天内容
create_time	datetime	消息发送时间

请求示例

响应示例

{
    "im_chatrecords": {
        "r_id": "221",
        "contents": [
            {
                "spokesman": 213,
                "spokesman_identity": 1,
                "msg": "这里是具体的聊天内容",
                "create_time": "2017-8-23 13:12:23"
            },
            {
                "spokesman": 234,
                "spokesman_identity": 1,
                "msg": "这里是具体的聊天内容",
                "create_time": "2017-8-23 13:12:23"
            }
        ]
    },
    "count": 42,
    "next_page": "https://www.bangwo8.com/api/v1/imchat/chatrecords/221.json?per_page=40&page=2",
    "previous_page": null
}

获取客服在线状态

请求参数

参数	类型	必填	说明
sId	int	是	客服 ID
time_start	datetime	否	开始时间，包含当天
time_end	datetime	否	结束时间，包含当天

响应字段

字段	类型	说明
serviceState	object	客服状态对象
serviceState.sId	int	客服 ID
serviceState.currentState	string	客服 IM 当前状态
serviceState.data	object	切换状态时间列表

响应示例

{
    "serviceState": {
        "sId": 356789,
        "currentState": "离线",
        "data": {
            "2020-06-08 09:00:07": "在线",
            "2020-06-08 12:00:10": "离线",
            "2020-06-08 13:30:07": "在线"
        }
    }
}

获取服务总结

请求参数

参数	类型	必填	说明
r_Id	int	是	会话 ID
servicesummary_type	int	是	服务总结类型：1-IM，2-呼叫中心，3-远程协助

说明

获取在线聊天的会话服务总结，servicesummary_type=1

接口返回级联类型字段默认返回选项 ID

如需返回选项内容而非 ID，使用 v2 接口：GET /api/v1/servicesummary_v2/{r_Id}.json

响应字段

字段	类型	说明
status	string	状态码
message	string	状态说明
data	object	服务总结数据
data.ticketTemplateName	string	模板名称
data.custom_fields	array	服务总结模板自定义字段

响应示例

{
    "status": "200",
    "message": "Successful",
    "data": {
        "serviceSummary": {
            "ticketTemplateName": "im 服务总结模板",
            "custom_fields": [
                {
                    "key": "field_1",
                    "value": "4334"
                },
                {
                    "key": "field_3",
                    "value": "1"
                },
                {
                    "key": "field_2",
                    "value": "下拉菜单的某一项"
                },
                {
                    "key": "field_4",
                    "value": "附件的下载地址"
                }
            ]
        }
    }
}

错误响应

没有绑定服务总结模板：

{
    "status": "120001",
    "message": "No service summary template"
}

未填写服务总结：

{
    "status": "120002",
    "message": "No service summary information"
}

2.3.2 CC 服务记录

获取通话记录列表

请求参数

参数	类型	必填	说明
starttime	datetime	否	按创建时间筛选，开始时间，格式为：2017-08-27
endtime	datetime	否	按创建时间筛选，结束时间，格式为：2017-08-29
fromPhone	varchar	否	客户号码，按手机号筛选时必填
direction	tinyint	否	呼叫方向：0-呼入，1-呼出，2-座席内呼
page	int	否	分页获取，默认为 1
per_page	int	否	每页大小，默认为 100

说明

结束时间包含当天，例如结束时间为 2017-08-29，则返回的记录包含 2017-08-29 当天的

一个 callid 唯一标识一条通话记录，当一次通话被转接过，则返回数据会有多条 callid 一样的记录

响应字段

字段	类型	说明
callrecords	array	通话记录列表
count	int	总记录数
next_page	string	下一页 URL
previous_page	string	上一页 URL

通话记录对象字段

字段	类型	说明
crId	string	通话记录 ID
callid	string	通话记录 ID（系统自动分配）
direction	tinyint	呼叫方向：0-呼入，1-呼出，2-座席内呼
appraise	tinyint	评价：1-非常满意，2-满意，3-不满意，0-未评价
fromPhone	varchar	主叫号码
toPhone	varchar	被叫号码，座席内呼时，该值为客服 id
Transfer	tinyint	是否转接：0-未转接，1-转接
TransferTime	datetime	转接时间
TransferToAgentid	int	转接到的客服 id
agentid	int	处理客服 id
digits	smallint	用户按键内容
fromattr	varchar	号码归属地
CallSummary	text	通话总结
alertingTime	datetime	振铃时间
starttime	datetime	主叫开始时间
endtime	datetime	主叫结束时间
sstime	datetime	被叫开始时间
setime	datetime	被叫结束时间
eventFlowState	tinyint	流程状态码：1-IVR 放弃，2-IVR 自动挂断，3-无可用座席，4-排队放弃，5-话机离线，7-已接听，6/8-振铃未接听，9-座席拒接，10-语音留言，11-客户速挂
callduration	string	主叫通话时长（秒）
seccallduration	string	被叫通话时长（秒）
recordurl	varchar	录音文件下载地址

请求示例

响应示例

{
  "callrecords": [
    {
      "callid": "123",
      "direction": "0",
      "appraise": "1",
      "fromPhone": "13240138421",
      "toPhone": "18582082009",
      "Transfer": "0",
      "agentid": "132",
      "fromattr": "北京市",
      "callduration": "90",
      "seccallduration": "80",
      "recordurl": "http://ccp02.oss.aliyuncs.com/ivr_record/4001222344/20170818/R0032de32_20170818185454.wav"
    }
  ],
  "count": 42,
  "next_page": "https://www.bangwo8.com/api/v1/callrecord/histories.json?per_page=40&page=2",
  "previous_page": null
}

获取指定手机号的通话记录列表

请求参数

参数	类型	必填	说明
starttime	datetime	否	开始时间，格式为：2021-10-27
endtime	datetime	否	结束时间，格式为：2021-10-29
fromPhone	varchar	是	客户号码
direction	tinyint	否	呼叫方向：0-呼入，1-呼出，2-座席内呼
page	int	否	页码，默认 1
per_page	int	否	每页大小，默认 100

请求示例

获取指定客服的通话记录列表

请求参数

参数	类型	必填	说明
id	int	是	客服 ID
starttime	datetime	否	开始时间，格式为：2017-08-27
endtime	datetime	否	结束时间，格式为：2017-08-29
page	int	否	页码，默认 1
per_page	int	否	每页大小，默认 100

说明

结束时间包含当天

一个 callid 唯一标识一条通话记录，当一次通话被转接过，则返回数据会有多条 callid 一样的记录

请求示例

获取通话记录详情

请求参数

参数	类型	必填	说明
id	string	是	通话记录 ID（callid）

响应字段

字段	类型	说明
callrecord	object	通话记录对象

请求示例

响应示例

{
    "callrecord": {
        "callid": "1601221206243740000100750000c343",
        "direction": "0",
        "appraise": "0",
        "fromPhone": "15200323154",
        "toPhone": "",
        "Transfer": "0",
        "agentid": "0",
        "digits": "0",
        "fromattr": "湖南长沙",
        "CallSummary": null,
        "alertingTime": "0000-00-00 00:00:00",
        "starttime": "2016-01-22 11:55:59",
        "endtime": null,
        "sstime": null,
        "setime": null,
        "callduration": "0",
        "seccallduration": "0",
        "recordurl": "http://ccp02.oss.aliyuncs.com/ivr_record/4001222344/20170818/R0032de32_20170818185454.wav"
    }
}

获取通话录音

说明

返回通话录音文件的下载地址

录音时间超过两个月会进入冷冻状态，需要先解冻才能访问

获取服务总结（CC）

请求参数

参数	类型	必填	说明
callid	int	是	通话 id
servicesummary_type	int	是	服务总结类型：2-呼叫中心（1-IM，3-远程协助）

说明

获取呼叫中心的通话服务总结，servicesummary_type=2

接口返回级联类型字段默认返回选项 ID

如需返回选项内容而非 ID，使用 v2 接口：GET /api/v1/servicesummary_v2/{callid}.json

响应字段

字段	类型	说明
status	string	状态码
message	string	状态说明
data	object	服务总结数据
data.ticketTemplateName	string	模板名称
data.custom_fields	array	服务总结模板自定义字段

错误响应

没有绑定服务总结模板：

{
    "status": "120001",
    "message": "No service summary template"
}

未填写服务总结：

{
    "status": "120002",
    "message": "No service summary information"
}

录音解冻

说明

录音时间超过两个月，录音会进入冷冻状态，即：获取录音之前需要先解冻后方能使用，解冻时效为 24 小时，超过 24 小时仍需要再次解冻。解冻大概需要 2 分钟解冻成功，解冻成功后可直接访问原来的录音地址。

请求参数

参数	类型	必填	说明
url	varchar	是	录音地址，可以通过获取通话记录详情接口获取到该地址
restore	int	是	固定值写 1

响应字段

字段	类型	说明
status	String	状态：RestoreAlreadyInProgress-解冻中，RestoreCompleted-解冻完成，OperationNotSupported-不支持解冻，NoSuchKey-目标不存在，RestoreFailed-解冻失败，RestoreTodo-解冻，ExceptionStatus-文件状态异常，请联系管理员
file_path	String	录音文件地址，注意这里是相对地址
file_name	String	录音文件名称

请求示例

响应示例

{
    "status": "CorrectStatus",
    "message": "状态正常",
    "file_path": "/recordings/71f717e43078338c/7a0604948a6b615c/20230101/xxx.wav",
    "file_name": "xxx.wav"
}

2.3.3 远程协助记录

获取远程协助记录列表

请求参数

参数	类型	必填	说明
starttime	datetime	否	按创建时间筛选，开始时间，格式为：2017-08-27
endtime	datetime	否	按创建时间筛选，结束时间，格式为：2017-08-29
page	int	否	分页获取，默认为 1
per_page	int	否	每页大小，默认为 100

说明

结束时间是包含当前时间的，例如结束时间为 2017-08-29，则返回的记录包含 2017-08-29 当天的

接口返回值中的"一级问题类型"、"二级问题类型"、"三级问题类型"均为下拉列表类型的字段，当前接口默认返回的是选项 ID，以下接口可返回选项内容，而非选项 ID：GET /api/v1/remoterecord/histories_v2.json

响应字段

字段	类型	说明
remoterecords	array	远程协助记录列表
count	int	总记录数
next_page	string	下一页 URL
previous_page	string	上一页 URL

服务记录对象字段

字段	类型	说明
csId	int	服务记录 id，系统自动分配
csIdS	char	会话 id，标识一次会话
csBTime	DATETIME	服务开始时间
csETime	DATETIME	服务结束时间
csStat	tinyint	服务状态：0-无效，1-服务中，2-服务等待中，3-服务延长中，4-服务保留中，5-服务完成
csServicerId	int	处理客服 id
uniqueNumber	char	帮我吧客户端 ID（9 位 ID）
csSId	int	服务卡 id
csPrice	decimal	服务费
payStat	tinyint	支付状态：0-没支付，1-支付成功，2-支付失败，3-刚打开支付页面更新记录，4-在线扣费成功
payDateTime	DATETIME	支付时间
companyName	varchar	公司名称
contactor	varchar	联系人
contactMethod	varchar	联系方式
ComputerName	varchar	主机备注
ptId	int	一级问题类型 id
ptChildId	int	二级问题类型 id
ptThird	int	三级问题类型 id
note	text	问题描述
ProblemSolution	text	解决办法
commentScore	tinyint	评价：5-好评，3-中评，1-差评，0-未评价
comment	varchar	评价内容
isFinish	tinyint	问题是否得以解决：0-没解决，1-已解决
ChatRecord	tinyint	有无文字聊天：0-无聊天记录，1-有聊天记录
Remote	tinyint	有无远程：0-没有发起远程，1-发起远程
TransferFile	tinyint	有无文件传输：0-没有传输文件，1-有传输文件
FileCount	tinyint	本次服务传输的文件个数
custom_fields	array	远程服务记录自定义字段
contents	varchar	聊天记录的资源 url

请求示例

响应示例

{
  "remoterecords": [
    {
      "csId": 123,
      "csIdS": "MjAxNy0wOC0xOCAxMDozMzowNQ==",
      "csBTime": "2017-8-27 10:21:10",
      "csETime": "2017-8-27 10:21:10",
      "csStat": 5,
      "csServicerId": 223,
      "csPrice": 234.00,
      "payStat": 1,
      "payDateTime": "2017-8-27 10:21:10",
      "companyName": "金万维科技有限公司",
      "contactor": "张三",
      "contactMethod": "13240138478"
    }
  ],
  "count": 42,
  "next_page": "https://www.bangwo8.com/api/v1/remoterecord/histories.json?per_page=40&page=2",
  "previous_page": null
}

获取指定客服的服务记录

请求参数

参数	类型	必填	说明
id	int	是	客服 ID
starttime	datetime	否	按创建时间筛选，开始时间，格式为：2017-08-27
endtime	datetime	否	按创建时间筛选，结束时间，格式为：2017-08-29
page	int	否	分页获取，默认为 1
per_page	int	否	每页大小，默认为 100

说明

结束时间是包含当前时间的

请求示例

获取远程协助记录的聊天记录

请求参数

参数	类型	必填	说明
id	int	是	服务记录 id
time_start	datetime	否	按聊天内容发送日期筛选：开始时间，格式为：2017-8-27
time_end	datetime	否	按聊天内容发送日期筛选：结束时间，格式为：2017-8-27，与 time_start 成对出现
page	int	否	分页获取，默认为 1
per_page	int	否	每页大小，默认为 100

说明

仅支持文本消息

响应字段

字段	类型	说明
remote_chatrecords	object	聊天记录对象
remote_chatrecords.csId	string	服务记录 id
remote_chatrecords.contents	array	聊天消息列表
count	int	消息总数
next_page	string	下一页 URL
previous_page	string	上一页 URL

消息对象字段

字段	类型	说明
spokesman	string	发言人的名字
spokesman_identity	tinyint	发言人的身份：1-客服，2-用户
msg	text	聊天内容
time	datetime	消息发送时间

请求示例

响应示例

{
    "remote_chatrecords": {
        "csId": "221",
        "contents": [
            {
                "spokesman": 213,
                "spokesman_identity": 1,
                "msg": "这里是具体的聊天内容",
                "time": "2017-8-23 13:12:23"
            },
            {
                "spokesman": 234,
                "spokesman_identity": 1,
                "msg": "这里是具体的聊天内容",
                "time": "2017-8-23 13:12:23"
            }
        ]
    },
    "count": 42,
    "next_page": "https://www.bangwo8.com/api/v1/remoterecord/chatrecords/221.json?per_page=40&page=2",
    "previous_page": null
}

获取服务总结（远程协助）

请求参数

参数	类型	必填	说明
csId	int	是	服务记录 id
servicesummary_type	int	是	服务总结类型：3-远程协助（1-IM，2-呼叫中心）

说明

获取远程协助的服务总结，servicesummary_type=3

响应字段

字段	类型	说明
status	string	状态码
message	string	状态说明
data	object	服务总结数据
data.ticketTemplateName	string	模板名称
data.custom_fields	array	服务总结模板自定义字段

错误响应

没有绑定服务总结模板：

{
    "status": "120001",
    "message": "No service summary template"
}

未填写服务总结：

{
    "status": "120002",
    "message": "No service summary information"
}

2.3.4 业务记录（服务总结）

获取业务记录列表

获取业务记录详情

修改业务记录

2.4 知识库

2.4.1 知识库条目

获取知识库列表

请求参数

参数	类型	必填	说明
created_start	string	否	按创建时间筛选，开始时间
created_end	string	否	按创建时间筛选，结束时间
updated_start	string	否	按更新时间查询，开始时间
updated_end	string	否	按更新时间查询，结束时间
created_order	string	否	按创建时间排序：asc（升序），desc（降序）
updated_order	string	否	按更新时间排序：asc（升序），desc（降序）
page	int	否	分页获取，默认为 1
per_page	int	否	每页大小，默认为 40，最大限制位 40
fId	int	否	分类 id（如果想获取"未分类"中的问题，该参数请传值"not"）
state	string	否	状态：0-草稿，1-待审核，2-已发布
isFAQ	string	否	是否常见问题：1-是，0-否

说明

默认按编码升序返回。时间参数格式为"2012-01-01 00:00:00"。

响应参数

参数	类型	说明
knowledge	array	知识库列表
count	int	总记录数
next_page	string	下一页 URL
previous_page	string	上一页 URL

knowledge 数组元素字段

参数	类型	说明
kId	int	知识库 ID
sQuestion	varchar	知识库的标题
sAnswer	varchar	知识库的答案
servicerId	int	添加知识库的客服 ID
state	tinyint	知识库的状态：0-未审核，1-已审核
reviewerId	int	审核知识库的客服 ID
goodRate	int	该条知识库的好评率
badRate	int	该条知识库的差评率
adoptCount	int	该条知识库被采纳次数
isFAQ	tinyint	是否被设为了常见问题：0-非常见问题，1-常见问题
relatedQuestion	varchar	该条知识库的关联问题
similarQuestion	varchar	该条知识库的相似问题
createDT	datetime	创建时间
updateDT	datetime	更新时间
sAttachment	array	知识库答案里的附件
fId	int	分类 id

返回示例

{
    "knowledge": [
        {
            "kId": "8741",
            "sQuestion": "晶体管的代换原则",
            "sAnswer": "类型相同、特性相近、外形相似",
            "servicerId": "0",
            "state": "0",
            "reviewerId": "",
            "goodRate": "0",
            "badRate": "0",
            "adoptCount": "0",
            "isFAQ": "0",
            "relatedQuestion": "",
            "createDT": "0000-00-00 00:00:00",
            "updateDT": "2016-06-28 10:55:04",
            "similarQuestion": "",
            "sAttachment": [
                {"fileName": "测试文件", "filePath": "https://alioss.bangwo8.com/128789/202501/17/xxxx.pdf"}
            ],
            "fId": "无分类"
        }
    ],
    "count": 42,
    "next_page": "https://www.bangwo8.com/api/v1/knowledge.json?per_page=40&page=2",
    "previous_page": null
}

获取知识库详情

请求参数

参数	类型	必填	说明
kid	string	是	知识库 ID

响应参数

参数	类型	说明
knowledge	object	知识库对象
knowledge.kId	int	知识库 ID
knowledge.url	varchar	该知识库的资源 url
knowledge.sQuestion	varchar	知识库的标题
knowledge.sAnswer	varchar	知识库的答案
knowledge.sAttachment	array	附件列表
knowledge.servicerId	int	添加知识库的客服 ID
knowledge.state	tinyint	状态：0-未审核，1-已审核
knowledge.reviewerId	int	审核知识库的客服 ID
knowledge.goodRate	int	好评率
knowledge.badRate	int	差评率
knowledge.adoptCount	int	被采纳次数
knowledge.isFAQ	tinyint	是否常见问题
knowledge.relatedQuestion	varchar	关联问题
knowledge.similarQuestion	array	相似问题
knowledge.createDT	datetime	创建时间
knowledge.updateDT	datetime	更新时间
knowledge.fId	int	分类 id

返回示例

{
    "knowledge": {
        "kId": "8741",
        "sQuestion": "晶体管的代换原则",
        "sAnswer": "类型相同、特性相近、外形相似",
        "servicerId": "0",
        "state": "0",
        "reviewerId": "",
        "goodRate": "0",
        "badRate": "0",
        "adoptCount": "0",
        "isFAQ": "0",
        "relatedQuestion": "",
        "similarQuestion": "",
        "createDT": "0000-00-00 00:00:00",
        "updateDT": "2016-06-28 10:55:04",
        "sAttachment": [
            {"fileName": "测试文件", "filePath": "https://alioss.bangwo8.com/128789/202501/17/xxxx.pdf"}
        ],
        "fId": "无分类"
    }
}

获取多条知识库

请求参数

参数	类型	必填	说明
ids	string	是	知识库 ID 列表，以逗号分隔，例如：8741,8745

响应参数

参数	类型	说明
knowledge	array	知识库列表

返回示例

{
    "knowledge": [
        {
            "kId": "8741",
            "sQuestion": "晶体管的代换原则",
            "sAnswer": "类型相同、特性相近、外形相似",
            "servicerId": "0",
            "state": "0",
            "reviewerId": null,
            "goodRate": "0",
            "badRate": "0",
            "adoptCount": "0",
            "isFAQ": "0",
            "relatedQuestion": "",
            "createDT": "0000-00-00 00:00:00",
            "updateDT": "2016-06-28 10:55:04",
            "sAttachment": [
                {"fileName": "测试文件", "filePath": "https://alioss.bangwo8.com/128789/202501/17/xxxx.pdf"}
            ],
            "fId": "无分类"
        }
    ]
}

创建知识库

请求参数

参数	类型	必填	说明
knowledge.sQuestion	string	是	问题标题
knowledge.sAnswer	string	是	答案内容，带 css 样式返回
knowledge.fId	int	否	知识库分类 ID
knowledge.isFAQ	int	否	是否常见问题：0-否，1-是
knowledge.relatedQuestion	string	否	相关问题
knowledge.similarQuestion	array	否	相似问题列表
knowledge.state	int	否	状态：0-草稿，1-待审核
knowledge.sAttachment	string	否	附件 token 列表，以逗号分隔

说明

新建知识库时，sQuestion 和 sAnswer 必填。

如果知识库答案带附件，需先调用上传附件接口获取 token。

sAnswer 值里的{数字}是附件的占位符，须从 1 开始连续编号，如{1}、{2}等。

sAttachment 为附件列表，以逗号分隔，顺序对应 sAnswer 里的占位符。

知识库答案为纯文本示例

知识库答案带附件示例

返回值

Status: 200 OK

Location: /api/v1/knowledge/{id}.json

返回示例

{
    "knowledge": {
        "kId": 11,
        "sQuestion": "我是知识库问题",
        ...
    }
}

修改知识库

请求参数

参数	类型	必填	说明
knowledge.sQuestion	string	否	问题标题
knowledge.sAnswer	string	否	答案内容
knowledge.fId	int	否	知识库分类 ID
knowledge.isFAQ	int	否	是否常见问题
knowledge.relatedQuestion	string	否	相关问题
knowledge.similarQuestion	array	否	相似问题列表
knowledge.state	int	否	状态
knowledge.sAttachment	string	否	附件 token 列表

调用示例

返回值

Status: 200 OK

返回示例

{
    "knowledge": {
        "kId": 11,
        "name": "知识库的问题",
        ...
    }
}

删除知识库

返回值

Status: 200 OK

2.4.2 知识库分类

获取知识库分类列表

响应参数

参数	类型	说明
knowledgeCategories	array	知识库分类列表

knowledgeCategories 数组元素字段

参数	类型	说明
kbcId	int	分类 ID
className	varchar	分类名称
parentId	int	上级分类 ID（0 为一级分类）

返回示例

{
    "knowledgeCategories": [
        {
            "kbcId": "8392",
            "className": "软件问题",
            "parentId": "0"
        },
        {
            "kbcId": "8395",
            "className": "具体 bug",
            "parentId": "8392"
        }
    ]
}

新增知识库分类

请求参数

参数	类型	必填	说明
className	string	是	分类名称
parentId	int	是	上级分类 ID，一级分类传 0

请求示例

{
    "knowledgeCategories": {
        "className": "软件问题",
        "parentId": 0
    }
}

返回值

Status: 200 OK

返回示例

{
    "status": "200",
    "kbcId": "8488",
    "message": "add successful!"
}

修改知识库分类

请求参数

参数	类型	必填	说明
className	string	是	分类名称
parentId	int	是	上级分类 ID，一级分类传 0

请求示例

{
    "knowledgeCategories": {
        "className": "应用问题",
        "parentId": 0
    }
}

返回值

Status: 200 OK

返回示例

{
    "knowledgeCategories": {
        "kbcId": "8392",
        "className": "应用问题",
        "parentId": "0"
    }
}

删除知识库分类

说明

删除分类后，原本属于该分类下的下级或上级的知识库中的 fId 值全部为 0，即全部划为无分类。

返回值

Status: 200 OK

返回示例

{
    "status": "200",
    "message": "delete successful!"
}

2.4.3 附件上传

上传附件

说明

URL 里需要增加 filename 参数来设置附件名

请求 header 里要设置"Content-Type: application/binary"

仅支持一次上传一个附件

调用示例

返回值

Status: 201 Created

Location: /api/v1/attachments/{id}.json

返回示例

{
    "attachment": {
        "attachId": 123,
        "fileName": "file.png",
        "filePath": "https://bangwo8.oss-cn-shenzhen.aliyuncs.com/18/Z28tfzPdB.png",
        "token": "15761b339251466e9fec23698503eb53"
    }
}

说明

上传成功后返回 token 值，该 token 可用于创建知识库时设置附件。

三、人员与组织

3.1 客服管理

3.1.1 获取客服列表

请求参数

参数	类型	必填	说明
page	int	否	页码，默认 1
per_page	int	否	每页数量，默认 100
created_start	date	否	创建时间开始
created_end	date	否	创建时间结束
updated_start	date	否	更新时间开始
updated_end	date	否	更新时间结束

响应参数

参数	类型	说明
supports	array	客服列表
count	int	总记录数
next_page	string	下一页 URL
previous_page	string	上一页 URL

Support 对象字段

参数	类型	说明
sId	int	客服 ID
sPassportName	varchar	客服登录名
groupId	int	所属分组 ID
sNum	varchar	客服编号
name	varchar	客服姓名
gnder	tinyint	性别（1-女，2-男）
email	varchar	邮箱
fixnumber	varchar	固定电话
mobile	varchar	手机号码
QQ	varchar	QQ 号码
isAdmin	tinyint	是否为管理员（0-否，1-是）
isStat	int	客服后台状态：1-在职，2-已从回收站中删除，0-在回收站中
createDT	datetime	创建时间
custom_fields	array	自定义字段

返回示例

{
    "supports": [
        {
            "sId": "563562",
            "sPassportName": "gzcs005",
            "groupId": "",
            "sNum": "005",
            "name": "刘经理",
            "gnder": "2",
            "email": "",
            "fixnumber": "",
            "mobile": "13076869445",
            "QQ": "",
            "isAdmin": "0",
            "createDT": "2019-08-15 16:29:05"
        }
    ],
    "count": "4",
    "next_page": "",
    "previous_page": ""
}

调用示例

3.1.2 获取客服详情

请求参数

参数	类型	必填	说明
sId	string	是	客服 ID

响应参数

参数	类型	说明
support	object	客服对象
support.sId	string	客服 ID
support.sPassportName	string	客服账号
support.groupId	string	所属分组 ID
support.sNum	string	客服工号
support.name	string	客服姓名
support.gnder	string	性别
support.email	string	邮箱
support.fixnumber	string	座机号码
support.mobile	string	手机号码
support.QQ	string	QQ 号码
support.isAdmin	string	是否管理员
support.createDT	string	创建时间
support.custom_fields	array	自定义字段

返回示例

{
    "support": {
        "sId": "563562",
        "sPassportName": "gzcs005",
        "groupId": "",
        "sNum": "005",
        "name": "刘经理",
        "gnder": "2",
        "email": "",
        "fixnumber": "",
        "mobile": "13076869445",
        "QQ": "",
        "isAdmin": "0",
        "createDT": "2019-08-15 16:29:05"
    }
}

调用示例

3.1.4 获取多个客服信息

请求参数

参数	类型	必填	说明
ids	string	是	客服 ID 列表，以逗号分隔，例如：1,2,3

响应参数

参数	类型	说明
supports	array	客服列表

返回示例

{
    "supports": [
        {
            "sId": 1,
            "name": "张三"
        },
        {
            "sId": 2,
            "name": "李四"
        }
    ]
}

调用示例

3.1.3 搜索客服

请求参数

参数	类型	必填	说明
query	string	是	搜索条件，格式：`字段名：值`
sort_by	string	否	按时间排序：createDT-创建时间，updateDT-更新时间
sort_order	string	否	升序/降序：asc-升序，desc-降序，默认为降序
page	int	否	页码
per_page	int	否	每页数量

支持的搜索字段：sPassportName（账号）、name（姓名）、sNum（工号）、mobile（手机号）

调用示例

3.1.5 创建客服

请求参数

参数	类型	必填	说明
support.sPassportName	varchar	是	客服账号，一旦创建无法修改
support.sNum	varchar	是	客服工号
support.groupId	varchar	否	客服分组 ID，多个用逗号分隔
support.name	varchar	否	客服姓名
support.gnder	tinyint	否	性别：1-女，2-男
support.email	varchar	否	电子邮箱
support.fixnumber	varchar	否	座机号码
support.mobile	varchar	否	手机号码
support.QQ	varchar	否	QQ 号码
support.isAdmin	tinyint	否	是否管理员：0-否，1-是

说明

创建客服时，sPassportName 和 sNum 必填。

多分组格式：{"groupId": "123,234"}

返回值

Status: 200 OK

Location: /api/v1/supports/{id}.json

返回示例

{
    "support": {
        "sId": "563562",
        "sPassportName": "gzcs005",
        "name": "刘经理"
    }
}

调用示例

3.1.6 修改客服

请求参数

参数	类型	必填	说明
supportId	int	是	客服 ID
support.name	varchar	否	客服姓名
support.groupId	varchar	否	客服分组 ID
support.gnder	tinyint	否	性别
support.email	varchar	否	邮箱
support.mobile	varchar	否	手机

返回值

Status: 200 OK

返回示例

{
    "support": {
        "sId": "563562",
        "sPassportName": "gzcs005",
        "name": "刘经理"
    }
}

调用示例

3.1.7 删除客服

返回值

Status: 200 OK

返回示例

{
    "support": {
        "sId": "563562",
        "sPassportName": "gzcs005"
    }
}

调用示例

3.1.8 恢复删除的客服

请求参数

参数	类型	必填	说明
servicerId	int	是	客服 ID
support.isStat	int	是	0-隐藏，1-显示

返回示例

{
    "support": {
        "sId": "1342642",
        "isStat": "1"
    }
}

调用示例

3.1.9 客服授权

请求参数

参数	类型	必填	说明
servicerId	int	是	客服 ID
permission.mType	int	是	模块类型：4-呼叫中心
permission.state	string	是	0-开启，1-关闭

返回示例

{
    "permission": {
        "sId": "2323",
        "mType": "4",
        "state": "0"
    }
}

调用示例

错误状态码

错误码	说明
403	The servicerId does not exist - 客服 ID 不存在

3.1.10 查看客服状态

请求参数

参数	类型	必填	说明
servicerId	int	是	客服 ID
plate	int	是	功能模块（1-工单，2-在线聊天，3-呼叫中心）

响应参数

参数	类型	说明
plate_service_state	object	客服状态对象
plate_service_state.sId	int	客服 id
plate_service_state.plate	int	功能模块
plate_service_state.state	varchar	客服状态

返回示例

{
    "plate_service_state": {
        "sId": 356789,
        "plate": "1",
        "state": "在线"
    }
}

调用示例

3.1.11 修改客服状态

请求参数

参数	类型	必填	说明
servicerId	int	是	客服 ID
plate_service_state.plate	int	是	功能模块（1-工单，2-在线聊天，3-呼叫中心）
plate_service_state.state	varchar	是	客服状态（后台设置的状态名称）

响应参数

参数	类型	说明
plate_service_state	object	客服状态对象
plate_service_state.sId	int	客服 id
plate_service_state.plate	int	功能模块
plate_service_state.state	varchar	客服状态

返回示例

{
    "plate_service_state": {
        "sId": 356789,
        "plate": "1",
        "state": "在线"
    }
}

调用示例

3.1.12 获取客服签到列表

请求参数

参数	类型	必填	说明
created_start	string	否	按创建时间筛选，开始时间
created_end	string	否	按创建时间筛选，结束时间
created_order	string	否	按创建时间排序：asc-升序，desc-降序
sId	int	否	按客服 id 进行筛选
page	int	否	分页获取，默认为 1
per_page	int	否	每页大小，默认为 100

响应参数

参数	类型	说明
signIn	array	签到列表
count	int	总记录数
next_page	string	下一页 URL
previous_page	string	上一页 URL

signIn 对象字段

参数	类型	说明
name	varchar	客服姓名
sNum	varchar	客服工号
remark	varchar	签到备注
attachments	varchar	签到附件（多个附件以逗号分隔）
tags	array	签到标签
checkinTime	datetime	签到时间
clockingPoint	varchar	签到地点（位置 + 经纬度）

返回示例

{
    "code": "0",
    "message": "success",
    "data": {
        "signIn": [
            {
                "name": "小明",
                "sNum": "56589",
                "remark": "备注一些内容",
                "attachments": "https://alioss.bangwo8.com/874731/202309/11/3iyze5cEnG.jpeg",
                "tags": [
                    "签到",
                    "测试 2"
                ],
                "checkinTime": "2017-09-12 10:12:22",
                "clockingPoint": "北京市北京市东城区，经度:116.40231、纬度:39.923807"
            }
        ],
        "count": 1456,
        "next_page": "",
        "previous_page": ""
    }
}

调用示例

3.1.13 创建客服签到

请求参数

参数	类型	必填	说明
signIn.remark	varchar	否	签到备注（最多 140 个汉字）
signIn.attachments	array	否	签到附件（最多 9 个）
signIn.tags	array	否	签到标签
signIn.checkinTime	datetime	是	签到时间
signIn.current	object	是	签到地点

current 对象字段

参数	类型	必填	说明
address	varchar	是	地图获取地址
landmark	varchar	是	详细地址
latitude	varchar	是	纬度
longitude	varchar	是	经度

返回示例

{
    "signIn": {
        "code": "0",
        "message": "success",
        "data": {
            "name": "小明",
            "sNum": "56589",
            "remark": "备注一些内容",
            "attachments": "https://alioss.bangwo8.com/874731/202309/11/3iyze5cEnG.jpeg",
            "tags": [
                "签到"
            ],
            "checkinTime": "2017-09-12 10:12:22",
            "current": {
                "address": "中国北京市丰台区看丹街道六圈路",
                "landmark": "汉威城",
                "latitude": "39.827126",
                "longitude": "116.302248"
            }
        }
    }
}

调用示例

3.1.14 获取客服排班列表

请求参数

参数	类型	必填	说明
startDT	datetime	否	开始日期（格式：2023-12-01）
endDT	datetime	否	结束日期（格式：2023-12-01）

响应参数

参数	类型	说明
duty	object	排班信息
duty.sid	int	客服 id
duty.date	datetime	日期
duty.schedules	array	排班列表

schedules 对象字段

参数	类型	说明
dutyId	int	排班 id
name	varchar	排班名称（最大 30 个汉字）
remark	varchar	备注
start_time	datetime	开始时间（格式：20:00:00）
end_time	datetime	结束时间（格式：20:00:00）
status	varchar	状态

返回示例

{
    "code": "0",
    "message": "ok",
    "data": {
        "duty": {
            "sid": "10591",
            "date": "2023-12-04",
            "schedules": [
                {
                    "dutyId": "10591_2023-12-04_656d4229600fa",
                    "name": "测试排班",
                    "remark": "备注",
                    "start_time": "12:01",
                    "end_time": "18:01",
                    "status": "1"
                }
            ]
        }
    }
}

调用示例

3.1.15 新增客服排班

请求参数

参数	类型	必填	说明
duty	array	是	排班信息
duty.sid	int	是	客服 sId
duty.date	datetime	是	排班日期（格式：2023-11-29）
duty.schedules	array	是	排班列表

schedules 对象字段

参数	类型	必填	说明
name	varchar	否	排班名称
remark	varchar	否	备注
start_time	datetime	是	开始时间（格式：15:00）
end_time	datetime	是	结束时间（格式：15:00）
url	string	否	点击排班后的跳转链接

返回示例

{
    "code": "0",
    "message": "success",
    "data": {
        "duty": [
            {
                "sid": "5675570",
                "date": "2023-11-07",
                "schedules": [
                    {
                        "dutyId": "5675570_2023-11-07_23",
                        "name": "周三 15:00-16:00",
                        "remark": "备注",
                        "start_time": "15:00",
                        "end_time": "16:00",
                        "url": "http://www.baidu.com"
                    }
                ]
            }
        ]
    }
}

调用示例

3.1.16 更新客服排班

请求参数

参数	类型	必填	说明
dutyId	string	是	排班 id（通过 URL 参数传递）
duty.name	varchar	否	排班名称
duty.remark	varchar	否	备注
duty.start_time	datetime	是	开始时间（格式：15:00）
duty.end_time	datetime	是	结束时间（格式：15:00）
duty.url	string	否	点击排班后的跳转链接

说明

修改接口只支持单条修改

不可修改排班的客服和日期，如果需要修改这两个参数需要删除原有的排班，创建一个新排班

返回示例

{
    "code": "0",
    "message": "ok",
    "data": {
        "duty": {
            "sid": "10591",
            "date": "2023-12-04",
            "schedules": [
                {
                    "dutyId": "10591_2023-12-04_656d4229600fa",
                    "name": "测试排班修改接口",
                    "remark": "测试修改",
                    "start_time": "12:01",
                    "end_time": "18:01",
                    "status": "1",
                    "url": "http://www.baidu.com"
                }
            ]
        }
    }
}

调用示例

3.1.17 删除客服排班

请求参数

参数	类型	必填	说明
dutyId	string	是	排班 id（通过 URL 参数传递）

说明

只能删除单条

不可删除今天当前时间之前的排班数据

返回示例

{
    "code": "0",
    "message": "ok",
    "data": {
        "duty": {
            "sid": "10591",
            "date": "2023-12-04",
            "schedules": [
                {
                    "dutyId": "10591_2023-12-04_656d4229600fa",
                    "name": "测试排班",
                    "remark": "测试修改",
                    "start_time": "12:01",
                    "end_time": "18:01",
                    "status": "1"
                }
            ]
        }
    }
}

3.2 客服组管理

3.2.1 获取客服组列表

响应参数

参数	类型	说明
supportgroups	array	客服分组列表

SupportGroup 对象字段

参数	类型	说明
sgId	int	客服分组 ID
sgName	varchar	客服分组名称
url	varchar	该客服分组的资源 URL

返回示例

{
  "supportgroups": [
    {
      "sgId": 1,
      "sgName": "北京办"
    },
    {
      "sgId": 2,
      "sgName": "上海办"
    }
  ]
}

3.2.2 获取客服组详情

响应参数

参数	类型	说明
supportgroup	object	客服分组对象

返回示例

{
  "supportgroup": {
    "sgId": 1,
    "sgName": "北京办"
  }
}

3.2.3 获取多个客服分组信息

请求参数

参数	类型	必填	说明
ids	string	是	客服分组 ID 列表，以逗号分隔

响应参数

参数	类型	说明
supportgroups	array	客服分组列表

返回示例

{
  "supportgroups": [
    {
      "sgId": 1,
      "sgName": "北京办"
    },
    {
      "sgId": 2,
      "sgName": "上海办"
    }
  ]
}

3.2.4 获取客服组下的客服

响应参数

参数	类型	说明
sgId	int	客服分组 ID
sgName	varchar	客服分组名称
supports	array	该分组下的客服列表
count	int	客服总数
previous_page	string	上一页 URL
next_page	string	下一页 URL

Support 对象字段

参数	类型	说明
sId	int	客服 ID
sPassportName	varchar	客服登录名
groupId	int	所属分组 ID
sNum	varchar	客服编号
name	varchar	客服姓名
gnder	tinyint	性别（1-女，2-男）
email	varchar	邮箱
fixnumber	varchar	固定电话
mobile	varchar	手机号码
QQ	varchar	QQ 号码
isAdmin	tinyint	是否为管理员（0-否，1-是）
createDT	datetime	创建时间

返回示例

{
  "sgId": 1,
  "sgName": "北京办",
  "supports": [
    {
      "sId": "563562",
      "sPassportName": "gzcs005",
      "groupId": "",
      "sNum": "005",
      "name": "刘经理",
      "gnder": "2",
      "email": "",
      "fixnumber": "",
      "mobile": "13076869445",
      "QQ": "",
      "isAdmin": "0",
      "createDT": "2019-08-15 16:29:05"
    },
    {
      "sId": "563570",
      "sPassportName": "gzcs006",
      "groupId": "",
      "sNum": "006",
      "name": "陈主管",
      "gnder": "1",
      "email": "",
      "fixnumber": "",
      "mobile": "15939833813",
      "QQ": "",
      "isAdmin": "0",
      "createDT": "2019-08-15 16:30:33"
    }
  ],
  "count": "4",
  "previous_page": "",
  "next_page": ""
}

3.2.5 创建客服组

请求参数

参数	类型	必填	说明
supportgroup.sgName	string	是	客服分组名称

返回值

Status: 200 OK

Location: /api/v1/supportgroups/{id}.json

返回示例

{
  "supportgroup": {
    "sgId": 1,
    "sgName": "北京办"
  }
}

3.2.6 修改客服组

请求参数

参数	类型	必填	说明
supportgroup.sgName	string	是	客服分组名称

返回值

Status: 200 OK

返回示例

{
  "supportgroup": {
    "sgId": 1,
    "sgName": "北京办"
  }
}

3.2.7 删除客服组

返回值

Status: 200 OK

返回示例

{
  "supports": {
    "sgId": "765607",
    "sgName": "gnwaycs",
    "url": "https://www.bangwo8.com/api/v1/supportgroups/765607.json"
  }
}

四、系统配置

4.1 表单管理

4.1.1 获取表单列表

说明

默认按编码升序返回。

响应参数

参数	类型	说明
forms	array	表单列表

Form 对象字段

参数	类型	说明
fId	int	表单 ID
url	varchar	该表单的资源 url
name	varchar	表单名称
key	varchar	表单的唯一标识，一旦创建后无法修改
descript	varchar	表单描述

返回示例

{
    "forms": [
        {
            "fId": "8741",
            "subject": "合同表",
            "key": "contract_table",
            "descript": "存储客户的合同"
        },
        {
            "fId": "8742",
            "subject": "资产表",
            "key": "asset_table",
            "descript": "存储客户购买的产品"
        }
    ]
}

4.1.2 获取表单详情

响应参数

参数	类型	说明
form	object	表单对象

返回示例

{
    "form": {
        "fId": 91739,
        "url": "https://www.bangwo8.com/api/v1/forms/91739.json",
        "subject": "合同表",
        "key": "contract_table",
        "descript": "这里是表单的描述"
    }
}

4.1.3 创建表单

请求参数

参数	类型	必填	说明
form.name	varchar	是	表单名称
form.key	varchar	否	表单唯一标识，不传则系统自动分配
form.descript	varchar	否	表单描述

返回示例

{
    "form": {
        "fId": 91739,
        "subject": "合同表",
        "key": "contract_table",
        "descript": "这里是表单的描述"
    }
}

4.1.4 修改表单

请求参数

参数	类型	必填	说明
form.name	varchar	否	表单名称
form.descript	varchar	否	表单描述

说明

表单的 key 字段一旦创建后无法修改。

返回示例

{
    "form": {
        "fId": 91739,
        "subject": "合同表",
        "key": "contract_table",
        "descript": "修改后的描述"
    }
}

4.1.5 删除表单

返回示例

{
    "form": {
        "fId": 91739,
        "subject": "合同表"
    }
}

4.2 表单字段

4.2.1 查询指定表单的字段列表

说明

默认按编码升序返回。

响应参数

参数	类型	说明
form_fields	array	表单字段列表

FormField 对象字段

参数	类型	说明
id	int	字段 ID
url	varchar	字段的资源 URL
name	varchar	字段名称
key	varchar	字段的唯一标识
type	int	字段类型
custom_field_options	array	下拉列表选项或级联目录

字段类型对照表

类型值	说明
1	下拉列表
2	单行文本
3	多行文本
4	正整数
5	小数
6	复选框
8	日期（格式：2018-02-03）
12	附件
13	评星
18	级联字段

返回示例

{
  "form_fields": [
    {
      "id": "24136421",
      "name": "测试省市级联",
      "key": "field_1",
      "type": "18",
      "custom_field_options": [
        {
          "key": "1",
          "value": "北京市",
          "subset_value": [
            {
              "key": "26",
              "value": "海淀区"
            },
            {
              "key": "27",
              "value": "朝阳区"
            }
          ]
        },
        {
          "key": "6",
          "value": "吉林省",
          "subset_value": [
            {
              "key": "29",
              "value": "长春市"
            },
            {
              "key": "30",
              "value": "吉林市"
            }
          ]
        }
      ]
    }
  ]
}

4.2.2 表单字段选项增加、更新

说明

对表单的下拉字段或级联字段进行选项的新增或更新操作。已存在的选项会更新，不存在的选项会新增。

请求参数

参数	类型	必填	说明
parentId	int	级联字段必填	帮我吧选项父级 ID（一级填 0）
extendParentId	int	否	选项外部扩展父级 ID（一级不传）
optionName	string	是	字段选项名称
optionId	int	否	帮我吧内选项 ID（更新时传入）
extendId	int	否	外部扩展 ID（级联字段有，下拉字段暂不可用）

级联字段请求示例

[
    {
        "parentId": "0",
        "optionName": "选项 1"
    },
    {
        "parentId": "1",
        "optionName": "选项 3",
        "optionId": "28"
    }
]

下拉字段请求示例

[
    {
        "optionName": "选项 1"
    },
    {
        "optionName": "选项 2",
        "optionId": "002"
    }
]

返回参数

参数	类型	说明
columnId	int	字段 ID
name	string	字段名称
key	string	字段唯一标识
type	int	字段类型（1-下拉字段，18-级联字段）
custom_field_options	array	字段选项列表

custom_field_options 字段选项列表说明

参数	类型	说明
optionId	int	选项 ID
optionName	string	字段名称
extendId	int	外部扩展 ID（级联字段展示）

返回示例（下拉字段）

{
  "columnId": "24917015",
  "name": "ipaas 下拉字段",
  "key": "field_14",
  "type": "1",
  "custom_field_options": [
    {
      "optionId": "358769",
      "optionName": "选项 1"
    },
    {
      "optionId": "358770",
      "optionName": "选项 2"
    }
  ]
}

4.2.3 表单字段选项删除

请求参数

参数	类型	必填	说明
optionId	int	至少一个	帮我吧内选项 ID
extendId	int	至少一个	外部扩展 ID

说明

optionId 和 extendId 两个参数至少使用一个。

返回参数

参数	类型	说明
optionId	int	帮我吧内选项 ID
optionName	string	字段选项名称
extendId	int	外部扩展 ID

返回示例

{
  "optionId": "358771",
  "optionName": "选项 3",
  "extendId": "11"
}

4.3 资产表

资产表是表单的一种，可在帮我吧后台设置某个表单用作资产表。将资产表关联到客户档案后，可用于记录客户资产，如合同表、购买明细、回访记录等。

4.3.1 获取资产表的所有数据

说明

默认按编码升序返回。

响应参数

参数	类型	说明
asset_table	array	资产表数据列表

Asset 对象字段

参数	类型	说明
rId	int	资产表某条数据的 ID
tableId	int	资产表 ID
ownerType	varchar	资产表数据的所属人类型：agent-服务商，servicer-客服，contacter-联系人，company-公司，servicerGroup-客服组
owner	int	资产表数据的所属人 ID
ticketId	int	工单的唯一标识 ID
unique_key	varchar	唯一值的字段唯一标识
unique_value	varchar	唯一值的取值
createTime	datetime	创建时间
updateTime	datetime	更新时间
relative_ticket_columnId	varchar	资产表对应的工单字段的 ID
field_*	-	自定义字段（如 field_1, field_2 等）

返回示例

{
  "asset_table": [
    {
      "rId": "67",
      "field_1": "榴莲千层",
      "field_2": "5",
      "field_4": "4524913",
      "field_5": [],
      "field_3": "",
      "relative_ticket_columnId": "24441346",
      "field_6": "",
      "owner": "1331193",
      "ownerType": "servicer",
      "tableId": "3785437",
      "createTime": "2022-04-01 14:19:07",
      "updateTime": "2022-04-01 14:19:07",
      "ticketId": "22497808"
    },
    {
      "rId": "65",
      "field_1": "旺仔牛奶",
      "field_2": "1000",
      "field_3": "010",
      "field_5": [
        {
          "fileName": "部件.png",
          "fileUrl": "874731/PZ6nBYMJA3.png"
        }
      ],
      "field_6_pid": "o1",
      "field_6_curId": "o27",
      "field_6": "北京市 - 丰台区",
      "relative_ticket_columnId": "24441346",
      "owner": "1331193",
      "ownerType": "servicer",
      "tableId": "3785437",
      "createTime": "2022-04-01 14:19:07",
      "updateTime": "2022-04-01 14:19:07",
      "ticketId": "22497808"
    }
  ]
}

4.3.2 给资产表添加一行数据

请求参数

参数	类型	必填	说明
item_data	object	是	资产数据对象
item_data.owner	int	是	所属人 ID
item_data.ownerType	varchar	是	所属人类型
item_data.ticketId	int	否	工单 ID
item_data.field_*	-	否	自定义字段
item_data.relative_ticket_columnId	varchar	否	对应的工单字段 ID

说明

级联字段传输格式为 "字段唯一标识":"aa-bb-cc"（如 "field_6": "吉林省 - 长春市"）。

请求示例

{
    "item_data": {
        "owner": "1331193",
        "ownerType": "servicer",
        "ticketId": "356786",
        "field_1": "旺仔小馒头",
        "field_2": "1000",
        "field_3": "011",
        "field_5": [
            {
                "fileName": "file1.png",
                "fileUrl": "https://s2.loli.net/2022/03/18/lVYR7pDi3bG4HLm.png"
            }
        ],
        "field_6": "吉林省 - 长春市",
        "relative_ticket_columnId": "26559664"
    }
}

返回示例

{
  "item_data": {
    "rId": "69",
    "ticketId": "356786",
    "field_1": "旺仔小馒头",
    "field_2": "1000",
    "owner": "1331193",
    "ownerType": "servicer",
    "tableId": "3785437",
    "createTime": "2022-04-01 14:29:56",
    "updateTime": "2022-04-01 14:29:56"
  }
}

4.3.3 给资产表添加多行数据

请求参数

参数	类型	必填	说明
items_data	array	是	资产数据数组

请求示例

{
    "items_data": [
        {
            "field_1": "测试多条 1",
            "field_2": "50",
            "owner": "1331193",
            "ownerType": "servicer",
            "relative_ticket_columnId": "24441346"
        },
        {
            "field_1": "测试多条 2",
            "ownerType": "servicer",
            "relative_ticket_columnId": "24441346"
        }
    ]
}

返回示例

{
  "items_data": [
    {
      "result_flag": "SUCCESS",
      "rId": "255",
      "field_1": "测试多条 1",
      "field_2": "50",
      "owner": "1331193",
      "ownerType": "servicer"
    },
    {
      "result_flag": "FAIL",
      "error_info": "请选择所属人",
      "field_1": "测试多条 2",
      "ownerType": "servicer"
    }
  ]
}

4.3.4 根据唯一值更新资产表一行数据

请求参数

参数	类型	必填	说明
unique_key	varchar	是	唯一值的字段唯一标识
unique_value	varchar	是	唯一值的取值
item_data	object	是	资产数据对象

请求示例

{
    "item_data": {
        "rId": "5",
        "owner": "65047",
        "ownerType": "servicer",
        "cpmc": "帮我吧",
        "cpdm": "XF345",
        "tableId": "61748"
    }
}

返回示例

{
  "item_data": {
    "rId": "5",
    "cpdm": "20190102555",
    "cpmc": "",
    "tableId": "61748",
    "owner": "65047",
    "ownerType": "servicer",
    "createTime": "2019-01-15 14:34:47",
    "updateTime": "2019-01-15 14:34:47"
  }
}

4.3.5 根据 ID 更新资产表一行数据

请求参数

参数	类型	必填	说明
item_data	object	是	资产数据对象

请求示例

{
    "item_data": {
        "owner": "65047",
        "ownerType": "servicer",
        "cpmc": "帮我吧",
        "cpdm": "XF345",
        "tableId": "61748"
    }
}

4.3.6 删除资产表一行数据

返回示例

{
  "result": {
    "rId": 5,
    "tableId": 61748,
    "success": true,
    "error_log": ""
  }
}

4.3.7 搜索资产表中的资产数据

请求参数

参数	类型	必填	说明
query	string	是	搜索内容
page	number	否	页码，默认为 1
per_page	number	否	每页大小，默认为 20

Query 参数说明

搜索内容	返回结果
`ownerType:servicer owner:1331193`	返回客服 sId 为"1331193"的所有资产
`ticketId:19665409 field_1:甜甜圈`	返回工单 ticketId 为"19665409"且自定义字段 field_1 值为"甜甜圈"的所有资产
`ticketId:null`	返回工单 ticketId 为空的所有资产
`updateTime:2021-12-03`	返回更新时间为 2021-12-03 的资产
`createTime>=2021-12-03 updateTime<=2022-09-03`	返回创建时间在 2021-12-03 之后且更新时间在 2022-09-03 之前的资产

注意事项

暂不支持搜索内容本身带有空格

多个条件之间需以空格分隔，如 ownerType:servicer owner:1331193

自定义字段与系统字段格式相同，空格隔开即可，如 ticketId:19665409 field_1:甜甜圈

请求示例

返回示例

{
  "asset_table": {
    "total": "2",
    "datas": [
      {
        "rId": "19",
        "field_1": "甜甜圈",
        "field_2": "25",
        "owner": "1331193",
        "ownerType": "servicer",
        "tableId": "3785437",
        "createTime": "2021-11-11 14:25:06",
        "updateTime": "2021-11-11 14:25:06"
      },
      {
        "rId": "25",
        "field_1": "甜甜圈",
        "field_2": "60",
        "ticketId": "19665409",
        "owner": "1331193",
        "ownerType": "servicer",
        "tableId": "3785437",
        "createTime": "2021-11-11 14:29:36",
        "updateTime": "2021-11-11 14:34:16"
      }
    ]
  }
}

4.4 自定义字段配置

4.4.1 联系人字段

查询联系人字段列表

获取系统或自定义的联系人（用户）字段定义列表，包括字段类型、是否为系统字段以及选项配置。

调用者权限: 管理员

UserField 对象字段

参数	类型	说明
id	int	字段 ID，系统字段默认为 1
name	varchar	字段显示名称
key	varchar	字段的唯一标识
type	int	字段类型：1-下拉列表，2-单行文本，3-多行文本，4-正整数，5-小数，6-复选框，7-正则表达式，8-日期，12-附件，14-高级复选框，17-电话，18-级联
system	tinyint	是否为系统字段：1-是，0-否
custom_field_options	array	选项/目录列表（下拉列表或级联字段）

返回示例

{
  "user_fields": [
    {
      "id": "1",
      "name": "姓名",
      "key": "name",
      "type": "2",
      "system": "1",
      "custom_field_options": []
    },
    {
      "id": "24795771",
      "name": "地区",
      "key": "field_3",
      "type": "18",
      "system": "0",
      "custom_field_options": [
        {
          "key": "1",
          "value": "北京市",
          "subset_value": [
            {
              "key": "26",
              "value": "海淀",
              "subset_value": [
                {"key": "28", "value": "中关村"},
                {"key": "29", "value": "清华"}
              ]
            },
            {"key": "27", "value": "朝阳"}
          ]
        },
        {"key": "6", "value": "吉林省"}
      ]
    },
    {
      "id": "24799067",
      "name": "联系人类型",
      "key": "field_4",
      "type": "1",
      "system": "0",
      "custom_field_options": [
        {"key": "4457267", "value": "VIP"},
        {"key": "4457271", "value": "普通联系人"}
      ]
    }
  ]
}

4.4.2 公司字段

查询公司字段列表

获取公司字段定义列表，包括字段类型、是否为系统字段以及选项配置。

调用者权限: 管理员

CompanyField 对象字段

参数	类型	说明
id	int	字段 ID，系统字段默认为 1
url	varchar	字段的资源 URL
name	varchar	字段名称
key	varchar	字段的唯一标识
type	int	字段类型（同联系人字段）
system	tinyint	是否为系统字段：1-是，0-否
custom_field_options	array	选项/目录列表

返回示例

{
  "company_fields": [
    {
      "id": "1",
      "name": "公司名称",
      "key": "companyName",
      "type": "2",
      "system": "1",
      "custom_field_options": []
    },
    {
      "id": "24797907",
      "name": "公司类型",
      "key": "field_2",
      "type": "1",
      "system": "0",
      "custom_field_options": [
        {"key": "4457111", "value": "互联网"},
        {"key": "4457115", "value": "金融"}
      ]
    },
    {
      "id": "24797963",
      "name": "地址",
      "key": "field_4",
      "type": "18",
      "system": "0",
      "custom_field_options": [
        {
          "key": "1",
          "value": "北京市",
          "subset_value": [
            {
              "key": "403",
              "value": "海淀区",
              "subset_value": [
                {"key": "3230", "value": "中关村"},
                {"key": "3231", "value": "清华"}
              ]
            }
          ]
        }
      ]
    }
  ]
}

4.4.3 工单字段

查询工单自定义字段列表

获取所有工单自定义字段（不包含系统字段）的列表。

调用者权限: 所有客服

TicketField 对象字段

参数	类型	说明
id	int	字段 ID
url	varchar	字段的资源 URL
name	varchar	字段名称
key	varchar	字段的唯一标识
system	tinyint	是否为系统字段：1-是，0-否
type	int	字段类型：1-下拉列表，2-单行文本，3-多行文本，4-正整数，5-小数，6-复选框，7-正则表达式，8-日期，11-表单，12-附件，13-评星，14-高级复选框，15-商品表，16-满意度评价表，17-电话，18-级联，20-资产表，23-签字
isRequired	tinyint	是否必选：1-非必选，0-必选
isReadonly	tinyint	是否只读：1-只读，0-可编辑
custom_field_options	array	下拉列表、高级复选框选项或级联目录

返回示例

[
  {
    "id": "8769479",
    "name": "新梯数据表",
    "key": "field_1",
    "type": "12",
    "isRequired": "0",
    "isReadonly": "0"
  },
  {
    "id": "8781221",
    "name": "确认情况",
    "key": "field_15",
    "type": "1",
    "isRequired": "0",
    "isReadonly": "0",
    "custom_field_options": [
      {"key": "1197569", "value": "安装局确认"},
      {"key": "1197572", "value": "安装师傅确认"}
    ]
  }
]

查询工单字段列表（包含系统字段）

调用者权限: 所有客服

返回参数与 ticket_fields.json 相同，但包含 system=1 的系统字段。

下拉字段选项全量覆盖

使用新选项列表完全替换指定下拉字段的所有选项。

调用者权限: 管理员

请求参数

参数	类型	必填	说明
optionName	string	是	字段选项名称
extendId	int	否	外部扩展 ID

请求示例

[
  {"optionName": "选项 1", "extendId": "001"},
  {"optionName": "选项 2", "extendId": "002"},
  {"optionName": "选项 3", "extendId": "003"}
]

返回示例

{
  "columnId": "24917015",
  "name": "ipaas 下拉字段",
  "key": "field_14",
  "type": "1",
  "custom_field_options": [
    {"optionId": "358769", "optionName": "选项 1", "extendId": "001"},
    {"optionId": "358770", "optionName": "选项 2", "extendId": "002"},
    {"optionId": "358771", "optionName": "选项 3", "extendId": "003"}
  ]
}

新增、修改字段选项内容

对下拉字段或级联字段进行选项的新增或更新。

调用者权限: 管理员

请求参数

参数	类型	必填	说明
parentId	int	级联字段必填	级联选项父级 ID（一级填 0）
extendParentId	int	否	级联选项外部扩展父级 ID
optionName	string	是	字段选项名称
extendId	int	否	选项的外部扩展 ID

下拉字段请求示例

[
  {"optionName": "选项 1", "extendId": "001"},
  {"optionName": "选项 2", "extendId": "002"}
]

级联字段请求示例

[
  {"parentId": "0", "optionName": "选项 1", "extendId": "001"},
  {"parentId": "1", "optionName": "选项 1", "extendId": "011"}
]

删除字段选项内容

删除指定字段的某个选项。

调用者权限: 管理员

请求参数

参数	类型	必填	说明
optionId	int	至少一个	帮我吧中字段选项 ID
extendId	int	至少一个	外部扩展 ID

返回示例

{
  "optionId": "358771",
  "optionName": "选项 3",
  "extendId": "003"
}

4.5 客服分组管理

4.5.1 获取客服分组列表

请求参数

参数	类型	必填	说明
page	int	否	页码，默认 1
per_page	int	否	每页数量，默认 100

响应字段

字段	类型	说明
groupId	int	客服组 ID
groupName	string	客服组名称
groupNote	string	备注
createTime	datetime	创建时间
updateTime	datetime	更新时间

请求示例

响应示例

{
  "supportgroups": [
    {
      "groupId": "1001",
      "groupName": "售前客服组",
      "groupNote": "负责售前咨询",
      "createTime": "2023-01-15 10:30:00",
      "updateTime": "2023-06-20 14:20:00"
    },
    {
      "groupId": "1002",
      "groupName": "售后客服组",
      "groupNote": "负责售后服务",
      "createTime": "2023-01-15 10:35:00",
      "updateTime": "2023-06-20 14:25:00"
    }
  ],
  "count": 2,
  "next_page": null,
  "previous_page": null
}

4.5.2 获取客服分组详情

路径参数

参数	类型	必填	说明
groupId	int	是	客服组 ID

响应示例

{
  "supportgroup": {
    "groupId": "1001",
    "groupName": "售前客服组",
    "groupNote": "负责售前咨询",
    "createTime": "2023-01-15 10:30:00",
    "updateTime": "2023-06-20 14:20:00"
  }
}

4.5.3 创建客服分组

请求参数

参数	类型	必填	说明
groupName	string	是	客服组名称
groupNote	string	否	备注

请求示例

响应示例

{
  "supportgroup": {
    "groupId": "1003",
    "groupName": "VIP 客服组",
    "groupNote": "负责 VIP 客户服务",
    "createTime": "2023-07-01 09:00:00",
    "updateTime": "2023-07-01 09:00:00"
  }
}

4.5.4 修改客服分组

请求参数

参数	类型	必填	说明
groupName	string	否	客服组名称
groupNote	string	否	备注

请求示例

4.5.5 删除客服分组

响应示例

{
  "status": "success",
  "message": "客服分组已删除"
}

4.6 工单查询器管理

4.6.1 获取工单查询器列表

响应字段

名称	类型	注释
id	int	查询器id，系统自动分配
url	varchar	查询器的资源url
title	varchar	查询器名称
active	tinyint	查询器是否启用，取值为：0-未启用，1-启用，默认启用。
ticket_count	int	查询器包含的工单数量。用GET方式传递了fields=show_tickets_num时会显示该参数
createDT	datetime	查询器的创建时间
updateDT	datetime	查询器的更新时间
请求示例

响应示例

{
    "ticketviews": [
        {
            "id": "1",
            "title": "所有工单",
            "active": "0",
            "createDT": "2019-08-16 00:00:08",
            "updateDT": ""
        },
        {
            "id": "2",
            "title": "最近7天工单",
            "active": "0",
            "createDT": "2019-12-08 16:11:23",
            "updateDT": "2019-12-08 16:13:40"
        }
    ]
}

4.6.2 获取工单查询器详情

请求参数

名称	类型	注释
id	int	查询器id

请求地址

GET /api/v1/ticketviews/{id}.json

调用示例

返回参数

名称	类型	注释
id	int	查询器id，系统自动分配
title	varchar	查询器名称
active	tinyint	查询器是否启用，取值为：0-未启用，1-启用，默认启用。
ticket_count	int	查询器包含的工单数量。用GET方式传递了fields=show_tickets_num时会显示该参数
createDT	datetime	查询器的创建时间
updateDT	datetime	查询器的更新时间

返回示例

{
    "ticketview": {
        "id": "9",
        "title": "未解决的工单",
        "active": "0",
        "createDT": "2019-08-16 00:00:07",
        "updateDT": ""
    }
}

4.6.3 获取指定工单查询器里的工单

请求参数

名称	类型	注释
id	int	查询器id

请求地址

GET /api/v1/ticketviews/{id}/tickets.json

调用示例

返回参数

名称	类型	必填	描述
ticketId	int	是	工单id，系统自动生成
custUserId	int	否	联系人id，说明该工单是为该客户解决问题
subject	String	是	工单标题
descript	String	是	工单描述
servicerUserId	int	否	受理客服id
ccUserIdList	string	否	抄送客服id列表
ticketType	int	否	工单类型：1–问题，2–事务，3–故障，4–任务
priorityLevel	int	否	工单优先级：1–低，2–正常，3–高，4–紧急
tagList	int	否	工单标签列表，以逗号分隔
ticketStatus	int	否	工单状态：1–新建，2–已开启，3–待回应，4–已解决，5–自动关闭，6–手动关闭
createDT	datetime	是	工单创建时间
updateDT	datetime	是	工单更新时间
solveDT	datetime	否	解决时间
waitDT	datetime	否	等待时间
openDT	datetime	否	开启时间
closeDT	datetime	否	关闭时间
servicerGroupId	int	否	受理客服组id
createrId	int	是	工单创建人id
createrType	int	是	工单创建人类型，0-客服 1-客户
agentId	int	是	关联agents表aId
ticketSource	int	否	工单来源：1–远程，2–聊天，3–呼叫中心，4–留言，5–系统创建，7–API，8–工单模板发布，9–邮件接入
ticketTemplateId	int	是	工单模板id，创建工单需指明当前工单使用哪个工单模板
ccGroupIdList	string	否	抄送客服组id列表
customTemplateId	int	否	客户模板id
createrType	String	否	创建类型
custom_fields	array	否	工单自定义字段

返回示例

{
    "tickets": [
        {
            "ticketId": "1",
            "subject": "测试工单",
            "descript": "",
            "ticketSource": "工单工作台",
            "ticketType": "",
            "priorityLevel": "",
            "ticketStatus": "新建",
            "custUserId": "21130282",
            "servicerUserId": "565123",
            "ticketTemplateId": "21130282",
            "tagList": "",
            "createDT": "2019-12-19 14:28:51",
            "updateDT": "2019-12-19 14:37:26",
            "custom_fields": [
                {
                    "key": "field_12",
                    "value": "合同制定"
                },
                {
                    "key": "field_14",
                    "value": "合同流转"
                },
                {
                    "key": "field_16",
                    "value": [
                        {
                            "name": "195151szk8umd8or8fmfa5.jpg",
                            "uri": "386279/snNyQASjsh.jpg",
                            "datetime": "2019-12-19 14:28:48"
                        }
                    ]
                },
                {
                    "key": "field_17",
                    "value": "0"
                },
                {
                    "key": "field_18",
                    "value": "0"
                },
                {
                    "key": "field_19",
                    "value": ""
                },
                {
                    "key": "field_20",
                    "value": ""
                },
                {
                    "key": "field_21",
                    "value": "0"
                },
                {
                    "key": "field_22",
                    "value": "sign0"
                },
                {
                    "key": "field_23",
                    "value": "0"
                },
                {
                    "key": "field_24",
                    "value": ""
                },
                {
                    "key": "field_25",
                    "value": "a:4:{s:2:\"SN\";s:16:\"xpt87wm7u4a64lv4\";s:5:\"total\";i:0;s:4:\"data\";a:0:{}s:10:\"isAppraise\";i:0;}"
                },
                {
                    "key": "field_27",
                    "value": "vvv"
                },
                {
                    "key": "field_29",
                    "value": "123.00"
                },
                {
                    "key": "field_30",
                    "value": "测试"
                },
                {
                    "key": "field_31",
                    "value": "测试"
                },
                {
                    "key": "field_32",
                    "value": "2019-12-20"
                },
                {
                    "key": "field_33",
                    "value": "a:3:{s:2:\"SN\";s:16:\"0oi3ov3jne6l7fuu\";s:5:\"total\";i:0;s:4:\"data\";a:0:{}}"
                },
                {
                    "key": "field_34",
                    "value": "低"
                },
                {
                    "key": "field_35",
                    "value": "近（1-15公里）"
                }
            ]
        }
    ],
    "count": "8",
    "previous_page": "",
    "next_page": ""
}

4.6.4 获取指定工单查询器的工单个数

请求参数

名称	类型	注释
id	int	查询器id

请求地址

GET /api/v1/ticketviews/{id}/count.json

调用者权限

所有客服

调用示例

返回参数

名称	类型	注释
ticketview_id	int	查询器id
count	int	该查询器下的工单总数

返回示例

{
    "ticketview_count": [
        {
            "ticketview_id": "15",
            "count": "7"
        }
    ]
}

4.6.5 删除工单查询器

4.7 工单模板管理

4.7.1 获取工单模板列表

请求参数

参数	类型	必填	说明
page	int	否	页码，默认 1
per_page	int	否	每页数量，默认 100

响应字段

字段	类型	说明
templateId	int	模板 ID
templateName	string	模板名称
templateDesc	string	模板描述
priority	int	默认优先级：1-低，2-正常，3-高，4-紧急
groupId	int	默认客服组 ID
createTime	datetime	创建时间

请求示例

响应示例

{
  "tickettemplates": [
    {
      "templateId": "201",
      "templateName": "售后支持模板",
      "templateDesc": "用于售后支持工单",
      "priority": "2",
      "groupId": "1002",
      "createTime": "2023-03-15 11:00:00"
    },
    {
      "templateId": "202",
      "templateName": "售前咨询模板",
      "templateDesc": "用于售前咨询工单",
      "priority": "1",
      "groupId": "1001",
      "createTime": "2023-03-15 11:30:00"
    }
  ],
  "count": 2,
  "next_page": null,
  "previous_page": null
}

4.7.2 获取工单模板详情

路径参数

参数	类型	必填	说明
templateId	int	是	模板 ID

响应示例

{
  "tickettemplate": {
    "templateId": "201",
    "templateName": "售后支持模板",
    "templateDesc": "用于售后支持工单",
    "priority": "2",
    "groupId": "1002",
    "createTime": "2023-03-15 11:00:00"
  }
}

4.7.3 获取多个工单查询器的工单个数

请求参数

名称	类型	注释
id	int	查询器id

请求地址

GET /api/v1/ticketviews/show_many.json?ids={ids}

调用者权限

所有客服

调用示例

返回参数

名称	类型	注释
ticketview_id	int	查询器id
count	int	该查询器下的工单总数

返回示例

{
    "ticketview_counts": [
        {
            "ticketview_id": "15",
            "count": "7"
        },
        {
            "ticketview_id": "2",
            "count": "23"
        }
    ]
}

请求参数

参数	类型	必填	说明
templateName	string	是	模板名称
templateDesc	string	否	模板描述
priority	int	否	默认优先级：1-低，2-正常，3-高，4-紧急
groupId	int	否	默认客服组 ID

请求示例

响应示例

{
  "tickettemplate": {
    "templateId": "203",
    "templateName": "VIP 客户模板",
    "templateDesc": "用于 VIP 客户工单",
    "priority": "3",
    "groupId": "1003",
    "createTime": "2023-07-01 10:00:00"
  }
}

4.7.4 修改工单模板

请求示例

4.7.5 删除工单模板

响应示例

{
  "status": "success",
  "message": "工单模板已删除"
}

4.8 客户分组管理

客户分组管理接口同 2.1.2 客户分组，请参考该章节。

4.9 短信服务

数据模型

SmsTemplate (短信模板) 对象

名称	类型	必填	注释
`name`	str	否	短信模板名称
`content`	str	是	短信正文
`id`	int	是	短信模板 ID
`createTime`	date	否	短信模板创建时间
`marks`	str	否	短信模板备注
`sign_info`	obj	否	短信签名内容
`text_info`	obj	否	短信正文内容

sign_info (签名信息) 对象

名称	类型	注释
`name`	str	签名名称
`remarks`	str	签名备注
`sign_id`	str	签名 ID

text_info (正文信息) 对象

名称	类型	注释
`name`	str	正文名称
`content`	str	正文内容
`remarks`	str	正文备注
`text_id`	str	正文 ID

接口列表

4.9.1 获取短信模板列表

获取所有短信模板的列表信息。

请求方法: GET

请求路径: /api/v1/smstemplist.json

调用者权限: 管理员

调用示例

返回值示例

{
    "code": "0",
    "message": "success",
    "data": {
        "page": "1",
        "pageSize": "300",
        "total": "6",
        "templates": [
            {
                "name": "618 活动快到期的用户续费提醒",
                "content": "亲爱的帮我吧远程个人版用户，您好！您的会员即将到期，618 大促正在进行中！续费远程产品可享最高五折优惠，还有额外的赠送年限，限时折扣等您来拿！抓住机会，立即续费，省钱更省心！详情请咨询客服或访问官网。别错过哦！拒收请回复 R",
                "id": "650",
                "createTime": "2024-06-19 16:38:39",
                "marks": "快到期的用户 618 活动续费提醒",
                "sign_info": {
                    "name": "帮我吧",
                    "remarks": "系统默认短信签名",
                    "sign_id": "22352"
                },
                "text_info": {
                    "name": "618 活动即将到期的续费提醒",
                    "content": "亲爱的帮我吧远程个人版用户，您好！您的会员即将到期，618 大促正在进行中！续费远程产品可享最高五折优惠，还有额外的赠送年限，限时折扣等您来拿！抓住机会，立即续费，省钱更省心！详情请咨询客服或访问官网。别错过哦！拒收请回复 R",
                    "remarks": "",
                    "text_id": "2188842"
                }
            }
        ]
    }
}

4.9.2 发送短信

使用指定模板或直接内容发送短信。

请求方法: POST

请求路径: /api/v1/sendsms.json

调用者权限: 管理员

请求参数

名称	类型	必填	注释
`tpl_id`	string	是	短信模板 ID
`mobile`	string	是	接收短信的手机号码
`content`	string	是	短信内容

调用示例

返回值示例

{
    "code": "0",
    "message": "success",
    "data": []
}

通用说明

认证方式: OAuth2 Bearer Token

基础 URL: https://www.bangwo8.com

数据格式: JSON

4.10 服务商设置

概述

客户注册帮我吧后，都会获得一个"服务商账号"，用于接口请求时的身份验证。以下接口均与服务商账号相关。

数据模型

Agent (服务商账号) 对象

名称	类型	只读	必填	注释
`agentId`	int	是	否	服务商 ID，系统自动生成
`agentAccount`	varchar	是	否	服务商账号
`dueDate`	date	是	是	服务商账号到期时间

JSON 示例

{
    "agentId": 1103,
    "agentAccount": "osp-test",
    "dueDate": "2018-09-09"
}

接口列表

4.10.1 获取服务商账号到期时间

获取当前服务商账号的基本信息及到期时间。

请求方法: GET

请求路径: /api/v1/agent/agent_info.json

调用者权限: 服务商账号

调用示例

返回值示例

{
  "agent_info": {
    "agentId": 110,
    "agentAccount": "osp-test",
    "dueDate": "2018-09-09"
  }
}

通用说明

认证方式: OAuth2 Bearer Token

基础 URL: https://www.bangwo8.com

数据格式: JSON

4.11 外部扩展集成

参见接口文档

五、呼叫中心

5.1 获取客服话机状态

获取指定客服或当前客服的话机状态信息，包括通话状态、话机注册状态、整理状态和工作台状态。

调用者权限: 管理员

请求参数

参数	类型	必填	说明
action	string	是	获取客服状态，固定填写：`serviceState`
sPassportName	string	否	客服账号。传该参数时查询对应账号客服的话机状态，不传则查询调用接口客服账号的话机状态

响应字段

字段	类型	说明
idleState	int	通话状态：`1`-忙碌，`0`-空闲
voipStatus	int	话机状态：`1`-已注册，`2`-未注册
arrangeState	int	整理状态：`1`-整理中，`0`-非整理状态
state	int	工作台状态：`0`-在线，`1`-离线，`2`-忙碌（系统状态）；其他值为自定义状态

返回示例

{
    "status": "0",
    "message": "success",
    "data": {
        "idleState": "0",
        "voipStatus": "2",
        "arrangeState": "0",
        "state": "0"
    }
}

状态说明对照表

字段	值	含义
idleState	`0`	空闲
idleState	`1`	忙碌
voipStatus	`1`	话机已注册
voipStatus	`2`	话机未注册
arrangeState	`0`	非整理状态
arrangeState	`1`	整理中
state	`0`	在线
state	`1`	离线
state	`2`	忙碌（系统状态）

5.2 接听模式切换

切换指定客服的电话接听模式（手机接听或话机接听）。

调用者权限: 管理员

路径参数

参数	类型	必填	说明
sId	int	是	客服 ID

请求体参数

参数	类型	必填	说明
answerMode.callAccessMode	int	是	接入模式：`0` - 手机接听，`1` - 话机接听

请求示例

{
    "answerMode": {
        "callAccessMode": "0"
    }
}

返回示例

{
    "permission": {
        "sId": "3232",
        "callAccessMode": "0"
    }
}

5.3 SDK网页集成(CC)

参见接口文档

六、在线客服

在线客服接口，用于 Web 前端/移动端集成

6.1 SDK网页集成(IM)

参见接口文档

七、公共接口

7.1 获取 Token

认证方式: HTTP Basic Auth（账号密码由 API 密钥管理页面创建）

请求参数

参数	类型	必填	说明
grant_type	string	是	固定值：client_credentials

响应参数

参数	类型	说明
access_token	string	认证 token
expires_in	int	过期时间 3600s
token_type	string	Bearer

说明

接口用户名和密码需从后台 API 秘钥管理界面创建

token 默认有效期 1 小时，建议缓存并在 3540 秒后刷新

7.2 标签接口

数据模型

Tag (标签) 对象

名称	类型	只读	必填	注释
`tagId`	int	是	否	标签 ID，系统自动生成
`url`	varchar	是	否	该标签的资源 URL
`tagName`	varchar	否	是	标签名称
`module`	int	否	是	标签所属模块（详见下方模块对照表）

模块类型对照表

值	模块
`2`	远程模块
`3`	上门模块
`4`	即时聊天模块
`5`	呼叫中心模块
`6`	在线客服模块
`7`	工单模块

JSON 示例

{
    "tagId": 1,
    "url": "https://www.bangwo8.com/api/v1/tags/1.json",
    "tagName": "售后",
    "module": 6
}

接口列表

获取标签列表

获取所有标签的列表信息。

请求方法: GET

请求路径: /api/v1/tags.json

调用者权限: 所有客服

调用示例

返回值示例

{
  "tags": [
    {
      "tagId": 1,
      "tagName": "售后",
      "module": 6
    },
    {
      "tagId": 2,
      "tagName": "售前",
      "module": 4
    }
  ]
}

附录

A. 错误码

错误码	说明
100047	无效的资源 URI
110001	created_start 时间格式错误
110002	created_end 时间格式错误
110009	page 参数错误
110010	per_page 参数错误
110011	参数必须是正整数
110013	没有传递用户值
110024	参数错误
110025	ids 参数无效
110026	联系人不存在
110032	sPassportName 不能为空
110033	sPassportName 格式错误
110034	sPassportName 已存在
110035	sNum 不能为空
110036	sNum 格式错误
110037	sNum 已存在
110038	name 超长
110039	创建失败
110040	客服不存在
110041	修改失败
110042	没有有效的更新值
110050	QQ 格式错误
110055	gnder 参数错误
110056	邮箱格式错误
110057	isAdmin 参数错误
110058	sPassportName 不能修改
110061	groupId 格式错误
110062	groupId 不存在
120051	自定义字段无效
19001	参数错误
19003	没有相关权限
19008	权限被拒绝
19101	参数错误
40001	认证失败
40002	重复请求

B. 字段类型说明

类型	说明	示例
string	字符串	"张三"
int	整数	123
datetime	日期时间	"2025-01-01 12:00:00"
date	日期	"2025-01-01"
array	数组	["选项 1", "选项 2"]
object	对象	{"key": "value"}
boolean	布尔值	true/false

C. 更新日志

版本	日期	更新内容
1.0.14	2026-04-05	完善 4.1 表单管理、4.2 表单字段、4.3 资产表接口：新增表单列表、详情、创建、修改、删除接口，完善表单字段选项增删改接口，完善资产表数据增删改查和搜索接口
1.0.13	2026-04-05	完善 3.1 客服管理接口：新增获取多个客服信息、恢复删除的客服、开通呼叫中心权限、查看/修改客服状态、客服签到、客服排班接口
1.0.12	2026-04-05	完善 3.1 客服管理和 3.2 客服组管理接口：新增客服创建、修改、删除接口，完善客服组管理接口文档，补充响应参数和返回示例
1.0.11	2026-04-05	完善 2.4 知识库接口：新增知识库列表、详情、创建、修改、删除接口文档，完善知识库分类管理接口文档，补充附件上传接口文档
1.0.10	2026-04-05	完善 2.3.3 远程协助记录接口：修正路由为 /api/v1/remoterecord/*，新增服务记录列表、指定客服服务记录、聊天记录、服务总结接口
1.0.9	2026-04-04	完善 2.3.2 CC 服务记录接口：新增获取指定客服的通话记录列表、获取服务总结（CC）、录音解冻接口到 apifox.json
1.0.8	2026-04-05	完善 2.3.2 CC 服务记录接口：修正路由为 /api/v1/callrecord/*，新增通话记录列表、指定手机号/客服通话记录、通话记录详情、录音解冻接口
1.0.7	2026-04-05	完善 2.3 IM 服务记录接口：补充 IM 会话列表、聊天记录详情、客服在线状态、服务总结接口，修复路由错误
1.0.6	2026-04-04	重新组织文档结构，按业务领域分类
1.0.5	2026-04-04	新增业务记录相关接口
1.0.4	2026-04-04	新增知识库分类管理接口、完善标签接口字段说明
1.0.3	2026-04-04	新增呼叫中心接听模式切换接口、完善获取客服话机状态接口参数说明
1.0.2	2026-04-03	新增表单管理接口
1.0.1	2026-04-03	新增服务记录接口
1.0.0	2026-04-01	初始版本

接口地图

帮我吧 API v1 接口文档#

目录#

一、快速入门#

1.1 基本信息#

1.2 认证方式#

OAuth2 Bearer Token（推荐）#

Basic Auth (不推荐)#

1.3 公共请求头#

1.4 响应格式#

成功响应#

错误响应#

1.5 通用状态码#

1.6 最佳实践#

二、核心业务实体#

2.1 客户与联系人#

2.1.1 联系人管理#

获取联系人列表#

获取多个联系人详情#

批量联系人详情#

搜索联系人#

创建联系人#

修改联系人#

删除联系人#

批量删除联系人#

2.1.2 客户分组#

获取客户分组列表#

获取客户分组详情#

批量分组详情#

创建客户分组#

修改客户分组#

获取分组用户#

2.1.3 联系人字段#

获取联系人字段列表#

2.1.4 公司管理#

获取公司列表#

获取公司详情#

批量公司详情#

创建公司#

修改公司#

删除公司#

批量删除公司#

搜索公司#

2.1.5 公司字段#

获取公司字段列表#

2.1.6 获取公司联系人#

2.1.7 远程 ID 管理#

获取远程ID信息#

修改远程ID备注#

远程ID绑定联系人#

解绑远程 ID#

2.2 工单系统#

2.2.1 工单管理#

获取工单列表#

获取工单详情#

批量工单详情#

搜索工单#

创建工单#

修改工单#

批量修改工单#

工单拆单#

2.2.2 工单回复#

获取工单回复列表#

2.2.3 工单附件#

上传工单附件#

2.2.4 工单模板#

获取工单模板列表#

批量工单模板#

获取工单模板详情#

获取模板字段#

2.2.5 工单字段#

获取工单自定义字段#

获取工单所有字段#

覆盖字段选项#

更新字段选项#

删除字段选项#

2.2.6 工单查询器#

获取工单查询器列表#

获取工单查询器详情#

获取查询器工单列表#

帮我吧 API v1 接口文档

目录

一、快速入门

1.1 基本信息

1.2 认证方式

OAuth2 Bearer Token（推荐）

Basic Auth (不推荐)

1.3 公共请求头

1.4 响应格式

成功响应

错误响应

1.5 通用状态码

1.6 最佳实践

二、核心业务实体

2.1 客户与联系人

2.1.1 联系人管理

获取联系人列表

获取多个联系人详情

批量联系人详情

搜索联系人

创建联系人

修改联系人

删除联系人

批量删除联系人

2.1.2 客户分组

获取客户分组列表

获取客户分组详情

批量分组详情

创建客户分组

修改客户分组

获取分组用户

2.1.3 联系人字段

获取联系人字段列表

2.1.4 公司管理

获取公司列表

获取公司详情

批量公司详情

创建公司

修改公司

删除公司

批量删除公司

搜索公司

2.1.5 公司字段

获取公司字段列表

2.1.6 获取公司联系人

2.1.7 远程 ID 管理

获取远程ID信息

修改远程ID备注

远程ID绑定联系人

解绑远程 ID

2.2 工单系统

2.2.1 工单管理

获取工单列表

获取工单详情

批量工单详情

搜索工单

创建工单

修改工单

批量修改工单

工单拆单

2.2.2 工单回复

获取工单回复列表

2.2.3 工单附件

上传工单附件

2.2.4 工单模板

获取工单模板列表

批量工单模板

获取工单模板详情

获取模板字段

2.2.5 工单字段

获取工单自定义字段

获取工单所有字段

覆盖字段选项

更新字段选项

删除字段选项

2.2.6 工单查询器

获取工单查询器列表

获取工单查询器详情

获取查询器工单列表

获取查询器工单总数