侧边栏

文档首页

CRM扩展

数据接口

呼叫能力

Android IM SDK手册（暂停使用）

iOS IM SDK手册（暂停使用）

—-

Android SIP SDK手册

iOS SIP SDK手册

客户端标准版快速集成

帮我吧远程SDK版本

网页在线客服集成

微信接入

工单:工单_客服

目录

工单(客服)接口

此接口仅供客服使用。

JSON格式

名称 类型 只读 必填 注释
ticketId int 是 否 工单ID，系统自动生成
url string 是 否 该工单的url地址
subject string 否 是 工单标题
descript string 否 否 工单描述，即第一条工单回复的文本内容
ticketSource int 否 否 工单来源：1–远程，2–聊天，3–呼叫中心，4–留言，5–系统创建
ticketType int 否 否 工单类型：1–问题，2–事务，3–故障，4–任务
priorityLevel int 否 否 工单优先级：1–低，2–正常，3–高，4–紧急
ticketStatus int 否 是 工单状态：1–新建，2–已开启，3–待回应，4–已解决，5–自动关闭，6–手动关闭
custUserId int 否 是 联系人ID
agentId int 否 否 服务商ID
createrId int 否 否 创建人ID
servicerUserId int 否 否 客服ID
servicerGroupId int 否 否 客服组ID
ccUserIdList string 否 否 抄送人ID列表
ccGroupIdList string 否 否 抄送组ID列表
ticketTemplateId int 否 否 工单模板ID
tagList string 否 否 工单标签列表
createDT date 是 否 创建时间
updateDT date 是 否 更新时间
custom_fields array 否 否 工单自定义字段

JSON示例 

{
     "ticketId": 1,
     "url": "https://www.bangwo8.com/api/v1/tickets/1.json",
     "subject": "产品咨询",
     "description": "帮我吧是什么？",
     "ticketSource": 0,
     "ticketType": 1,
     "priorityLevel": 2,
     "ticketStatus": 0,
     "custUserId": 121,
     "agentId": 37809,
     "createrId": 0,
     "servicerUserId": 234,
     "servicerGroupId": 0,
     "ccUserIdList": "123,456,789",
     "ccGroupIdList": "2432,3455,2323"
     "tagList": "vip客户,普通客户",
     "createDT": "2017-05-04 14:08:22",
     "updateDT": "2017-05-04 14:08:22",
     "custom_fields": [
      {
          "key": "field_1",
          "value": "4334"
      },
      {
          "key": "field_3",
          "value": "1" //复选框
      },
      {
          "key": "field_2",
          "value": "下拉菜单的某一项"
      },
      {
          "key": "field_4",
          "value": "附件的下载地址" //附件多个时，以逗号分隔
      }
     ]
}

工单列表

GET /api/v1/tickets.json

查询参数

名称 必要的 类型 注释
created_start 否 string 按创建时间查询：开始时间
created_end 否 string 按创建时间查询：结束时间
updated_start 否 string 按更新时间查询：开始时间
updated_end 否 string 按更新时间查询：结束时间
created_order 否 string 按创建时间排序：asc（升序），desc（降序）
updated_order 否 string 按更新时间排序：asc（升序），desc（降序）
status_order 否 string 按工单状态排序：asc（升序），desc（降序）
page 否 number 页码，默认为 1
per_page 否 number 每页大小，默认为 100

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

调用者权限 

管理员

也可以使用下面的接口 

/*查看服务商下某个客户的工单*/
GET /api/v1/companys/{company_id}/tickets.json
/*查看服务商下某个客户的某个联系人的工单*/
GET /api/v1/users/{user_id}/tickets.json

调用示例 

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

返回值示例 

Status: 200 OK

{
	"tickets": [
		{
			"ticketId": 110,
			"subject": "产品咨询",
			...
		},
		{
			"ticketId": 111,
			"subject": "产品服务",
			...
		}
	]
}

查看工单

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

调用者权限 

  管理员

调用示例 

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

返回示例 

Status: 200 OK

{
	"ticket": {
		"ticketId": 110,
		"subject": "产品咨询",
		...
	}
}

查看多个工单

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

说明：工单id要以逗号分隔。此接口最多返回100个工单。

