侧边栏

文档首页


CRM扩展

数据接口

呼叫能力

Android IM SDK手册(暂停使用)

iOS IM SDK手册(暂停使用)

Android SIP SDK手册

iOS SIP SDK手册

客户端标准版快速集成

帮我吧远程SDK版本

网页在线客服集成

微信接入

帮我吧文档:数据接口:客服:客服

客服接口


JSON格式

名称 类型 只读 必填 注释
sId int 是 否 客服ID,系统自动生成
url varchar 是 否 该客服的资源url
sPassportName varchar 是 是 客服账号,一旦创建就无法修改
password varchar 是 否 客服密码 ,不传值则默认为管理员在帮我吧后台设置密码
groupId varchar 是 否 客服所属分组ID,系统自动生成,一个客服可属于多个分组,此时以逗号分隔,具体格式见JSON示例
sNum varchar 否 是 客服工号
name varchar 否 否 客服姓名
gnder tinyint 否 否 客服性别:1-女,2-男,默认是1
email varchar 否 否 电子邮箱
fixnumber varchar 否 否 座机号码
mobile varchar 否 否 手机号码
QQ varchar 否 否 QQ号码
isAdmin tinyint 否 否 是否是管理员:0-非管理员,1-管理员,默认为0
isStat int 是 否 客服后台状态,1-在职 2-已从回收站中删除 0-在回收站中
createDT datetime 是 否 创建时间,格式为:2018-02-03 00:00:00
custom_fields array 是 否 自定义字段

JSON示例

{
     "sId": 1,
     "url": "https://www.bangwo8.com/api/v1/supports/1.json",
     "sPassportName": "张三",
     "groupId": "123,234",
     "sNum": "888",
     "name": "张三",
     "gnder": "2",
     "email": "601100987@gnway.com",
     "fixnumber": "010-63701717-8280",
     "mobile": "13240139489",
     "QQ": "601100987",
     "isAdmin": "0",
     "createDT": "2017-09-12 10:12:22"
}

获取客服列表

GET /api/v1/supports.json

查询参数

名称 必需的 类型 注释
created_start 否 string 按创建时间筛选,开始时间
created_end 否 string 按创建时间筛选,结束时间
created_order 否 string 按创建时间排序,取值为:asc-升序,desc-降序
page 否 int 分页获取,默认为1
per_page 否 int 每页大小,默认为100

说明:默认按编码升序返回。时间参数(created_start、created_end)格式为“2012-01-01 00:00:00”。

调用者权限

管理员

调用示例

curl https://www.bangwo8.com/api/v1/supports.json \
  -v -u {account}:{password}

返回值示例

Status: 200 OK

{
	"supports": [
		{
			"sId": 1,
			"name": "张三",
			...
		},
		{
			"sId": 2,
			"name": "李四",
			...
		}
	],
        "count": 42,
        "next_page": "https://www.bangwo8.com/api/v1/supports.json?per_page=40&page=2",
        "previous_page": null
}

查看指定客服信息

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

调用者权限

所有客服

调用示例

curl https://www.bangwo8.com/api/v1/supports/{id}.json \
  -v -u {account}:{password}

返回值示例

Status: 200 OK

{
  "support": {
    "sId": "1331193",
    "sPassportName": "13039209552",
    "groupId": "344124,344214,344215,344216,344217",
    "sNum": "001",
    "name": "管理员",
    "gnder": "1",
    "email": "",
    "fixnumber": "",
    "mobile": "13039209552",
    "QQ": "",
    "isAdmin": "1",
    "createDT": "2021-09-27 17:05:38"
    "custom_fields": [
            {
                "key": "field_1", 
                "value": "4464896"
            },
            {
                "key": "field_2",
                "value": "文本内容"
            }
     ]
  }
}

获取多个客服信息

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

调用者权限

管理员

调用示例

curl https://www.bangwo8.com/api/v1/supports/show_many.json?ids=1,2,3 \
  -v -u {account}:{password}

返回值示例

Status: 200 OK

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

创建客服

POST /api/v1/supports.json

调用者权限

