Webhooks API文档#

快速上手指南#

使用webhooks可以让你在特定事件发生的时候即时得到通知,比如有新的工单产生的时候。当有特定的事件发生的时候, 我们会通过HTTP POST请求向你设置的webhook payload url发送数据, 格式为JSON,编码为UTF-8,User Agent为"daike robot v1.0"。 当前的webhooks API版本为v1.0。

你可以用webhooks来:

  • 当有新的工单产生的时候,通知客服去马上处理;
  • 当用户有新的回复的时候,通知客服去处理,减少用户等待时间;

例如当你的用户提交一个新工单时,待客将向你设置的webhook payload url发送如下POST请求:

{
  "event_type": "ticket_create",
  "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"
  },
  "user_properties": {
    "user_type": "paid",
    "vip_level": 7
  },
  "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"
      },
      "assigned_to": {
        "id": "B99Vb70B",
        "name": "philcoulson",
        "email": "phil@shield.gov",
        "role": "agent",
        "avatar": "https://avatars1.githubusercontent.com/u/552983"
      }
    }
  ],
  "via": "email"
}

你的API在接到此POST请求后,需提供HTTP状态码200,此时一次通知结束。

如果你没有提供此状态码,待客将在30秒、1分钟、5分钟、30分钟、2小时、12小时和24小时后再次发送请求直到成功; 若这些请求均未得到预期的返回值,待客将不再尝试。

事件类型#

待客webhooks API目前支持4种事件, 即当以下事件发生时,待客将向你发送HTTP POST请求。目前支持的事件分别是:

事件名称 描述
工单创建事件 当有新的工单发起的时候
工单指派事件 当工单被指派的时候
消息事件 当工单有新的回复的时候
工单关闭事件 当工单被关闭的时候

POST的具体内容为工单详情API内容加上一个新的event_type字段来表示新发生的事件类型, 各个字段的内容请参看获得工单详情API中的详细说明。

工单创建事件#

当有用户创建工单时,webhooks发送的请求中,event_type字段的值为ticket_create, events字段中会新增一个工单创建事件, 事件的各个字段的说明请参考工单创建事件,具体格式如下:

{
  "event_type": "ticket_create",
  ...,
  "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"
      },
      "assigned_to": {
        "id": "B99Vb70B",
        "name": "philcoulson",
        "email": "phil@shield.gov",
        "role": "agent",
        "avatar": "https://avatars1.githubusercontent.com/u/552983"
      }
    }
  ],
  ...
}

工单指派事件#

当在后台中,将工单指派给某个工作人员时,发送的请求中event_type字段的值为ticket_assignevents字段中会新增一个工单指派事件,事件的各个字段的说明请参考工单指派事件,具体格式如下:

{
  "event_type": "ticket_assign",
  ...,
  "events": [
    ...,
    {
      "type": "ticket_assign",
      "timestamp": "1462480013.164",
      "ticket_id": "VwKXD5P8",
      "reason": "Check this order please.",
      "staff": {
        "id": "5EV1xr7r",
        "name": "Smith",
        "email": "smith@getqujing.com",
        "role": "admin",
        "avatar": "https://avatars1.githubusercontent.com/u/552984"
      },
      "was_assigned_to": {
        "id": "B99Vb70B",
        "name": "philcoulson",
        "email": "phil@getqujing.com",
        "role": "agent",
        "avatar": "https://avatars1.githubusercontent.com/u/552983"
      },
      "assigned_to": {
        "id": "5EV1xr7r",
        "name": "Smith",
        "email": "smith@getqujing.com",
        "role": "admin",
        "avatar": "https://avatars1.githubusercontent.com/u/552984"
      }

    }
  ],
  ...
}

消息事件#

当工作人员或用户对某个工单使用文本消息回复时,发送的请求中event_type字段的值为messageevents字段中会新增一个消息事件,事件的各个字段的说明请参考消息事件,具体格式如下:

{
  "event_type": "message",
  ...,
  "events": [
    ...,
    {
      "type": "message",
      "timestamp": "1462480013.164",
      "ticket_id": "VwKXD5P8",
      "via": "api",
      "text": "Ping...",
      "user": {
        "id": "x73WqBnD",
        "name": "John",
        "email": "John@gmail.com"
      },
    }
  ],
  ...
}

使用附件回复也是一个回复,在这个情况下,event_type字段的值为attachment, events字段中会新增一个附件事件, 事件的各个字段的说明请参考附件事件,具体格式如下:

{
  "event_type": "attachment",
  ...,
  "events": [
    ...,
    {
      "type": "attachment",
      "timestamp": "1462480013.164",
      "ticket_id": "VwKXD5P8",
      "via": "api",
      "user": {
        "id": "x73WqBnD",
        "name": "John",
        "email": "John@gmail.com"
      },
      "attachment_id": "xWX20lXj",
      "content_type": "image/png",
      "filename": "example.png",
      "size": "233",
      "url": "https://...",
      "thumb_url": "https://...",
      "medium_thumb_url": "https://...",
    }
  ],
  ...
}

工单关闭事件#

当在后台中,工作人员关闭某个工单时,此时发送的请求中的event_type字段的值为ticket_close, events字段中会新增一个工单关闭事件(对于使用SDK发起的工单,由于用户可以重新打开工单,故可能有多次的工单关闭事件), 事件的各个字段的说明请参考工单关闭事件,具体格式如下:

{
  "event_type": "ticket_close",
  ...,
  "events": [
    ...,
    {
      "type": "ticket_close",
      "timestamp": "1462480013.164",
      "ticket_id": "VwKXD5P8",
      "status": "closed",
      "staff": {
        "id": "B99Vb70B",
        "name": "philcoulson",
        "email": "phil@shield.gov",
        "role": "agent",
        "avatar": "https://avatars1.githubusercontent.com/u/552983"
      }
    }
  ],
  ...
}

Webhooks安全#

为了保证webhooks的安全,待客建议对于webhook payload url使用HTTPS协议。另外,建议校验signature保证结果没有被篡改。 待客向你设置中的webhook payload url发起请求的时候,请求的头部中带有X-Daike-Webhook-Signature, 校验方式为: 其值应当等于"sha1="加上对于请求实体使用HMAC计算得到的结果,用ruby实现的伪代码为:

"sha1=#{OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha1'), team.secret, request_body)}"