调用者权限 

  管理员

调用示例 

curl https://www.bangwo8.com/api/v1/tickets/show_many.json?ids=110,111,112 \
 -v -u {account}:{password}

返回值示例 

Status: 200 OK

{
  "tickets": [
    {
      "ticketId": 110,
      "subject": "产品咨询",
      ...
    },
    {
      "ticketId": 111,
      "subject": "产品服务"
      ...
    },
    ...
  ]
}

创建工单

POST /api/v1/tickets.json

调用者权限 

  管理员

请求参数

名称 类型 必须的 描述
subject string 是 工单标题
ticketReply object 是 工单描述，请参考工单回复
custUserId int否 联系人id，说明该工单是为该客户解决问题
custUser object否 联系人信息
createrId int否 创建人id
servicerUserId int否 受理客服id
servicerGroupId int否 受理客服组id
ccUserIdList string否 抄送客服id列表
ccGroupIdList string否 抄送客服组id列表
ticketSource int否 工单来源：1–远程，2–聊天，3–呼叫中心，4–留言，5–系统创建
ticketType int否 工单类型：1–问题，2–事务，3–故障，4–任务
priorityLevel int否 工单优先级：1–低，2–正常，3–高，4–紧急
ticketStatus int否 工单状态：1–新建，2–已开启，3–待回应，4–已解决，5–自动关闭，6–手动关闭
ticketTemplateId int 否 如果需要传工单来源、类型、优先级、状态或者自定义字段，则必须传该字段值
tagList int否 工单标签列表，以逗号分隔
custom_fields array否 工单自定义字段

custUser参数说明
目前支持的联系人信息有mobilephone、name、fixnumber、qq、email，如果要使用该参数，则mobilephone是必需的，其余是选填项。如果数据库里没有该联系人信息，则会自动创建。 

"custUser":{ 
	"mobilephone": 13240138438,
	"name": "张三" ,
	"fixnumber": "010-63701717" ,
	"qq": "601100987" ,
	"email": "bangwo8@126.com" ,
}

自定义字段说明
key是字段的唯一标识，可从“帮我吧后台-》工单自定义字段”查看；value是该字段的具体值。 

"custom_fields": [
     {
      "key": "field_1",
      "value": "文本框内容"
     },
     {
      "key": "field_2",
      "value": "下拉框的某选项"
     }
    ]

上传工单附件
工单附件包含两种类型：自定义字段类型的附件和工单回复里的附件。无论是哪种类型的附件，都需要先调用工单回复里的上传附件接口，调用成功后，系统会返回相应的附件token，然后将参数置位此token即可。 

/*自定义字段附件*/
"custom_fields": [
	{
            "key": "field_4", //附件自定义字段的唯一标识
            "value": "11234af5467818a7865weq,34523af5467818a7865wer" //token
        }
]

/*工单回复里的附件*/
"ticketReply": {
        "attachments": [
           "11234af5467818a7865weq", //附件1的token
           "34243rt5644334a6755sda" //附件2的token
        ]
}

调用示例 

curl https://www.bangwo8.com/api/v1/tickets.json \
  -d '{"ticket": {"subject": "产品咨询", "ticketReply": { "replyMsg":"你好，我想咨询下帮我吧产品" }}}' \
  -H "Content-Type: application/json" -v -u {account}:{password} -X POST

返回值示例 

Status: 201 Created
Location: https://www.bangwo8.com/api/v1/tickets/{id}.json

{
  "ticket": {
    "ticketId": 110,
    "subject": "产品咨询",
    ...
  }
}

更新工单

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

调用者权限 

所有客服

请求参数

名称 类型 必需的 描述
ticketReply object 是 工单描述，请参考工单回复
servicerUserId int否 受理客服id
servicerGroupId int否 受理客服组id
ccUserIdList int否 抄送客服id列表，如果是抄送的客服分组，则传客服分组id，多个id之间以逗号分隔
ticketSource int否 工单来源：1–远程，2–聊天，3–呼叫中心，4–留言，5–系统创建
ticketType int否 工单类型：1–问题，2–事务，3–故障，4–任务
priorityLevel int否 工单优先级：1–低，2–正常，3–高，4–紧急
ticketStatus int否 工单状态：1–新建，2–已开启，3–待回应，4–已解决，5–自动关闭，6–手动关闭
ticketTemplateId int 否 如果需要更新工单来源、类型、优先级、状态或者自定义字段，则必须传该字段值
tagList int否 工单标签列表，以逗号分隔
custom_fields array否 工单自定义字段

