七鱼开发文档中心
总览服务端 APIWebiOSAndroid鸿蒙Uniapp微信小程序插件三方接入
在线机器人对话接入与动态能力

一触即达

一触即达动态接口的鉴权、请求参数、响应结构、模板示例、Velocity 和移动 SDK 接入说明。

一触即达

本文档为一触即达接入文档，企业根据不同业务模块，使用一触即达功能需要实现对应模块的http查询接口。 根据企业是否允许匿名访客查询，调用查询接口方式分为匿名访客查询和有名访客查询，匿名访客是指企业未做过CRM信息对接的访客，匿名访客查询是允许所有连接到机器人客服的访客使用该查询接口，有名访客查询是只允许做过CRM信息对接的访客才可使用该查询。但查询某些信息时（如查订单等需要用户唯一标识的查询）必须要企业提供访客唯一标识，即企业需通过CRM信息对接提供给七鱼。

对接方式

说明：所有接口均需符合七鱼对企业接口的请求格式规范和返回格式规范，其规范见下文。 目前七鱼调用第三方接口时会加上的鉴权方式有两种，一是token校验（复用CRM信息对接里获取token的接口，若能获取到token则使用该token，获取不到token则不使用，此种需企业提供appId,appSecret和获取token的接口），另一种是checkSum校验，需企业提供appId和appSecret,生成checkSum方式见下文。企业可依据不同模块情况采用任意校验方式，或不使用身份校验。

​调用说明​

  1. 获取token接口的请求方式同CRM对接文档里相同；
  2. 一触即达的所有接口请求均为POST请求；
  3. 一触即达的所有接口请求的Content-Type类型均为：application/x-www-form-urlencoded;charset=utf-8。

接口请求地址