管理员

调用示例

curl -v -u {account}:{password} https://www.bangwo8.com/api/v1/supports.json \
  -H "Content-Type: application/json" -X POST -d '{
    "support": {
        "sPassportName": "13039209552",
        "groupId": "344124,344214,344215,344216,344217",
        "sNum": "001",
        "name": "管理员",
        "gnder": "1",
        "email": "",
        "fixnumber": "",
        "mobile": "13039209552",
        "QQ": "",
        "isAdmin": "1",
        "custom_fields": [
            {
                "key": "field_1",    //下拉字段
                "value": "下拉选项内容"   //下拉选项内容
            },
            {
                "key": "field_2",    //单行文本
                "value": "文本内容"   //单行文本内容
            },
            {
                "key": "field_3",        //多行文本
                "value": "多行文本内容"    //多行文本内容
            },
            {
                "key": "field_4",        //正整数
                "value": "5"             //正整数内容
            },
            {
                "key": "field_5",        //小数
                "value": "12.00"         //小数内容
            },
            {
                "key": "field_6",        //复选框
                "value": "是"            //选中为”是“,未选中为”否“
            },
            {
                "key": "field_7",        //日期
                "value": "2023-02-12"    //日期内容
            },
            {
                "key": "field_8",        //正则表达式
                "value": "go.*d"         //正则表达式内容
            },
            {
                "key": "field_9",        //附件
                "value":[                //附件内容
                  {
                      "fileName":"file1.org", //命名需要有后缀才能在工单中正确显示
                      "fileUrl":"https://huixing.org" 
                  }, 
                  {
                      "fileName":"file2.org",
                      "fileUrl":"https://huixing.org" 
                  }
                  ]
             },
             {
                "key": "field_10",        //高级复选款
                "value": "苹果,香蕉"       //高级复选框选项内容
             },
             {
                "key": "field_11",        //级联
                "value": [                //选项id
                    "北京市",
                    "丰台区",
                    "丰科万达"
                ]
            }
        ]
    }
}'

说明:
1、创建客服时,sPassportName和sNum必填。
2、当一个客服属于多个分组时,多个分组以逗号分隔,具体格式如下:{“groupId”: “123,234”}。

返回值示例

Status: 200 OK
Location: https://www.bangwo8.com/api/v1/supports/{id}.json

{
  "support": {
    "sId":   11,
    "name": "张三",
    ...
  }
}

修改客服信息

PUT /api/v1/supports/{id}.json

调用者权限

所有客服

调用示例

curl -v -u {account}:{password} https://www.bangwo8.com/api/v1/supports/123.json \
  -H "Content-Type: application/json" -X PUT -d '{"support": {"name": "张三"}}'

返回值示例

Status: 200 OK

{
  "support": {
    "sId":   11,
    "name": "张三",
    ...
  }
}

删除客服信息

DELETE /api/v1/supports/{id}.json

调用者权限

管理员

调用示例

curl -v -u {account}:{password} https://www.bangwo8.com/api/v1/supports/932845.json \
  -H "Content-Type: application/json"
  -X DELETE

返回值示例

Status: 200 OK
{
    "support": {
        "sId": "932845",
        "sPassportName": "gnly003",
        "groupId": "264586,266059",
        "sNum": "003",
        "name": "卢园",
        "gnder": "1",
        "email": "",
        "fixnumber": "",
        "mobile": "15506843512",
        "QQ": "",
        "isAdmin": "0",
        "createDT": "2020-06-02 11:42:20"
    }
}

搜索客服信息

GET /api/v1/supportgroups/supports/search.json

查询参数

名称 必需的 类型 注释
query 是 string 搜索内容(模糊搜索)
sort_by否 string 按时间排序,目前支持:createDT-创建时间,updateDT-更新时间
sort_order否 string 按升序还是降序返回,取值为:asc-升序,desc-降序,默认为降序

说明:默认按编码升序返回。时间参数(created_start、created_end)格式为“2012-01-01 00:00:00”。

query参数说明

