# Json Api组件

很多时候，Messenger用户希望在Messenger上便捷的获取自己的账号信息（例如订单详情，购买记录等等），但这些信息存放在商户的服务器中。按常规解决方式，Bothub必须进行技术对接获取这些信息再发送给用户。这样的问题是：

* 不灵活。万一商户接口有数据结构改动，或者是希望修改显示的样式，甚或是临时关闭该功能，都需要Bothub一方改动代码并且重新上线才能做到。
* 影响了bot的完整体验。由于这一部分无法在后台自行配置，相当于整个Bot的应答链中断了，造成如果要在发送这些消息时关联到其他内容块的时候非常麻烦。

**由此，我们制作了Json Api插件，让用户能够以简单配置完成在自己系统里查询数据并发送消息这一逻辑。**

![](https://3545383198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LBxiFMKIFEMsz8J7IuU%2F-LCTAV_QkstipKFfyGM-%2F-LCTE84cBMrLfT4mrDFu%2Fp3f1p801.jpg?alt=media\&token=129fc9d2-e895-4928-b406-e66988e50dcd)

## 插件介绍

当一个Json Api插件被发送给用户时，实际的逻辑如下

* Bothub会发一个Get请求到商户指定的URL。这个URL可以指定带上一些参数，包括用户的名字，facebook id，以及用户上一条发送的消息
* 商户接收到调用之后，根据用户参数做一些查询，组织好发给用户的信息内容，返回给Bothub
* Bothub将消息发送给用户

![Jason Api插件窗口](https://3545383198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LBxiFMKIFEMsz8J7IuU%2F-LCTAV_QkstipKFfyGM-%2F-LCTEi3ayoCBxROnNIdb%2Fp3f1p802.jpg?alt=media\&token=027f275d-8188-4429-b0f8-b24d97aae004)

### URL指定

URL是以http\:// 或者https\:// 开头的地址。可以使用参数指代部分用户信息，比如<http://www.bothub.ai/order-by-id/>

可用的参数请前往以&#x4E0B;***可用模板***&#x4E2D;查看

{% content-ref url="../api/messenger-api" %}
[messenger-api](https://bothub.gitbook.io/project/advanced-tool/api/messenger-api)
{% endcontent-ref %}

点击用户属性框可以看到选择配置中可以选择给URL带参数（即url后面的以问号附属的参数)。可选的参数仍然&#x662F;***可用模板***&#x4E2D;列举的部分。为了方便商户结合用户的输入进行判断，还可以使用下面的参数

| 添加参数            | 对应内容                                       |
| --------------- | ------------------------------------------ |
| last\_message   | 用户向页面发送的最近一条文本信息的内容或者是postback payload的内容。 |
| fb\_id          | 用户的Facebook ID                             |
| fb\_first\_name | 用户名                                        |
| fb\_last\_name  | 用户的姓                                       |
| fb\_locale      | 用户的所在地（例如：en/US）                           |
| fb\_timezone    | 用户时区（-12～12）                               |
| fb\_gender      | 用户性别（female或者male）                         |

### 验证

考虑到商户开放的API可能需要验证，通过配置此部分可以让Get请求在Request header中放置一组key和value对来进行验证。

### 错误跳转

商户可以指定一个内容块，当商户对于API的处理处于以下情况时

* 超时（限制为30秒)
* 返回http状态码为除200之外的其他值
* 返回的json结构不符合要求 发送此内容块的内容给用户（例如，这个块可以显示服务暂时不可用，请稍后再试等内容）。如果商户不指定这个块，将不发送任何内容给用户。

### 返回值样式

返回值为json格式，结构如下，和[发送模板消息](https://bothub.gitbook.io/project/advanced-tool/api/template-message)中的结构类似。

> ```
> {
>     "type" : "send_block",
>     "message": {
>         "block_name": "points_info",
>         "params": [
>             {
>                 "key": "points",
>                 "value": "20000"
>             },
>             {
>                 "key": "prize",
>                 "value": "Gold Medal"
>             }
>         ]
>     },
> }
> ```

### **返回值说明**

* type: 必须为send\_block
* message：等同于[发送模板消息](https://bothub.gitbook.io/project/advanced-tool/api/template-message)的message字段。