Web API文档#

API介绍#

协议概述#

开发者可以通过调用待客的API将待客的服务集成到你的应用,不管是网页,微信或者是其他应用场景。 API遵循REST规范。 在API中,请求和回复的Content-Type都应该是application/json(除了特殊说明)。

协议入口#

当前的API版本为v1,web API的地址为https://v1.daikeapi.com

验证协议#

客户端发出的HTTP请求中,至少要携带以下的首部,分别是

HTTP首部
Authorization Token ${token}
X-Daike-App-Id 应用的appid

错误处理#

在API的返回中,由HTTP状态码表示是否执行成功,其中2xx表示成功,4xx表示失败,常见的HTTP状态码请查看常见的HTTP状态码一节。 在请求失败时,服务器的返回是一个形如以下的JSON:

{
  "reason": "invalid_request",
  "errors": {
  }
}

其中reason是一个机器可读的字符串,表示某个具体错误,errors则是一个错误对象,里面有各个API定义的实际错误内容,通用的错误有:

错误 描述
invalid_format 请求的body不是JSON
forbidden 不允许访问,例如SDK不允许访问web的内容
unauthorized 未通过验证
validation_failed 提交的数据没有通过验证,可以在errors中取得键值对来得到具体的出错的field与对应的错误,如{"name": "no content provided"}
not_found 所指的资源不存在
invalid_appid 未提供首部X-Daike-App-Id或提供的appid不合法

常见的HTTP状态码#

HTTP状态码 描述
200 OK表示请求成功,比如说成功获得了一张工单的详情
201 Created表示资源创建成功,比如说成功创建了一张工单
400 Bad Request通常情况是请求参数不合法,比如说某个参数不符合API参数要求
401 Unauthorized未通过验证,比如说HTTP首部中的token不对
403 Forbidden不允许该请求,比如说SDK是不允许访问只有web才能看到的内容
404 Not Found没有找到所请求的资源,比如你请求某张不存在工单的详情
500 Internal Server Error通常情况是我们服务器后端有问题

API列表及详细说明#

目前待客对外提供的API有以下几种,详细说明如下:

发起工单API#

URI#

POST /api/tickets

描述#

创建工单。由于要上传附件,所以这个接口不使用JSON作为Content-Type,而是传统的multipart/form-data

参数#

"user_id": "d05dfef32d04aeb48c1eeadb",
"name": "John Doe",
"email": "johndoe@gmail.com",
"description": "It's unreasonably ugly to use",
"attachments": [多个附件],
"tags": ["tag1", "tag2"]
"properties": '{"name": "John"}'
字段名 描述
user_id 用户id,可选,待客使用该字段来标识用户
name 用户姓名,可以为空
email 用户邮箱,可以为空
description 用户填入的问题描述,必须
attachments 用户上传的附件, 可选
tags 工单标签,可选
properties 自定义的属性键值对,可选。由于Content-Typemultipart/form-data,其格式应为JSON格式的字符串,比如'{"vip_level": 10, "paid": "yes"}'。且不支持值为嵌套的字段,比如'{"nested_key_one": {"nested_value": "yes"}, "nested_key_two": [1, 2, 3]}'

示例#

curl -X POST \
  -H "X-Daike-App-Id: YOUR_APPID" \
  -H "Authorization: Token YOUR_TOKEN" \
  -F "name=John Doe" \
  -F "email=johndoe@gmail.com" \
  -F "description=I don't know what to say" \
  -F 'tags[]=tag1' \
  -F 'tags[]=tag2' \
  -F 'properties={"vip_level": 10}' \
  https://v1.daikeapi.com/api/tickets

返回#

工单对象

邮件工单API#

URI#

POST /api/tickets/emails

描述#

创建工单,但是消息的收发都通过邮件。Content-Type同为multipart/form-data

参数#

"user_id": "d05dfef32d04aeb48c1eeadb",
"name": "John Doe",
"email": "johndoe@gmail.com",
"description": "It's unreasonably ugly to use",
"attachments": [多个附件],
"tags": ["tag1", "tag2"],
"properties": '{"name": "John"}',
"content_type": "text/plain"
字段名 描述
user_id 用户id,可选,待客使用该字段来标识用户
name 用户姓名,可以为空
email 用户邮箱,必须
description 用户填入的问题描述,必须
attachments 用户上传的附件, 可选
tags 工单标签,可选
properties 自定义的属性键值对,可选。由于Content-Typemultipart/form-data,其格式应为JSON格式的字符串,比如'{"vip_level": 10, "paid": "yes"}'。且不支持值为嵌套的字段,比如'{"nested_key_one": {"nested_value": "yes"}, "nested_key_two": [1, 2, 3]}'
content_type 表示传入的问题描述的文本类型,值为text/plain或者text/html,默认值为text/html,可选