搜索内容 返回结果
query=sPassportName:ademi 搜索客服账号为ademi的客服信息
query=name:陆华搜索客服姓名为陆华的客服信息
query=sNum:001搜索客服工号为001的客服信息
query=mobile:15586943723搜索客服手机号码为15586943723的客服信息(通过手机号账号查询客服的时候,每10条会分页显示)

调用者权限

管理员

调用示例

curl https://www.bangwo8.com/api/v1/supportgroups/supports/search.json?query=sPassportName:ademi
  -H "Content-Type: application/json" \
   -v -u {account}:{password} -X GET

返回值示例

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

恢复删除的客服

PUT /api/v1/servicers/{sId}.json

请求参数

名称 必需的 类型 注释
isStat是 int 客服是否生效0:隐藏,1:显示

调用示例

curl -v -u {account}:{password} https://www.bangwo8.com/api/v1/servicers/1342642.json -X PUT -d '{"support": {"isStat": "1"}}'

返回值示例

Status: 200 OK
{
  "support": {
    "sId":"1342642",
    "isStat": "1"
  }
}

开通呼叫中心权限

请求参数

名称 必需的 类型 注释
sId 是 int 客服id
mType 是 int 模块类型:4-呼叫中心
state 是 string 开启关闭:0开启1关闭

请求地址

PUT /api/v1/permissions/{sId}.json

调用者权限 管理员

调用示例

curl https://www.bangwo8.com/api/v1/permissions/3232.json \
  -H "Content-Type: application/json" \
  -d '{"permission": {"mType": "4","state":"0" }}' \-v -u {account}:{password} -X PUT

返回值示例

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

当客服ID不存在时返回

{
    "status":403,
    "message":"The sId does not exist"
}

查看客服状态

请求参数

名称 必需的 类型 注释
plate 是 int 功能模块(1-工单,2-在线聊天,3-呼叫中心)

请求地址

GET /api/v1/plate_service_state/{sId}.json

调用者权限

管理员

调用示例

curl  -X GET -v -u {account}:{password} https://www.bangwo8.com/api/v1/plate_service_state/356789.json?plate=2

返回参数

名称 类型 注释
sId int 客服id
plate int 功能模块(1-工单,2-在线聊天,3-呼叫中心)
state varchar 客服状态(后台设置的状态名称)

返回值示例

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

修改客服状态

请求参数

名称 必需的 类型 注释
plate 是 int 功能模块(1-工单,2-在线聊天,3-呼叫中心)
state 是 varchar 客服状态(后台设置的状态名称)

请求地址

PUT /api/v1/plate_service_state/{sId}.json

调用者权限

管理员

调用示例

curl https://www.bangwo8.com/api/v1/plate_service_state/674890.json \
  -H "Content-Type:application/json" \
  -d '{
             "plate_service_state":{
                      "plate":"1",
                      "state":"在线"
              }
}' \
 -v -u {account}:{password} -X PUT

返回参数

名称 类型 注释
sId int 客服id
plate int 功能模块(1-工单,2-在线聊天,3-呼叫中心)
state varchar 客服状态(后台设置的状态名称)

返回值示例

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

获取客服签到列表

请求地址

GET /api/v1/signin.json

查询参数

名称 必需的 类型 注释
created_start 否 string 按创建时间筛选,开始时间
created_end 否 string 按创建时间筛选,结束时间
created_order 否 string 按创建时间排序,取值为:asc-升序,desc-降序
sId 否 int 按客服id进行筛选
page 否 int 分页获取,默认为1
per_page 否 int 每页大小,默认为100

说明:默认按编码升序返回。时间参数(created_start、created_end)格式为“2012-01-01 00:00:00”。

调用者权限

管理员

调用示例

curl --location --request GET 'http://www.bangwo8.com/api/v1/signin.json?sId=67859&per_page=100&page=1' \
--header 'Authorization: Basic MTMwMzkyMDk1NTI6bGN4NTI8' \
--header 'Cookie: TFAPICLNTID=747335697c39afc1a113a2506b9579be; acw_tc=2760825416935340767362025e78b9cc1e095a07c37e610c4167002930232b'