调用示例 

curl https://www.bangwo8.com/api/v1/tickets/{id}.json \
  -H "Content-Type: application/json" \
  -d '{"ticket": {"ticketStatus": "open", "ticketReply": { "replyMsg": "这里是工单回复文本内容", "replyUserId": 233434 }}}' \
  -v -u {account}:{password} -X PUT

返回值示例 

Status: 200 OK

{
  "ticket": {
     "ticketId": 123,
     "subject": "这里是工单标题",
     "ticketStatus":  "已解决",
     ...
  }
}

更新多个工单

PUT /api/v1/tickets/update_many.json
PUT /api/v1/tickets/update_many.json?ids={ids}

说明：一次最多更新100个工单

调用权限 

所有客服

调用示例
对不同的工单进行相同的处理，调用下面的接口： 

PUT /api/v1/tickets/update_many.json?ids=111,222,333
{
  "ticket": {
    "ticketStatus": "已解决"
  }
}

对不同的工单进行不同的处理，调用下面的接口： 

PUT /api/v1/tickets/update_many.json
{
  "tickets": [
    { "ticketId": 111, "ticketStatus": "已解决" },
    { "ticketId": 222, "ticketStatus": "待回应" }
  ]
}

返回值示例 

Status: 200 OK

{
  "results": [
    {
      "ticketId": 111,
      "success": false,
      "error_log": "字段值不合法"
    },
    {
      "ticketId": 222,
      "success": true,
      "error_log": ""
    }
  ]
}

搜索工单

GET /api/v1/tickets/search.json

调用权限 

所有客服

请求参数

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

query参数说明

搜索内容 返回结果
query=2444 模糊搜索，返回工单编号、工单标题或者联系人姓名包含该内容的工单
query=status:已开启，已解决 搜索
query=field_1:454 返回自定义字段唯一标识为“field_1”的内容里面包含“454”的工单
query=2444 createDT>2017-07-01返回工单编号、工单标题或者联系人姓名包含该内容的工单，并且创建时间是2017年7月1日以后的
query=status:已开启，已解决 createDT⇐2017-07-01返回工单状态为已开启或已解决的工单，并且创建时间是2017年7月1日以前的，包含2017年7月1日当天
query=status:已开启，已解决 updateDT>=2017-07-01返回工单状态为已开启或已解决的工单，并且更新时间是2017年7月1日以后的，包含2017年7月1日当天

说明：当query参数增加了时间的过滤条件时，两个条件之间要以空格分开，比如“status:已开启，已解决 updateDT>=2017-07-01”

调用示例 

curl "https://www.bangwo8.com/api/v1/tickets/search.json" \
  -G --data-urlencode "query=status:已解决 createDT>2017-07-03" \
  -v -u {account}:{password}

返回值示例 

Status: 200 OK

{
  "results": [
    {
      "subject":   "这里是工单标题",
      "createDT":  "2009-05-13 10:07:08",
      "updateDT":  "2011-07-22 11:11:12",
      "ticketId":  211,
      "url":       "https://www.bangwo8.com/api/v1/tickets/211.json"
    },
    {
      "subject":   "这里是工单标题",
      "createDT":  "2010-07-13 10:07:08",
      "updateDT":  "2011-07-13 11:11:12",
      "ticketId":  122,
      "url":       "https://www.bangwo8.com/api/v1/tickets/122.json"
    },
    ...
  ],
  "next_page": "https://www.bangwo8.com/api/v1/tickets/search.json?query=\"status:已开启\"&sort_by=createDT&sort_order=desc&page=2",
  "prev_page": null,
  "count":     1234
}

页面工具

关于我们 | 联系我们 | 意见建议 | 论 坛 | 管理后台

增值电信业务经营许可证:京B2-20192684 京ICP备05008343号

Copyright @ 2004-2020 Gnway.com All rights reserved