示例#

curl -X POST \
  -H "X-Daike-App-Id: YOUR_APPID" \
  -H "Authorization: Token YOUR_TOKEN" \
  -F "name=John Doe" \
  -F "email=johndoe@gmail.com" \
  -F "description=I don't know what to say" \
  -F 'tags[]=tag1' \
  -F 'tags[]=tag2' \
  -F 'properties={"vip_level": 10}' \
  https://v1.daikeapi.com/api/tickets/emails

返回#

工单对象

获得工单详情API#

URI#

GET /api/tickets/:id

描述#

获取某条工单详情

示例#

curl -X GET \
  -H "X-Daike-App-Id: YOUR_APPID" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  https://v1.daikeapi.com/api/tickets/TIKCET_ID

返回#

工单对象

{
  "id": "K9gGXMGD",
  "status": "open",
  "description": "I can't purchse anything right now",
  "created_at": "2016-06-17T08:34:32Z",
  "messages_count": 0,
  "tag": ["bug", "purchse"],
  "user": {
    "id": "x73WqBnD",
    "name": "John",
    "email": "John@gmail.com"
  },
  "assignee": {
    "id": "B99Vb70B",
    "name": "philcoulson",
    "email": "phil@shield.gov",
    "role": "agent",
    "avatar": "https://avatars1.githubusercontent.com/u/552983"
  },
  "user_properties": {...},
  "device_properties": {...},
  "events": [
    {
      "type": "ticket_create",
      "timestamp": "1462480013.164",
      "ticket_id": "VwKXD5P8",
      "description": "I can't play the game now.",
      "user": {
        "id": "x73WqBnD",
        "name": "John",
        "email": "John@gmail.com"
      },
      "assignee": {
        "id": "B99Vb70B",
        "name": "philcoulson",
        "email": "phil@shield.gov",
        "role": "agent",
        "avatar": "https://avatars1.githubusercontent.com/u/552983"
      }
    }
    ...
    {
      "type": "ticket_close",
      "ticket_id": "VwKXD5P8",
      "timestamp": "1462480013.164",
      "user": {
        "id": "x73WqBnD",
        "name": "John",
        "email": "John@gmail.com"
      },
      "staff": {
        "id": "B99Vb70B",
        "name": "philcoulson",
        "email": "phil@shield.gov",
        "role": "agent",
        "avatar": "https://avatars1.githubusercontent.com/u/552983"
      }
    }
  ],
  "via": "email"
}
字段名 描述
id 工单id
status 工单状态,目前有openclosed
description 工单描述信息
created_at 工单创建时间,格式为iso8601
message_count 工单的对话数量
tags 工单的标签
user 创建该工单的用户
assignee 负责该工单的客服
user_properties 工单提交时的用户信息,键值对
device_properties 工单提交时的设备信息,键值对
events 工单事件。具体参考事件列表及详细说明部分

获得工单列表API#

URI#

GET /api/tickets

描述#

获得工单列表

参数#

示例#

curl -X GET \
  -H "X-Daike-App-Id: YOUR_APPID" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  https://v1.daikeapi.com/api/tickets

返回#

{
  "tickets": [
    {
      "id": "K9gGXMGD",
      "status": "open",
      "description": "I can't purchse anything right now",
      "created_at": "2016-06-17T08:34:32Z",
      "messages_count": 0,
      "tags": ["bug", "purchse"],
      "user": {
        "id": "x73WqBnD",
        "name": "John",
        "email": "John@gmail.com"
      },
      "assigned_to": {
        "id": "B99Vb70B",
        "name": "philcoulson",
        "email": "phil@shield.gov",
        "role": "agent",
        "avatar": "https://avatars1.githubusercontent.com/u/552983"
      },
      "via": "email"
    },
    ...
  ]
}
字段名 描述
tickets 工单对象的列表

工单消息API#

URI#

POST /api/tickets/:id/messages

描述#

发送信息,在工单中进行对话。目前对邮件工单和表单邮件工单不支持该接口

参数#

{
  "send_from": "user",
  "text": "Hello, world."
}
字段名 描述
send_from "staff"或者"user", 表示信息的发送者
text 消息内容