返回参数

名称 类型 注释
name varchar 客服姓名
sNum varchar 客服工号
remark varchar 签到备注
attachments varchar 签到附件
tags array 签到标签(展示标签内容)
checkinTime datetime 签到时间
clockingPoint varchar 签到地点(位置+经纬度)

返回值示例

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

创建客服签到

请求地址

POST /api/v1/signin.json

查询参数

名称 必需的 类型 注释
remark 否 varchar 签到备注(字数最多为140个,字母/数字/符号占一个字数)
attachments 否 array 签到附件(最多9个附件)
tags 否 array 签到标签
checkinTime 是 datetime 签到时间
current 是 array 签到地点(位置+经纬度)

current参数说明:

名称 必需的 类型 注释
address 是 varchar 地图获取地址
landmark 是 varchar 详细地址
latitude 是 varchar 维度
longitude 是 datetime 精度

调用者权限

管理员

调用示例

curl --location --request POST 'https:www.bangwo8.com/api/v1/signin.json' \
--header 'Authorization: Basic MTMwMzkyMDk1NTI6bGN4NTI4' \
--header 'Content-Type: application/json' \
--data-raw '{
    "signIn": {
        "remark": "备注一些内容",
        "attachments": [
            {
                "fileName": "file1.jpg",
                "fileUrl": "https://huixing.jpg"
            },
            {
                "fileName": "file2.png",
                "fileUrl": "https://huixing.png"
            }
        ],
        "tags": [
            "签到",
            "测试2",
            "a",
            "b"
        ],
        "checkinTime": "2017-09-12 10:12:22",
        "current" : {
            "address" : "中国北京市丰台区看丹街道六圈路",
            "landmark" : "汉威城",
            "latitude" : "39.827126",
            "longitude" : "116.302248"
        }
    }
}'

返回参数

名称 类型 注释
name varchar 客服姓名
sNum varchar 客服工号
remark varchar 签到备注
attachments varchar 签到附件
tags array 签到标签(展示标签内容)
checkinTime datetime 签到时间
clockingPoint varchar 签到地点(位置+经纬度)

返回值示例

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

获取客服排班列表

请求地址

GET /api/v1/supports.json

查询参数

名称 必需的 类型 注释
startDT 否 datetime 开始日期(格式:2023-12-01)
endDT 否 datetime 结束日期(格式:2023-12-01)

调用者权限

管理员

调用示例

curl --location 'http://www.bangwo8.com/api/v1/schedules.json?startDT=2023-12-01&endDT=2023-12-31' \
--header 'Authorization: Basic b3NwdGVzdDoxMjMxMjNh' \
--header 'Cookie: TFAPICLNTID=4046a4103ce9b0a340ee0d63f1ec0cd5'

返回参数

名称 类型 注释
sid int 客服id
date datetime 日期
schedules array 排班列表

schedules参数

名称 类型 注释
dutyId int 客服id
name varchar 排班名称(最大30个汉字)
remark varchar 备注
start_time datetime 开始时间 格式为:20:00:00
start_time datetime 结束时间 格式为:20:00:00

返回值示例

Status: 200 OK
{
    "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"
                    }
                ]
            ]
        }
    }
}

新增客服排班

请求地址

POST  /api/v1/schedules.json

请求参数

名称 必需的 类型 注释
sid 是 int 客服sId
date 是 datetime 排班日期(格式:2023-11-29)
schedules 是 array 排班列表

schedules参数内容

名称 必需的 类型 注释
name 否 varchar 排班名称
remark 否 varchar 备注
start_time 是 datetime 开始时间(格式:15:00)
end_time 是 datetime 结束时间(格式:15:00)
url 否 string 点击排班后的跳转链接

调用者权限

管理员

调用示例

