webhook使用说明

此文档是约束用户提供的webhook接口的入参和返回值

接口有两种使用方式:1.消息触发型 2.任务推送型
消息触发型:通过对用户消息做匹配触发,答案替换webhook里返回的ansContent
任务推送型:这个需要你对机器人管理系统的任务式对话功能有一定的了解,请求参数是我方在调用你方 接口时候给的入参,请求结果是我方需要你在接口中按格式返回的信息

webhook(消息触发型)

1.鉴权方式

公式

sign=SHA1(integrationName&appKey&timestamp)

其中:

示例

鉴权所需数据

名称
integrationName 对接名称,在系统配置的名称
api_token 221b368d7f5f597867f525971f28ff75
timestamp 1496631984

计算机签名:

sha1("对接一&221b368d7f5f597867f525971f28ff75&1496631984") ->
96d8271cd705d3f134d215e9b3c27bb73f1132ed

请求地址

请求参数

URL Parameters

Path Type Required Description
timestamp Integer true 时间戳
sign String true 签名

Request Body

Path Type Required Description
integrationName String true 对接名称
regex String true 正则表达式
questionContent String true 问题内容
extra Object false 附加参数对象
extra.weChatOpenId String false 如果为微信渠道,则为微信的openId
customerExtra Object false 客户自定义附加对象
customerExtra.customerId Integer false 客服系统的用户Id

请求结果

Path Type Description
answerContent String 答案内容

示例

$ curl 'HOST/API?timestamp=1513150103&sign=ab991af4ef65fc6061cf16c19d7d9d1bc1e12dcb' -i -X POST -H 'Content-Type: application/json' -d '{
          "integrationName" : "对接一",
          "regex" : "[abc]",
          "questionContent" : "问题内容",
          "extra" : {
            weChatOpenId : "wechatId"
          }
        }'
返回
{
  "answerContent" : 这里是答案
}

webhook(任务推送型)

请求参数

Path Type Required Description
taskNodeId Integer true 节点ID,当前任务式会话匹配停留的节点Id
sessionId Integer true 会话ID,对话记录的Id
timestamp Long true 时间戳
sign String true 签名
variables Map false 变量Map,任务树配置里搜集到的变量
customerExtra Object false 客户自定义附加对象
customerExtra.customerId Integer false 客服系统的用户Id
customerExtra.callerNumber String false 语音机器人主叫号码(此字段为语音机器人使用)
customerExtra.dialogueDesc String false 此字段使用比较特殊,是为了满足客户给机器人对话的Webhook传自定义信息的需求 首先要在客服系统里,客户自定义字段内,设置一个名字叫做c_cf_dialogueDesc的自定义字段 可以设置客户的该字段值 之后打开聊天插件,将该字段添加到路径参数里,格式如下 https://xxx.udesk.cn/im_client/?web_plugin_id=41597&c_cf_dialogueDesc=* 这样系统会自动将该参数值以参数dialogueDesc的形式当做webhook的一个请求参数传进去 特殊提醒:客服系统和路径传参都是以c_cf_dialogueDesc参数名进行传值

请求结果

Path Type Description
resCode Integer 响应码【0成功/-1失败】
resError String 非用户级别错误信息
message Message 用户消息
variables Map 变量设置,你可以修改变量表
toTaskNodeId Integer 跳转任务节点ID,动作是跳转节点有效
routeType Integer 跳转节点类型(1.直接触发 2.等待回复)
command String 动作指令

message

Path Type Required Description
msgType String true 消息类型
msgContent Object true 消息内容

msg_type

Value Description 对应msgContent
plain 纯文本 String
rich 富文本 String
selective_table 选择表格 selective_table
selective_list 选择列表 selective_list
show_product 产品展示 show_product
selective_product 选择产品 show_product
custom_card 卡片消息 custom_card

selective_table

Path Type Description
title String 标题
rowNumber Integer 行数
columnNumber Integer 列数
optionList List<Option> 选项列表

selective_list

Path Type Description
title String 标题
optionList List<Option> 选项列表

show_product

Path Type Description
title String 标题
showSize Integer 默认展示数量
turnFlag Integer 轮播标识
productList List<OptionalProduct> 商品列表

custom_card

Path Type Description
id Integer 主键
name String 名称
turnFlag Integer 是否轮播标志 0否1是 default 0 换一组的功能
showSize Integer 卡片列表显示数量 turnFlag=1有效
title String 标题,如果不为空,则显示title卡片
cardList List 卡片列表
cardList[].id Integer 卡片Id
cardList[].type Integer 卡片类型 1.富文本卡片 2.FAQ推荐列表卡片
cardList[].isHit Integer 卡片是否能点击 type=1有效 0否 1是
cardList[].hitType Integer 卡片点击效果 type=1&isHit=1有效 1超链接2回复消息
回复消息是指在聊天窗替用户提问一串文本
cardList[].hitContent String 卡片点击内容 type=1&isHit=1有效
hitType=1是链接地址 hitType=2是需要回复的消息内容
cardList[].content String 富文本具体内容 type=1有效
cardList[].suggestContent String FAQ推荐卡片的文案type=2有效
cardList[].suggestList List FAQ推荐的问题列表type=2有效
cardList[].suggestList[].id Integer 问题的标识id.type=2有效
cardList[].suggestList[].content String 问题的内容.type=2有效
cardList[].suggestList[].type Integer 问题类型type=2有效

optional_product

Path Type Description
id Integer ID
name String 商品名称
image String 商品图片
url String 商品链接
infoList List<ProductInfo> 商品信息

product_info

Path Type Description
info String 文本
boldFlag String 加粗标识
url Integer 商品链接
color String 颜色

option

Path Type Description
id String 选项ID
value String 选项值

签名

示例

## appKey:abcde
## sign:md5Hex(abcde1001001551510709)
$ curl 'https://demo/webhook' -i -X POST -H 'Content-Type: application/json' -d '{
  "taskNodeId" : 100,
  "sessionId" : 100,
  "timestamp" : 1551510709,
  "variables" : {
    "city":"北京",
    "name":"李浩"
   },
  "sign" : "9195e2a5c1d84b86dc59819f29a0e300",
}'
返回
{
  "resCode": 0,
  "message": {
    "msgType": "rich",
    "msgContent": "webhook返回的内容"
  }
}