示例#

curl -X POST \
  -H "X-Daike-App-Id: YOUR_APPID" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"send_from": "user", "text": "nice to meet you"}' \
  https://v1.daikeapi.com/api/tickets/TICKET_ID/messages

返回#

工单对象,但是在events字段中新增一个消息事件,格式如下,事件各个字段含义见消息事件

{
  ...,
  "events": [
    ...
    {
      "type": "message",
      "timestamp": "1562480013.164",
      "ticket_id": "VwKXD5P8",
      "staff": {
        "id": "B99Vb70B",
        "name": "philcoulson",
        "email": "phil@shield.gov",
        "role": "agent",
        "avatar": "https://avatars1.githubusercontent.com/u/552983"
      },
      "text": "Hello, world."
    }
  ],
  "via": "email"
}

上传工单附件API#

URI#

POST /api/tickets/:id/attachments

描述#

发送附件。由于要上传附件,所以这个接口不使用JSON作为Content-Type,而是传统的multipart/form-data。目前对邮件和表单邮件不支持该接口

参数#

"file": 文件对象
"send_from": 发送者,"staff"或者"user"

示例#

curl -X POST \
  -H "X-Daike-App-Id: YOUR_APPID" \
  -H "Authorization: Token YOUR_TOKEN" \
  -F "send_from=user" \
  -F "file=@/PATH/TO/IMG"
  https://v1.daikeapi.com/api/tickets/TICKET_ID/attachments

返回#

工单对象,但是在events字段中新增一个附件事件,格式如下,事件各个字段含义见附件事件

{
  ...
  "events": [
    ...,
    {
      "type": "attachment",
      "timestamp": "1462480013.164",
      "attachment_id": "JPoyykkN",
      "ticket_id": "VwKXD5P8",
      "user_id": "MPrx7MNK",
      "staff_id": "4NkZjApm",
      "content_type": "image/jpg",
      "filename": "3222fe17-6302-4e94-acb3-d1debe510bc1.jpg",
      "size": 153984,
      "url": "https://cdn.daikeapp.com/uploads/attachment/file/17/3222fe17-6302-4e94-acb3-d1debe510bc1.jpg",
      "thumb_url": "https://cdn.daikeapp.com/uploads/attachment/file/17/thumb_3222fe17-6302-4e94-acb3-d1debe510bc1.jpg",
      "mediumthumb_url": "https://cdn.daikeapp.com/uploads/attachment/file/17/medium_thumb_3222fe17-6302-4e94-acb3-d1debe510bc1.jpg"
    }
  ],
  ...
}

事件列表及详细说明#

目前待客工单事件有以下几种,详细说明如下:

工单创建事件#

工单新增时产生,格式如下:

{
  "type": "ticket_create",
  "timestamp": "1462480013.164",
  "ticket_id": "VwKXD5P8",
  "description": "I can't play the game now.",
  "user": {
    "id": "x73WqBnD",
    "name": "John",
    "email": "John@gmail.com"
  },
  "assigned_to": {
    "id": "B99Vb70B",
    "name": "philcoulson",
    "email": "phil@shield.gov",
    "role": "agent",
    "avatar": "https://avatars1.githubusercontent.com/u/552983"
  }
}
字段名 描述
type 事件类型
timestamp 时间戳
ticket_id 工单的id
description 工单的描述
user 新增工单用户信息
user.id 用户id
user.name 用户名称
user.email 用户邮箱
assigned_to 工单指派给的员工信息
assigned_to.id 员工id
assigned_to.name 员工姓名
assigned_to.email 员工邮箱
assigned_to.avatar 员工头像

工单指派事件#

指派工单时产生,格式如下:

{
  "type": "ticket_assign",
  "timestamp": "1462480013.164",
  "ticket_id": "VwKXD5P8",
  "staff": {
    "id": "B99Vb70B",
    "name": "philcoulson",
    "email": "phil@shield.gov",
    "role": "agent",
    "avatar": "https://avatars1.githubusercontent.com/u/552983"
  },
  "was_assigned_to": {
    "id": "AodI770B",
    "name": "John",
    "email": "John@shield.gov",
    "role": "agent",
    "avatar": "https://avatars1.githubusercontent.com/u/552911"
  },
  "assigned_to": {
    "id": "B99Vb70B",
    "name": "philcoulson",
    "email": "phil@shield.gov",
    "role": "agent",
    "avatar": "https://avatars1.githubusercontent.com/u/552983"
  },
  "reason": "Please help check this order"
}
字段名 描述
type 事件类型
timestamp 时间戳
ticket_id 工单的id
staff 指派工单的员工
staff.id 员工id
staff.name 员工姓名
staff.email 员工邮箱
staff.avatar 员工头像
was_assigned_to 之前处理工单的员工
was_assigned_to.id 员工id
was_assigned_to.name 员工姓名
was_assigned_to.email 员工邮箱
was_assigned_to.avatar 员工头像
assigned_to 现在处理工单的员工
assigned_to.id 员工id
assigned_to.name 员工姓名
assigned_to.email 员工邮箱
assigned_to.avatar 员工头像
reason 指派时捎带的留言

消息事件#

消息事件是双方主要通信的事件,格式如下:

{
  "type": "message",
  "timestamp": "1462480013.164",
  "ticket_id": "VwKXD5P8",
  "user": {
    "id": "MPrx7MNK",
    "name": "John",
    "email": "John@gmail.com"
  },
  "staff": {
    "id": "4NkZjApm",
    "name": "philcoulson",
    "email": "phil@shield.gov",
    "role": "agent",
    "avatar": "https://avatars1.githubusercontent.com/u/552983"
  },
  "text": "this is a message from santa, hohoho"
}
字段名 描述
subtype 可选,表示特殊的消息
timestamp 时间戳
ticket_id 工单的id
user \ staff 发送方,根据发送者不同,会使用其中一个
user.id 用户id
user.name 用户名称
user.email 用户邮箱
staff.id 员工id
staff.email 员工邮箱
staff.role 员工角色,可以是agent(客服)或者amdin(管理者)
staff.avatar 员工头像
text 消息正文

subtype的取值范围:

subtype值 描述
auto_reply_message 该消息是一条自动回复消息
faq_message 该消息是一条faq

附件事件#

特殊的消息,用于收到包含附件的信息,格式如下:

{
  "type": "attachment",
  "timestamp": "1462480013.164",
  "attachment_id": "JPoyykkN",
  "ticket_id": "VwKXD5P8",
  "user": {
    "id": "x73WqBnD",
    "name": "John",
    "email": "John@gmail.com"
  },
  "staff": {
    "id": "B99Vb70B",
    "name": "philcoulson",
    "email": "phil@shield.gov",
    "role": "agent",
    "avatar": "https://avatars1.githubusercontent.com/u/552983"
  },
  "content_type": "image/jpg",
  "filename": "3222fe17-6302-4e94-acb3-d1debe510bc1.jpg",
  "size": 153984,
  "url": "https://cdn.daikeapp.com/uploads/attachment/file/17/3222fe17-6302-4e94-acb3-d1debe510bc1.jpg",
  "thumb_url": "https://cdn.daikeapp.com/uploads/attachment/file/17/thumb_3222fe17-6302-4e94-acb3-d1debe510bc1.jpg",
  "mediumthumb_url": "https://cdn.daikeapp.com/uploads/attachment/file/17/medium_thumb_3222fe17-6302-4e94-acb3-d1debe510bc1.jpg"
}
字段名 描述
type 事件类型
timestamp 时间戳
attachment_id 附件id
ticket_id 工单的id
user \ staff 发送方,根据发送者不同,会使用其中一个
user.id 用户id
user.name 用户名称
user.email 用户邮箱
staff.id 员工id
staff.name 员工姓名
staff.email 员工邮箱
staff.avatar 员工头像
content_type 附件的MIME type
filename 附件文件名
size 附件大小
url 附件的url
thumb_url 附件缩略图的url,只有在上传图片时才出现
medium_thumb_url 附件中等缩略图的url,只有在上传图片时才出现

工单关闭事件#

关闭工单时产生,格式如下:

{
  "type": "ticket_close",
  "timestamp": "1476331555.896",
  "ticket_id": "Vvk9rNOR",
  "staff": {
    "id": "B99Vb70B",
    "name": "philcoulson",
    "email": "phil@shield.gov",
    "role": "agent",
    "avatar": "https://avatars1.githubusercontent.com/u/552983"
  },
  "status": "closed"
}
字段名 描述
type 事件类型
timestamp 时间戳
ticket_id 工单的id
staff 关闭工单的员工
staff.id 员工id
staff.name 员工姓名
staff.email 员工邮箱
staff.avatar 员工头像
status 工单状态