POST [https://qiyeserver/](https://qiyeserver/)...  HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

​响应参数

返回字段定义：

参数是否必填参数说明
code是请求的返回码
desc否描述信息
result是接口调用结果
  1. 所有一触即达企业接口的返回类型为JSON，同时进行UTF-8编码；
  2. 接口的返回值在result字段里，可以是任何对象，只有code=200时才认为调用成功，并使用result字段里的内容做后续操作。

示例

返回示例

{
  "code": 200,
  "desc": "success",
  "result": {
    "id": "123456",
    "name": "hello world",
    "address": "浙江省杭州市滨江区长河街道网商路599号网易大厦"
  }
}

​接口调用流程

  1. 若接口不需请求校验并对所有人开放，则接口只需符合上文所列的请求和返回规范即可。
  2. 分配appId和appSecret，企业需在页面：接入设置->信息对接->CRM信息对接处填写给七鱼分配的appId和appSecret用于获取token和生成checkSum校验；
  3. 若企业设置了获取token接口，并且七鱼成功获取到token后，会在七鱼调用企业一触即达接口时将token作为参数带上；
  4. 七鱼在调用企业接口时，将appSecret，time，nonce三个参数使用sha1哈希算法生成checkSum校验和（同消息接口checksum校验和示例代码），其中time为精确到秒的时间戳，nonce为一串随机生成的字符串,参数放在Http Request Header中传输；
  5. POST请求调用第三方接口，七鱼会带上的请求参数有：userId（String字符串类型），plgCode（String字符串类型），params（Map键值对类型，包含请求所需参数，需要企业在一触即达查询节点里进行设置），请求参数放在请求体里。

​参数说明

参数是否必填参数说明
appId是企业分配给七鱼的appId
nonce是随机字符串（最大长度128个字符）
time是当前UTC时间戳，精确到秒数
checkSum是SHA1(appSecret + nonce + time),将三个参数按appSecret、nonce、 time顺序拼接成的字符串计算SHA1哈希值，并转化成16进制的小写字符串作为checkSum
userId是开发者的应用里的用户ID，通过CRM接入同步给七鱼
plgCode是七鱼要调用的对应模块名称
params是调用第三方接口的参数列表，企业在一触即达的查询节点里进行配置
token否获取到的企业token

对接示例

模板id说明SDK支持版本
01文本不限
02文本+按钮列表不限
drawer_list抽屉列表>=5.1.0
bubble_list气泡列表>=5.1.0
bubble_node_list气泡节点列表>=5.1.0
horizontal_sliding_list横滑卡片>=5.1.0

注：其他端不受版本限制

示例 1：文本

在一触即达的流程中，根据企业在节点中设置的提取变量，结合企业接口地址，获取文本消息并填充到模板中，返回示例为：

{
  "code": 200,
  "desc": "success",
  "result": {
    "data": {
      "item_list": [
        {
          "item_type": 0,
          "label": "七鱼客服bot对接"
        },
        {
          "item_type": 1,
          "label": "<a href="[http://qiyukf.netease.com/](http://qiyukf.netease.com/)">七鱼客服</a>"
        }
      ]
    }
  }
}
​字段说明
参数类型必传说明
item_typeInt是文本类型，0-普通文本，1-富文本
labelString是文本内容
​xml模板填充样式
<template id="01">
    #if(${data.item_list} && ${data.item_list.size()} > 0)
        #foreach($item in $!{data.item_list})
            <LinearLayout>
               #if($!{item.item_type} == 0)
                   <text name="label">$!{item.label}</text>
               #else
                   <richText name="label">$!{item.label}</richText>
               #end
            </LinearLayout>
        #end
    #end
</template>

示例 2：文本+按钮列表

本模板为文本模板升级版，支持文本+按钮列表的样式。在一触即达的流程中，根据企业在节点中设置的提取变量，结合企业接口地址，获取文本消息并填充到模板中，返回示例为：

{
  "code": 200,
  "desc": "success",
  "result": {
    "data": {
      "introducer": "引导语",
      "item_list": [
        {
          "item_type": "0",
          "label": "按钮1",
          "params": "orderNo=0"
        },
        {
          "item_type": "1",
          "label": "按钮2",
          "target": "[http://qiyukf.netease.com](http://qiyukf.netease.com)",
          "params": "orderNo=0"
        }
      ]
    }
  }
}
​字段说明
参数类型必传说明
introducerString否引导语文案
item_listArray是按钮列表
​按钮字段说明
参数类型必传说明
item_typeInt是按钮类型，0-跳转至下一个节点，1-跳转至外部链接
labelString是按钮文案
paramsString否点击item跳转时携带的参数
targetString否跳转至下一个节点时可不传target，跳转至外部链接时需配置链接地址
​xml模板填充样式
<template id="02">
    <LinearLayout>
        <text name="label">$!{data.introducer}</text>
    </LinearLayout>

    #if(${data.item_list} && ${data.item_list.size()} > 0)
        #foreach(${item} in $!{data.item_list})
            #if($!{item.item_type} == 0)
                <LinearLayout>
                    <link type="block" style="button" target="${xml_nfid_block_1}" params="$!{item.params}">
                        <text name="label">$!{item.label}</text>
                    </link>
                </LinearLayout>
            #else
                <LinearLayout>
                    <link type="url" style="button" target="$!{item.target}" params="$!{item.params}">
                        <text name="label">$!{item.label}</text>
                    </link>
                </LinearLayout>
            #end
        #end
    #end
</template>

示例 3：抽屉列表

抽屉列表可以用于展示订单列表或商品列表，支持展示图文内容，也支持仅展示文字内容，样式如图：

如果需要返回抽屉列表内容，企业需要在一触即达查询节点内配置接口，并加入固定入参tabId,currentPage（代表当前要请求第几页），pageSize（代表每页的大小是多少）。拉取抽屉列表时，七鱼调用企业服务器，例如：tabId=1,currentPage=1,pageSize=5，代表拉取第1个分组的第1页共5条数据（注意：若params包含的参数为空，默认拉取第1个分组的第1页共5条数据，即相当于tabId=1,currentPage=1,pageSize=5）。企业可以自定义pageSize，默认值为5，最大不超过10。tabId和currentPage可以根据访客的点选动态赋值。在一触即达查询节点中的配置如下：

返回示例

result返回值为企业订单列表的JSON数组

{
  "code": 200,
  "desc": "success",
  "result": {
    "data": {
      "tab_id": 1,
      "current_page": 1,
      "page_size": 5,
      "introducer": "请选择您想咨询的订单",
      "banner": "选择咨询的订单",
      "empty_list_hint": "无数据返回提示文案aaa",
      "tab1":{
        "name": "分组1",
        "item_list": [
          {
            "item_type": "1",
            "img": "[https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg](https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg)",
            "title": "考拉海购",
            "sub_title": "卖家已发货"
          },
          {
            "item_type": "0",
            "img": "[https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg](https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg)",
            "title": "1ZARA 女装 加大码飞行员夹克777",
            "sub_title": "1ZARA 女装 加大码飞行员夹克",
            "attr_1": "100",
            "attr_2": "100",
            "attr_3": "100",
            "target": "[http://www.baidu.com](http://www.baidu.com)",
            "params": "orderNo=0"

          },
          {
            "item_type": "0",
            "img": "[https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg](https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg)",
            "title": "1ZARA 女装 加大码飞行员夹克888",
            "sub_title": "1ZARA 女装 加大码飞行员夹克",
            "attr_1": "100",
            "attr_2": "100",
            "attr_3": "100",
            "target": "[http://www.baidu.com](http://www.baidu.com)",
            "params": "orderNo=0"

          },
          {
            "item_type": "1",
            "img": "[https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg](https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg)",
            "title": "网易严选",
            "sub_title": "卖家已发货"
          },
          {
            "item_type": "0",
            "img": "[https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg](https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg)",
            "title": "1ZARA 女装 加大码飞行员夹克999",
            "sub_title": "1ZARA 女装 加大码飞行员夹克",
            "attr_1": "100",
            "attr_2": "100",
            "attr_3": "100",
            "target": "[http://www.baidu.com](http://www.baidu.com)",
            "params": "orderNo=0"

          },
          {
            "item_type": "0",
            "img": "[https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg](https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg)",
            "title": "1ZARA 女装 加大码飞行员夹克000",
            "sub_title": "1ZARA 女装 加大码飞行员夹克",
            "attr_1": "100",
            "attr_2": "100",
            "attr_3": "100",
            "target": "[http://www.baidu.com](http://www.baidu.com)",
            "params": "orderNo=0"
          }
        ]
      },
      "tab2":{
        "name": "分组2",
        "item_list": []
      },
      "tab3":{
        "name": "分组3",
        "item_list": []
      },
      "tab4":{
        "name": "分组4",
        "item_list": []
      }
    }
  }
}

​

  • 字段说明

参数类型必传说明
tab_idInt是当前列表分组id，从params中获取，若params为空，默认为1
current_pageInt是当前页，从params中获取，若params为空，默认为1
page_sizeInt是每页数据条数，从params中获取，若params为空，默认为5，最多不超过10条
introducerString是引导语，不可为空值
bannerString否提示语
empty_list_hintString是无数据返回提示文案，不可为空值
tab1Object是列表分组1，对应分组id为1
tab2Object否列表分组2，对应分组id为2
tab3Object否列表分组3，对应分组id为3
tab4Object否列表分组4，对应分组id为4

列表分组tab格式说明：

参数类型必传说明
nameString否列表分组名称，如果不传则不展示该行内容
item_listArray是列表分组中item分组数据和item详细数据

item分组数据(item_type=1)格式说明:

参数类型必须说明
item_typeString是值固定为1
imgString否缩略图地址
titleString否标题，可以为空
sub_titleString否副标题

item详细数据(item_type=0)格式说明:

参数类型必须说明
item_typeString是值固定为0
imgString否缩略图地址
titleString否标题
sub_titleString否副标题
attr_1String否属性1
attr_2String否属性2
attr_3String否属性3
paramsString否点击item跳转时携带的参数
targetString否点击item的跳转目标地址或目标节点，若仅展示列表内容可以为空

注意事项：

<1> 为了降低企业对接难度和简化分页处理，item分组与item采用混排平铺的方式实现分组效果，item分组被当做一个特殊的item，两者的区别是item_type不同

<2> 抽屉列表要求至少包含一个列表分组，即tab1。当包含多个分组时，每次返回结果只需包含当前请求分组的item_list字段，但是需要填充其他分组的name字段。例如存在3个列表分组的情况下，在请求分组1的数据时，除了要填充tab1.name，tab1.item_list外，还需要填充tab2.name，tab3.name。

​

  • xml模板填充样式
<template id="drawer_list">
    <LinearLayout>
        <text name="label">$!{data.introducer}</text>
        <text name="empty_list_hint">$!{data.empty_list_hint}</text>
        <text name="tab_id">$!{data.tab_id}</text>
        <text name="title">$!{data.banner}</text>
    </LinearLayout>

    <group>
        <tab>
            <text name="tab_name">$!{data.tab1.name}</text>
        </tab>
        #if(1 == ${data.tab_id} && ${data.tab1.item_list} && ${data.tab1.item_list.size()} > 0)
            #foreach(${item} in $!{data.tab1.item_list})
                <LinearLayout>
                    <text name="p_item_type">$!{item.item_type}</text>
                    <link type="block" style="button" target="${xml_nfid_block_1}" params="$!{item.params}">
                        <image name="p_img" url="$!{item.img}"/>
                        <text name="p_title">$!{item.title}</text>
                        <text name="p_sub_title">$!{item.sub_title}</text>
                        <text name="p_attr_1">$!{item.attr_1}</text>
                        <text name="p_attr_2">$!{item.attr_2}</text>
                        <text name="p_attr_3">$!{item.attr_3}</text>
                    </link>
                </LinearLayout>
            #end
        #end

        #if(1 == ${data.tab_id})
            #set($page_1 = ${data.current_page} + 1)
        #else
            #set($page_1 = 1)
        #end

        <action>
            <link type="block" style="button" target="${xml_nfid_block_self}" params="tabId=1&currentPage=$!{page_1}&pageSize=5" >
                <text name="label">查看更多</text>
            </link>
        </action>
    </group>

    <group>
        <tab>
            <text name="tab_name">$!{data.tab2.name}</text>
        </tab>
        #if(2 == ${data.tab_id} && ${data.tab2.item_list} && ${data.tab2.item_list.size()} > 0)
            #foreach(${item} in $!{data.tab2.item_list})
                <LinearLayout>
                    <text name="p_item_type">$!{item.item_type}</text>
                    <link type="block" style="button" target="${xml_nfid_block_2}" params="$!{item.params}">
                        <image name="p_img" url="$!{item.img}"/>
                        <text name="p_title">$!{item.title}</text>
                        <text name="p_sub_title">$!{item.sub_title}</text>
                        <text name="p_attr_1">$!{item.attr_1}</text>
                        <text name="p_attr_2">$!{item.attr_2}</text>
                        <text name="p_attr_3">$!{item.attr_3}</text>
                    </link>
                </LinearLayout>
            #end
        #end

        #if(2 == ${data.tab_id})
            #set($page_2 = ${data.current_page} + 1)
        #else
            #set($page_2 = 1)
        #end

        <action>
            <link type="block" style="button" target="${xml_nfid_block_self}" params="tabId=2&currentPage=$!{page_2}&pageSize=5" >
                <text name="label">查看更多</text>
            </link>
        </action>
    </group>

    <group>
        <tab>
            <text name="tab_name">$!{data.tab3.name}</text>
        </tab>
        #if(3 == ${data.tab_id} && ${data.tab3.item_list} && ${data.tab3.item_list.size()} > 0)
            #foreach(${item} in $!{data.tab3.item_list})
                <LinearLayout>
                    <text name="p_item_type">$!{item.item_type}</text>
                    <link type="display" style="button" >
                    <image name="p_img" url="$!{item.img}"/>
                    <text name="p_title">$!{item.title}</text>
                    <text name="p_sub_title">$!{item.sub_title}</text>
                    <text name="p_attr_1">$!{item.attr_1}</text>
                    <text name="p_attr_2">$!{item.attr_2}</text>
                    <text name="p_attr_3">$!{item.attr_3}</text>
                    </link>
                </LinearLayout>
            #end
        #end

        #if(3 == ${data.tab_id})
            #set($page_3 = ${data.current_page} + 1)
        #else
            #set($page_3 = 1)
        #end


        <action>
            <link type="block" style="button" target="${xml_nfid_block_self}" params="tabId=3&currentPage=$!{page_3}&pageSize=5" >
                <text name="label">查看更多</text>
            </link>
        </action>
    </group>

    <group>
        <tab>
            <text name="tab_name">$!{data.tab4.name}</text>
        </tab>
        #if(4 == ${data.tab_id} && ${data.tab4.item_list} && ${data.tab4.item_list.size()} > 0)
            #foreach(${item} in $!{data.tab4.item_list})
                <LinearLayout>
                    <text name="p_item_type">$!{item.item_type}</text>
                    <link type="url" style="button" target="$!{item.target}" params="$!{item.params}">
                    <image name="p_img" url="$!{item.img}"/>
                    <text name="p_title">$!{item.title}</text>
                    <text name="p_sub_title">$!{item.sub_title}</text>
                    <text name="p_attr_1">$!{item.attr_1}</text>
                    <text name="p_attr_2">$!{item.attr_2}</text>
                    <text name="p_attr_3">$!{item.attr_3}</text>
                    </link>
                </LinearLayout>
            #end
        #end

        #if(4 == ${data.tab_id})
            #set($page_4 = ${data.current_page} + 1)
        #else
            #set($page_4 = 1)
        #end

        <action>
            <link type="block" style="button" target="${xml_nfid_block_self}" params="tabId=4&currentPage=$!{page_4}&pageSize=5" >
                <text name="label">查看更多</text>
            </link>
        </action>
    </group>

</template>

示例 4：气泡列表

气泡列表可以用于展示订单列表或商品列表，支持展示图文内容，也支持仅展示文字内容，样式如图：

如果需要返回气泡列表内容，企业需要在一触即达查询节点内配置接口，并加入固定入参currentPage,pageSize。拉取列表时，七鱼调用企业服务器，例如：currentPage=1,pageSize=5，代表拉取第1页共5条数据（注意：若params包含的参数为空，默认拉取的第1页共5条数据，即相当于currentPage=1,pageSize=5）。企业可以自定义pageSize，默认值为5，最大不超过10。currentPage可以根据访客的点选动态赋值。一触即达查询节点的配置请参看上文抽屉列表示例部分。

返回示例

result返回值为企业订单列表的JSON数组

{
  "code": 200,
  "desc": "success",
  "result": {
    "data": {
      "current_page": 1,
      "page_size": 5,
      "introducer": "请选择您想咨询的订单",
      "banner": "选择咨询的订单",
      "empty_list_hint": "无数据返回提示文案aaa",
      "tab1":{
        "item_list": [
          {
            "item_type": "1",
            "img": "[https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg](https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg)",
            "title": "item分组",
            "sub_title": "卖家已发货"
          },
          {
            "item_type": "0",
            "img": "[https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg](https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg)",
            "title": "1ZARA 女装 加大码飞行员夹克777",
            "sub_title": "1ZARA 女装 加大码飞行员夹克",
            "attr_1": "100",
            "attr_2": "100",
            "attr_3": "100",
            "target": "[http://www.baidu.com](http://www.baidu.com)",
            "params": "orderNo=0"

          },
          {
            "item_type": "0",
            "img": "[https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg](https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg)",
            "title": "1ZARA 女装 加大码飞行员夹克888",
            "sub_title": "1ZARA 女装 加大码飞行员夹克",
            "attr_1": "100",
            "attr_2": "100",
            "attr_3": "100",
            "target": "[http://www.baidu.com](http://www.baidu.com)",
            "params": "orderNo=0"

          },
          {
            "item_type": "1",
            "img": "[https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg](https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg)",
            "title": "item分组",
            "sub_title": "卖家已发货"
          },
          {
            "item_type": "0",
            "img": "[https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg](https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg)",
            "title": "1ZARA 女装 加大码飞行员夹克999",
            "sub_title": "1ZARA 女装 加大码飞行员夹克",
            "attr_1": "100",
            "attr_2": "100",
            "attr_3": "100",
            "target": "[http://www.baidu.com](http://www.baidu.com)",
            "params": "orderNo=0"

          },
          {
            "item_type": "0",
            "img": "[https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg](https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg)",
            "title": "1ZARA 女装 加大码飞行员夹克000",
            "sub_title": "1ZARA 女装 加大码飞行员夹克",
            "attr_1": "100",
            "attr_2": "100",
            "attr_3": "100",
            "target": "[http://www.baidu.com](http://www.baidu.com)",
            "params": "orderNo=0"
          }
        ]
      }
    }
  }
}
​字段说明

参数类型必传说明
current_pageInt是当前页，从params中获取，若params为空，默认为1
page_sizeInt是每页数据条数，从params中获取，若params为空，默认为5，最多不超过10条
introducerString是引导语，不可为空值
bannerString否提示语
empty_list_hintString是无数据返回提示文案，不可为空值
tab1Object是列表分组，气泡列表仅支持一个列表分组

列表分组格式说明:

参数类型必传说明
item_listArray是列表分组中item分组数据和item详细数据

item分组数据(item_type=1)格式说明:

参数类型必须说明
item_typeString是值固定为1
imgString否缩略图地址
titleString否标题，可以为空
sub_titleString否副标题

item详细数据(item_type=0)格式说明:

参数类型必须说明
item_typeString是值固定为0
imgString否缩略图地址
titleString否标题
sub_titleString否副标题
attr_1String否属性1
attr_2String否属性2
attr_3String否属性3
paramsString否点击item跳转时携带的参数
targetString否点击item的跳转目标地址或目标节点，若仅展示列表内容可以为空
​xml模板填充样式
<template id="bubble_list">
    <LinearLayout>
        <text name="label">$!{data.introducer}</text>
        <text name="empty_list_hint">$!{data.empty_list_hint}</text>
        <text name="title">$!{data.banner}</text>
    </LinearLayout>

    <group>
        #if(${data.tab1.item_list} && ${data.tab1.item_list.size()} > 0)
            #foreach(${item} in $!{data.tab1.item_list})
                <LinearLayout>
                    <text name="p_item_type">$!{item.item_type}</text>
                    <link type="block" style="button" target="${xml_nfid_block_1}" params="$!{item.params}">
                        <image name="p_img" url="$!{item.img}"/>
                        <text name="p_title">$!{item.title}</text>
                        <text name="p_sub_title">$!{item.sub_title}</text>
                        <text name="p_attr_1">$!{item.attr_1}</text>
                        <text name="p_attr_2">$!{item.attr_2}</text>
                        <text name="p_attr_3">$!{item.attr_3}</text>
                    </link>
                </LinearLayout>
            #end
        #end

        #set($page = ${data.current_page} + 1)
        <action>
            <link type="block" style="button" target="${xml_nfid_block_self}" params="currentPage=$!{page}&pageSize=5" >
            <text name="label">查看更多</text>
            </link>
        </action>
    </group>

</template>

示例 5：横滑卡片列表

横滑卡片列表可以用于展示商品列表，支持展示图文内容，样式如下：

如果需要返回横滑卡片列表内容，企业需要在一触即达查询节点内配置接口，并加入固定入参currentPage,pageSize。拉取列表时，七鱼调用企业服务器，例如：currentPage=1,pageSize=5，代表拉取第1页共5条数据（注意：若params包含的参数为空，默认拉取的第1页共5条数据，即相当于currentPage=1,pageSize=5）。企业可以自定义pageSize，默认值为5，最大不超过10。currentPage可以根据访客的点选动态赋值。一触即达查询节点的配置请参看上文抽屉列表示例部分。

返回示例

result返回值为企业订单列表的JSON数组

{
  "code": 200,
  "desc": "success",
  "result": {
    "data": {
      "current_page": 1,
      "page_size": 5,
      "introducer": "引导语aaa",
      "empty_list_hint": "无数据返回提示文案aaa",
      "tab1":{
        "item_list": [
          {
            "item_type": "0",
            "img": "[https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg](https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg)",
            "title": "1ZARA 女装 加大码飞行员夹克777",
            "sub_title": "1ZARA 女装 加大码飞行员夹克",
            "attr_1": "100",
            "attr_2": "100",
            "attr_3": "100",
            "target": "[http://www.baidu.com](http://www.baidu.com)",
            "params": "orderNo=0"

          },
          {
            "item_type": "0",
            "img": "[https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg](https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg)",
            "title": "1ZARA 女装 加大码飞行员夹克888",
            "sub_title": "1ZARA 女装 加大码飞行员夹克",
            "attr_1": "100",
            "attr_2": "100",
            "attr_3": "100",
            "target": "[http://www.baidu.com](http://www.baidu.com)",
            "params": "orderNo=0"

          },
          {
            "item_type": "0",
            "img": "[https://img.alicdn.com/imgextra/i2/2228361831/TB2Zo._a5GO.eBjSZFjXXcU9FXa_!!2228361831.jpg](https://img.alicdn.com/imgextra/i2/2228361831/TB2Zo._a5GO.eBjSZFjXXcU9FXa_!!2228361831.jpg)",
            "title": "1ZARA 女装 加大码飞行员夹克",
            "sub_title": "1ZARA 女装 加大码飞行员夹克",
            "attr_1": "100",
            "attr_2": "100",
            "attr_3": "100",
            "target": "[http://www.baidu.com](http://www.baidu.com)",
            "params": "orderNo=0"

          },
          {
            "item_type": "0",
            "img": "[https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg](https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg)",
            "title": "1ZARA 女装 加大码飞行员夹克999",
            "sub_title": "1ZARA 女装 加大码飞行员夹克",
            "attr_1": "100",
            "attr_2": "100",
            "attr_3": "100",
            "target": "[http://www.baidu.com](http://www.baidu.com)",
            "params": "orderNo=0"

          },
          {
            "item_type": "0",
            "img": "[https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg](https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg)",
            "title": "1ZARA 女装 加大码飞行员夹克000",
            "sub_title": "1ZARA 女装 加大码飞行员夹克",
            "attr_1": "100",
            "attr_2": "100",
            "attr_3": "100",
            "target": "[http://www.baidu.com](http://www.baidu.com)",
            "params": "orderNo=0"
          }
        ]
      }
    }
  }
}
​字段说明

参数类型必传说明
current_pageInt是当前页，从params中获取，若params为空，默认为1
page_sizeInt是每页数据条数，从params中获取，若params为空，默认为5，最多不超过5条
introducerString是引导语，不可为空值
empty_list_hintString是无数据返回提示文案，不可为空值
tab1Object是列表分组，横滑卡片列表仅支持一个列表分组

列表分组格式说明：

参数类型必传说明
item_listArray是列表分组中的item详细数据

item分组数据(item_type=1)格式说明:

参数类型必须说明
item_typeString是值固定为1
imgString否缩略图地址
titleString否标题，可以为空

item详细数据(item_type=0)格式说明:

参数类型必须说明
item_typeString是值固定为0
imgString否缩略图地址
titleString否标题
sub_titleString否副标题
attr_1String否属性1
attr_2String否属性2
attr_3String否属性3
paramsString否点击item跳转时携带的参数
targetString否点击item的跳转目标地址或目标节点，若仅展示列表内容可以为空
注意事项

<1> 横滑卡片的数据填充企业可以按两种模式处理：一种是传统的分页模式，此时currentPage代表页码；一种是随机模式，此时currentPage代表轮次，可以随机返回item。企业可以根据不同场景选择合适的模式。

​xml模板填充样式
<template id="horizontal_sliding_list">
    <LinearLayout>
        <text name="label">$!{data.introducer}</text>
        <text name="empty_list_hint">$!{data.empty_list_hint}</text>
    </LinearLayout>

    #if(${data.tab1.item_list} && ${data.tab1.item_list.size()} > 0)
        #foreach(${item} in $!{data.tab1.item_list})
            <LinearLayout>
                <link type="block" style="button" target="${xml_nfid_block_1}" params="$!{item.params}">
                <image name="p_img" url="$!{item.img}"/>
                <text name="p_title">$!{item.title}</text>
                <text name="p_sub_title">$!{item.sub_title}</text>
                <text name="p_attr_1">$!{item.attr_1}</text>
                <text name="p_attr_2">$!{item.attr_2}</text>
                <text name="p_attr_3">$!{item.attr_3}</text>
                </link>
            </LinearLayout>
        #end
    #end

    #set($page = ${data.current_page} + 1)
    <action>
        <link type="block" style="button" target="${xml_nfid_block_self}" params="currentPage=$!{page}&pageSize=5" >
        <text name="label">换一批</text>
        </link>
    </action>

</template>

示例 6：气泡节点列表

气泡节点列表可以实现类似时间轴列表的效果，可以用于展示物流信息，企业也可以根据自己的需求灵活定制，样式如下：

返回示例

拉取气泡节点列表时，七鱼调用企业服务器，目前不用在一触即达查询节点的接口配置中设置固定入参。result返回值为订单列表的JSON数组

{
  "code": 200,
  "desc": "success",
  "result": {
    "data":
    {
      "introducer": "引导语",
      "empty_list_hint": "无数据返回提示文案",
      "banner": "标题",
      "footer": "查看更多",
      "target": "[https://qiyukf.com](https://qiyukf.com)",
      "item_list": [
        {
          "title": "业务员二片区岸上蓝山正在第1次派件",
          "desc": "2017-05-17 18:01:38",
          "is_current": "1"
        },
        {
          "title": "业务员二片区岸上蓝山正在第2次派件",
          "desc": "2017-05-17 18:01:38",
          "is_current": "0"
        },
        {
          "title": "业务员二片区岸上蓝山正在第3次派件",
          "desc": "2017-05-17 18:01:38",
          "is_current": "0"
        },
        {
          "title": "业务员二片区岸上蓝山正在第4次派件",
          "desc": "2017-05-17 18:01:38",
          "is_current": "0"
        },
        {
          "title": "业务员二片区岸上蓝山正在第5次派件",
          "desc": "2017-05-17 18:01:38",
          "is_current": "0"
        },
        {
          "title": "业务员二片区岸上蓝山正在第6次派件",
          "desc": "2017-05-17 18:01:38",
          "is_current": "0"
        },
        {
          "title": "业务员二片区岸上蓝山正在第7次派件",
          "desc": "2017-05-17 18:01:38",
          "is_current": "0"
        }
      ]
    }
  }
}
​字段说明

参数类型必传说明
introducerString是引导语，不可为空值
bannerString否标题
footerString否自定义底部按钮的提示语，默认“查看更多”
targetString否如果底部按钮的跳转事件设置为跳转到外链，此处传入外链的链接地址
empty_list_hintString是无数据返回提示文案，不可为空值
item_listArray是列表

item数据格式说明:

参数类型必须说明
titleString否标题
descString否描述
is_currentString是是否停留在当前节点：1-是 0-否
​xml模板填充样式
<template id="bubble_node_list">
    <LinearLayout>
        <text name="label">$!{data.introducer}</text>
        <text name="empty_list_hint">$!{data.empty_list_hint}</text>
        <text name="title">$!{data.banner}</text>
    </LinearLayout>

    <LinearLayout>
        <text name="label">$!{data.title}</text>
    </LinearLayout>

    #if(${data.item_list} && ${data.item_list.size()} > 0)
        #foreach($item in $!{data.item_list})
            <LinearLayout>
                <text name="p_title">$!{item.title}</text>
                <text name="p_desc">$!{item.desc}</text>
                <text name="p_is_current">$!{item.is_current}</text>
            </LinearLayout>
        #end
        </LinearLayout>
    #end

    <action>
        <link type="url" style="button" target="$!{data.target}"">
            <text name=\"label\">${data.footer}</text>
        </link>
    </action>
</template>

Velocity语法赋值

如果企业需要定制一触即达输出的样式，企业需要与七鱼预先约定字段，并在一触即达中配置xml填充信息。配置xml时可参考以上xml模版填充样式。xml模版同时支持Velocity语法赋值，内容如下：

​赋值

$!{参数名称}

​遍历

#foreach ($item in $list)
#end

​注：当接口返回结果的result结果为数组时，$list 可以直接是用 $result 赋值遍历。

#foreach ($item in $result)
#end

​条件

    #if($(orderDto))
          订单对象有值
      #else
          订单对象为空
      #end

      #if(!$(orderDto))
          订单对象为空
      #else
         订单对象有值
     #end

​变量约定

参数具体指代约定在xml中的velocity的变量名称样例
跳转至节点本身xml_nfid_block_selftarget="${xml_nfid_block_self}"
跳转至其他节点前缀：xml_nfid_block_+后缀：1-2位数字target="${xml_nfid_block_1}"
跳转至url地址前缀：xml_nfid_url_+后缀：1-2位数字params="nodeId=${xml_nfid_url_1}" target="http://www.baidu.com"

移动SDK接入指南

​Android 接入指南

  1. 请确保你的SDK为最新版本。
compile 'com.qiyukf.unicorn:unicorn:3.10.0'
  1. 在SDK初始化时，为 YSFOptions 的 onBotEventListener 赋值：
// ... your codes
// YSFOptions options = new YSFOptions();
options.onBotEventListener = new OnBotEventListener() {
@Override
public boolean onUrlClick(Context context, String url) {
  // 加入处理一触即达url的代码
  BrowserActivity.start(context, url);
  return true;
  }
  };
// Unicorn.init(this, "appKey", options, new UnicornImageLoader());
// ... your codes

​IOS 接入指南

  1. 需要的 iOS SDK 版本是 v3.10.0 或以上
  2. 自定义 bot 点击事件处理：
QYCustomActionConfig *actionConfig = [[QYSDK sharedSDK] customActionConfig];
//botClick 是 bot 相关点击回调
actionConfig.botClick =【你的代码】

这篇文档有帮助吗？

服务先知

机器人服务先知常见问题和快捷短语企业接口的请求、签名和响应说明。

快捷短语跳转

快捷短语跳转。

目录

一触即达
对接方式
​调用说明​
接口请求地址
​响应参数
示例
返回示例
​接口调用流程
​参数说明
对接示例
示例 1：文本
​字段说明
​xml模板填充样式
示例 2：文本+按钮列表
​字段说明
​按钮字段说明
​xml模板填充样式
示例 3：抽屉列表
返回示例
示例 4：气泡列表
返回示例
​字段说明
​xml模板填充样式
示例 5：横滑卡片列表
返回示例
​字段说明
注意事项
​xml模板填充样式
示例 6：气泡节点列表
返回示例
​字段说明
​xml模板填充样式
Velocity语法赋值
移动SDK接入指南
​Android 接入指南
​IOS 接入指南