curl --location --request POST 'http://www.bangwo8.com/api/v1/schedules.json' \
--header 'Authorization: Basic Y2hlbmZlbmcxMjEzODpjZjEyMzQ1Ng==' \
--header 'Content-Type: application/json' \
--data-raw '{
    "duty":[
        {
            "sid":"5675570",
            "date":"2023-11-07",
            "schedules":[
                {
                    "name":"周三15:00-16:00",
                    "remark":"备注备注一些东西",
                    "start_time":"15:00",
                    "end_time":"16:00",
                    "url":"http://www.baidu.com"
                }
            ]
        },
        {
            "sid":"2235666",
            "date":"2023-11-07",
            "schedules":[
                {
                    "name":"是个名",
                    "remark":"备注备注一些东西",
                    "start_time":"15:00",
                    "end_time":"16:00"
                },
                {
                    "name":"周三18:00-19:00",
                    "start_time":"15:00",
                    "end_time":"16:00"
                }
            ]
        }
    ]
}}'

返回参数

名称 类型 注释
sid int 客服id
date datetime 日期
schedules array 排班列表

schedules参数

名称 类型 注释
dutyId int 排班id
name varchar 排班名称(最大30个汉字)
remark varchar 备注
start_time datetime 开始时间 格式为:20:00
start_time datetime 结束时间 格式为:20: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"
                    }
                ]
            },
            {
                "sid":"2235666",
                "date":"2023-11-07",
                "schedules":[
                    {
                        "dutyId":"2235666_2023-11-07_24",
                        "name":"是个名",
                        "remark":"备注备注一些东西",
                        "start_time":"15:00",
                        "end_time":"16:00"
                    },
                    {
                        "dutyId":"2235666_2023-11-07_25",
                        "name":"周三18:00-19:00",
                        "start_time":"15:00",
                        "end_time":"16:00"
                    }
                ]
            }
        ]
    }
}

更新客服排班

请求地址

PUT  /api/v1/schedules.json

说明: ①修改接口只支持单条修改。 ②不可修改排班的客服和日期,如果需要修改这两个参数需要删除原有的排班,创建一个新排班。

请求参数

名称 必需的 类型 注释
name 否 varchar 排班名称
remark 否 varchar 备注
start_time 是 datetime 开始日期(格式:2023-12-01)
end_time 是 datetime 结束日期(格式:2023-12-01)
url 否 string 点击排班后的跳转链接

调用者权限

管理员

调用示例

curl --location --request PUT 'http://www.bangwo8.com/api/v1/schedules.json?dutyId=10591_2023-12-04_656d4229600fa' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Y2hlbmZlbmcxMjEzODpjZjEyMzQ1Ng==' \
--data '{
    "duty": {
        "name": "周三15:00-16:00",
        "remark": "备注备注一些东西",
        "start_time": "15:00",
        "end_time": "16:00",
        "url":"http://www.baidu.com"
    }
}'

返回参数

名称 类型 注释
sid int 客服id
date datetime 日期
schedules array 排班列表

schedules参数

名称 类型 注释
dutyId int 客服id
name varchar 排班名称(最大30个汉字)
remark varchar 备注
start_time datetime 开始时间 格式为:20:00:00
start_time datetime 结束时间 格式为:20:00:00

返回值示例

{
    "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"
                }
            ]
        }
    }
}

删除客服排班

请求地址

DELETE  /api/v1/schedules.json

说明:①只能删除单条 ②不可删除今天当前时间之前的排班数据

调用者权限

管理员

调用示例

curl --location --request DELETE 'http://www.bangwo8.com/api/v1/schedules.json?dutyId=10591_2023-12-04_656d4229600fa' \
--header 'Authorization: Basic Y2hlbmZlbmcxMjEzODpjZjEyMzQ1Ng=='

返回参数

名称 类型 注释
sid int 客服id
date datetime 日期
schedules array 排班列表

schedules参数

名称 类型 注释
dutyId int 排班id
name varchar 排班名称(最大30个汉字)
remark varchar 备注
start_time datetime 开始时间 格式为:20:00:00
start_time datetime 结束时间 格式为:20:00:00

返回值示例

{
    "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"
                }
            ]
        }
    }
}

错误状态码

错误码 注释
10011 该客服不存在
10012 功能模块输入不正确
10013 输入的客服状态在后台无匹配值

页面工具