# 消息推送API

## 请求URL

```http
https://joinchat.ai/api/send_message
```

## 请求示例和接口安全性验证

JoinChat会为每个机器人生成独一无二的私钥。在调取Joinchat发送API时，开发人员需要用此密钥对整个请求参数提进行sha256、base64加密，并将签名加在请求Header头的`x-joinchat-signature`字段里。JoinChat会根据请求体和签名验证接口安全性,  注意不要泄露自己的私钥。开发者可以随时在后台`设置--API管理页面`更改自己的私钥

下面是调用JoinChat发送API向用户发送消息的简单示例 ：

```php
<?php
// API管理中秘钥
const API_SECRET  = 'xxxxx';

// 请求参数
$params = '{"page_id":12345,"recipient":{"id":"123456"},
"message":{"template_type":"text","text":"Hello World"},
"tag":"ACCOUNT_UPDATE","delay":1}';

// 将参数和秘钥加密生成签名
$sign = base64_encode(hash_hmac('sha256', $params, API_SECRET, true));

/*httpClient 是伪代码*/
$client = new httpClient();

// 伪代码, 将签名添加到请求头中
$client->setHeaders(['x-joinchat-signature' => $sign]);

// 调用JoinChat发送API向messenger用户发送消息
$resp = $client->post('https://joinchat.ai/api/send_message', $params);
```

## 请求参数解释

### 参数示例

```php
{
    "page_id":12345,
    "recipient":{
        "uuid":"123456"
    },
    "message":{
        "template_type":"text",
		"text":"Hello World"
    },
	"tag":"ACCOUNT_UPDATE",
	"delay": 1
}
```

### 参数含义

| 字段        | 类型  | 说明                                                                    |
| --------- | --- | --------------------------------------------------------------------- |
| page\_id  | 字符串 | 机器人绑定的facebook主页id, 可在设置-API中查看                                       |
| recipient | 对象  | 对消息接收人的说明。所有请求都必须包含下列任一属性：`id, phone, email, uuid`。参考`发送者对象recipient` |
| message   | 对象  | 消息对象, 有五种, 包括 文本消息, 菜单消息,  画册消息, 列表消息, 回执消息, 参考各类型消息文档                |
| tag       | 字符串 | 消息标签, 可以不受24小时发送时间窗限制, 参考消息标签文档                                       |
| delay     | int | 消息延时, 单位s, 连续发送消息时, 先后顺序不好控制, 可加入适当延时, 最大10                           |

## 发送者对象recipient

> 开发者可以通过四种方式给用户发送messenger消息, 四者只能选一个

| 字段    | 类型  | 说明                                 |
| ----- | --- | ---------------------------------- |
| id    | 字符串 | 消息接收人的facebook\_id, 可在用户管理中查看      |
| phone | 字符串 | 消息接收人的phone, 可在用户管理中查看, 需用户绑定phone |
| email | 字符串 | 消息接收人的email, 可在用户管理中查看, 需用户绑定email |
| uuid  | 字符串 | 见uuid介绍                            |

## recipient.uuid

### 介绍

> uuid是JoinChat为开发者提供了一种非常灵活的消息发送方式,  开发者可以将自己网站的用户和uuid做关联, 当开发者随时想向自己网站用户发送 messenger 消息, 既可通过和用户关联的uuid请求JoinChat发送API, 从而将消息送达到facebook用户, 使用场景如下:

* 用户注册后, 给用户messenger推送积分信息, 并且发送优惠券
* 用户购物车弃购后, 给用户messenger推送召回消息, 提高转化率
* 用户下单后, 给用户推送订单回执

### 配置方法

如何将自己网站的用户和uuid做关联呢? 三步即可

#### 创建插件

登录JoinChat后台, 点击推广插件, 创建Send to Messenger插件或者优惠券插件;

![](https://536261050-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LbSzTk1SGLwJ3VFu1kJ%2F-Lk7-6vT_KfQt2DGjm6f%2F-Lk7p6WyWvBxdRSbj6BC%2Fimage.png?alt=media\&token=d5340f49-2100-4555-b4e9-c42701c83a3f)

#### 配置SDK并安装代码

创建推广插件后, 点击SDK管理, 选择刚创建的插件, 启用后, 然后复制链接插码到自己的网站

![](https://536261050-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LbSzTk1SGLwJ3VFu1kJ%2F-Lk7q3BxOs0ZmHCmc-LM%2F-Lk7ymiNbsf40x8xGGTf%2Fimage.png?alt=media\&token=ab7fa512-84d2-493a-ba95-33ba495614cb)

开发者打开自己网站, 即可看到send to messenger插件

![](https://536261050-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LbSzTk1SGLwJ3VFu1kJ%2F-Lk7q3BxOs0ZmHCmc-LM%2F-Lk7zEQnXgwi6-fsrCaB%2Fimage.png?alt=media\&token=d0ad418c-7f4f-40bf-90ff-87bf03330e7c)

#### 编写Javascript回调函数

当用户点击`Send to Messenger`插件, JoinChat会执行开发者设置的Javascript回调函数, 在回调函数中开发者可以将uuid和自己网站的用户id关联起来, 回调函数设置方式如下

```javascript
<script type="text/javascript">
    /**
     * 回调函数必须命名为joinchatSendToMessengerCallback
     * 用户可以在回调函数中执行任何js原生代码, 包括发送Ajax请求
     * Joinchat会将uuid传给回调函数
     * 开发者可以向后端发送ajax请求, 将uuid和用户id做关联
     * @param uuid JoinChat为每个用户生成的唯一标识, 存到Cookie中
     */
    let joinchatSendToMessengerCallback = function (uuid) {
        console.log('hello Joinchat, uuid is: ' + uuid);
        let ajax = new XMLHttpRequest();
        // 向开发者后端发送ajax请求, 将uuid和用户id做关联
        ajax.open('get','/save-uuid?uuid='+uuid);
        ajax.send();
        ajax.onreadystatechange = function () {
            if (ajax.readyState==4 &&ajax.status==200) {
                console.log(ajax.responseText);
            }
        }
    }
</script>

<script src="https://joinchat.ai/js/analytics/sdk/15150c9d53ccc1eb21ffef1af5b6b184.js"></script>
```

开发者自己网站用户和uuid做了关联, 即可以随时向用户发送messenger消息

## 消息类型

joinchat支持用户发送文本消息, 菜单消息, 画册消息, 列表消息和回执消息,&#x20;

&#x20;其中文本消息为普通消息, 其他消息都被模板消息.

模板消息可以增加按钮, 首先先介绍支持的按钮类型, 然后介绍支持的各种消息类型

开发者想了解messenger消息类型, 可参阅facebook messenger 官方文档

{% embed url="<https://developers.facebook.com/docs/messenger-platform/send-messages>" %}

## 按钮类型

### 网址按钮

#### 格式

```javascript
{
  "type": "web_url",
  "url": "<URL_TO_OPEN_IN_WEBVIEW>",
  "title": "<BUTTON_TEXT>",
}
```

#### 参数解释

* type: 值必须为web\_url
* url: 点击按钮要打开的网址,
* title: 按钮标题。请勿超过 20 个字符。

| 属性                     | 类型  | 说明                                                            |
| ---------------------- | --- | ------------------------------------------------------------- |
| `type`                 | 字符串 | 按钮的类型。必须是 `web_url`。                                          |
| `title`                | 字符串 | 按钮标题。请勿超过 20 个字符。                                             |
| `url`                  | 字符串 | **用户轻触按钮后，此网址将在移动浏览器中打开。需要在Joinchat管理端将该网址域名添加到白名单中**         |
| `webview_height_ratio` | 字符串 | ***可选。*** WebView 的高度。有效值：`compact`、`tall`、`full`。默认为 `full`。 |

### 回传按钮

#### 格式

```javascript
{
  "type":"postback",
  "title":"<BUTTON_TEXT>",
  "payload":"{\"block_id\":1}"
}
```

#### 参数解释

| 字段        | 类型  | 说明                                                                                                                                        |
| --------- | --- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `type`    | 字符串 | 按钮的类型。必须为 `postback`。                                                                                                                     |
| `title`   | 字符串 | 按钮标题。请勿超过 20 个字符。                                                                                                                         |
| `payload` | 字符串 | <p></p><ul><li><p>点击按钮, 发送到Joinchat的数据, 目前支持格式为:</p><ul><li>block\_id: 点击按钮, 触发的block</li><li>flow\_id: 点击按钮, 触发的flow</li></ul></li></ul> |

## 文本消息

### **请求参数示例:**

```javascript
{
    "page_id":12345,
    "recipient":{
        "id":"123456"
    },
    "message":{
        "template_type":"text",
		"text":"Hello World",
    },
	"tag":"ACCOUNT_UPDATE",
	"delay": 1,
}
```

### **参数解释**

* template\_type: 值必须为text
* text: UTF-8 编码文本，最多 640 个字符。

## 菜单消息

### 请求参数示例:

```javascript
{
    "page_id":12345,
    "recipient":{
        "id":"123456"
    },
    "message":{
		"template_type":"button",
		"text":"What do you want to do next?",
		"buttons":[
		  {
			"type":"web_url",
			"url":"https://www.messenger.com",
			"title":"Visit Messenger"
		  }
		]
    },
	"tag":"ACCOUNT_UPDATE",
	"delay": 3,
}
```

### 参数解释

#### `message` <a href="#payload" id="payload"></a>

| 属性              | 类型      | 说明                                                                                                             |
| --------------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| `template_type` | 字符串     | 值必须为 `button`                                                                                                  |
| `text`          | 字符串     | UTF-8 编码文本，最多 640 个字符。文本显示在按钮上方。                                                                               |
| `buttons`       | 阵列<按钮>  | 显示为行动号召的一组[按钮](https://developers.facebook.com/docs/messenger-platform/send-api-reference/buttons)，包括 1-3 个按钮。 |
| `sharable`      | Boolean | ***可选。*** 设置为 `true`，可为模板消息启用 Messenger 原生分享按钮。默认为 `false`。                                                    |

![](https://536261050-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LbSzTk1SGLwJ3VFu1kJ%2F-Lk3RUETYohsMvz3mNrU%2F-Lk3SDXEcc9RjRqDv1ZX%2Fimage.png?alt=media\&token=57fb30bc-1d4c-47b9-a2c0-10866dec9f1c)

## 画册消息

### 请求参数示例:

```javascript
{
    "page_id":12345,
    "recipient":{
        "id":"123456"
    },
    "message":{
        "template_type":"generic",
        "elements":[
            {
                "title":"Welcome!",
                "image_url":"https://petersfancybrownhats.com/company_image.png",
                "subtitle":"We have the right hat for everyone.",
                "default_action":{
                    "type":"web_url",
                    "url":"https://petersfancybrownhats.com/view?item=103",
                    "webview_height_ratio":"tall"
                },
                "buttons":[
                    {
                        "type":"web_url",
                        "url":"https://petersfancybrownhats.com",
                        "title":"View Website"
                    },
                    {
                        "type":"postback",
                        "title":"Start Chatting",
                        "payload":"DEVELOPER_DEFINED_PAYLOAD"
                    }
                ]
            }
        ]
    },
	"tag":"ACCOUNT_UPDATE",
	"delay": 3,
}
```

### 参数解释

#### `message` <a href="#payload" id="payload"></a>

| 属性                   | 类型                                                                                                                        | 说明                                                                                                                                                                           |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `template_type`      | 字符串                                                                                                                       | 值必须为 `generic`                                                                                                                                                               |
| `sharable`           | Boolean                                                                                                                   | ***可选。*** 设置为 `true`，可为模板消息启用 Messenger 原生分享按钮。默认为 `false`。                                                                                                                  |
| `image_aspect_ratio` | 字符串                                                                                                                       | ***可选。*** 呈现 `element.image_url`指定的图片时使用的宽高比。必须为 `horizontal` (1.91:1) 或 `square`(1:1)。默认为 `horizontal`。                                                                     |
| `elements`           | 数组<[`element`](https://developers.facebook.com/docs/messenger-platform/reference/template/generic/?translation#elements)> | [`element`](https://developers.facebook.com/docs/messenger-platform/reference/template/generic/?translation#elements) 对象的数组，描述要发送的常规模板的实例。指定多个元素时，会发送可水平滚动的模板轮播。最多支持 10 个元素。 |

#### `message.elements` <a href="#elements" id="elements"></a>

对于每一条消息，常规模板最多支持 10 个元素。除 `title` 之外，还必须至少设置一种属性。

| 属性名称             | 类型                                                                                                                     | 说明                                                                                                                                         |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `title`          | 字符串                                                                                                                    | 显示在模板中的标题。不超过 80 个字符。                                                                                                                      |
| `subtitle`       | 字符串                                                                                                                    | ***可选。*** 显示在模板中的副标题。不超过 80 个字符。                                                                                                           |
| `image_url`      | 字符串                                                                                                                    | ***可选。*** 显示在模板中的图片网址。                                                                                                                     |
| `default_action` | 对象                                                                                                                     | ***可选。*** 用户轻触模板时执行的默认操作。接受与[网址按钮](https://developers.facebook.com/docs/messenger-platform/send-api-reference/url-button)相同的属性，`title` 除外。 |
| `buttons`        | 数组<[`button`](https://developers.facebook.com/docs/messenger-platform/reference/template/generic/?translation#button)> | ***可选。*** 要添加到模板中的[按钮](https://developers.facebook.com/docs/messenger-platform/send-api-reference/buttons)数组。每个元素最多支持 3 个按钮。               |

![](https://536261050-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LbSzTk1SGLwJ3VFu1kJ%2F-Lk3RUETYohsMvz3mNrU%2F-Lk3S-suceSihqnmCDGv%2Fimage.png?alt=media\&token=a51511c5-e328-4db8-9e21-760ce2641f22)

## 列表消息

### 请求参数示例:

```javascript
{
    "page_id":12345,
    "recipient":{
        "id":"123456"
    },
    "message":{
        "template_type":"list",
        "top_element_style":"compact",
        "elements":[
            {
                "title":"Classic T-Shirt Collection",
                "subtitle":"See all our colors",
                "image_url":"https://peterssendreceiveapp.ngrok.io/img/collection.png",
                "buttons":[
                    {
                        "title":"View",
                        "type":"web_url",
                        "url":"https://joinchat.ai",
                        "messenger_extensions":true,
                        "webview_height_ratio":"tall",
                        "fallback_url":"https://peterssendreceiveapp.ngrok.io/"
                    }
                ]
            },
            {
                "title":"Classic White T-Shirt",
                "subtitle":"See all our colors",
                "default_action":{
                    "type":"web_url",
                    "url":"https://joinchat.ai",
                    "messenger_extensions":false,
                    "webview_height_ratio":"tall"
                }
            },
            {
                "title":"Classic Blue T-Shirt",
                "image_url":"https://peterssendreceiveapp.ngrok.io/img/blue-t-shirt.png",
                "subtitle":"100% Cotton, 200% Comfortable",
                "default_action":{
                    "type":"web_url",
                    "url":"https://joinchat.ai",
                    "messenger_extensions":true,
                    "webview_height_ratio":"tall",
                    "fallback_url":"https://peterssendreceiveapp.ngrok.io/"
                },
                "buttons":[
                    {
                        "title":"Shop Now",
                        "type":"web_url",
                        "url":"https://joinchat.ai",
                        "messenger_extensions":true,
                        "webview_height_ratio":"tall",
                        "fallback_url":"https://peterssendreceiveapp.ngrok.io/"
                    }
                ]
            }
        ],
        "buttons":[
            {
                "title":"View More",
                "type":"postback",
                "payload":"payload"
            }
        ]
    },
	"tag":"ACCOUNT_UPDATE",
	"delay": 3,
}
```

### 参数解释

#### `message` <a href="#payload" id="payload"></a>

| 属性                  | 类型                                                                                                 | 说明                                                                                                                                                                           |
| ------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `template_type`     | 字符串                                                                                                | 值必须为 `list`                                                                                                                                                                  |
| `top_element_style` | 字符串                                                                                                | <p><em><strong>可选。</strong></em> 设置第一个列表项的格式。Messenger 网页客户端目前仅呈现 <code>compact</code> 格式。</p><p><code>compact</code>:呈现无格式的列表项。</p><p><code>large</code>:将第一个列表项呈现为封面项。</p> |
| `buttons`           | 一组<[按钮](https://developers.facebook.com/docs/messenger-platform/send-api-reference/buttons)>       | ***可选。*** 显示在列表底部的[按钮](https://developers.facebook.com/docs/messenger-platform/send-api-reference/buttons)。最多支持 1 个按钮。                                                       |
| `elements`          | 一组<[元素](https://developers.facebook.com/docs/messenger-platform/reference/template/list#elements)> | <p>描述列表中各项目的一组元素。<br></p><p>要求最少 2 个元素。最多支持 4 个元素。</p>                                                                                                                       |
| `sharable`          | Boolean                                                                                            | ***可选。*** 设置为 `true`，可为模板消息启用 Messenger 原生分享按钮。默认为 `false`。                                                                                                                  |

#### `message.elements` <a href="#elements" id="elements"></a>

| 属性               | 类型                                                                                           | 说明                                                                                                                                                                                                                                                |
| ---------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`          | 字符串                                                                                          | <p>显示为列表项标题的字符串。 不超过 80 个字符。如果标题跨越太多行，则可能会被截断。</p><p>元素也必须至少设置 <code>image\_url</code> 或 <code>subtitle</code> 之一。</p>                                                                                                                            |
| `subtitle`       | 字符串                                                                                          | <p><em><strong>可选。</strong></em> 显示为列表项副标题的字符串。不超过 80 个字符。如果副标题跨越太多行，则可能会被截断。</p><p>元素必须至少设置 <code>image\_url</code> 或 <code>subtitle</code> 之一。</p>                                                                                              |
| `image_url`      | 字符串                                                                                          | <p><em><strong>可选。</strong></em> 要显示在列表项中的图片网址。</p><p>元素必须至少设置 <code>image\_url</code> 或 <code>subtitle</code> 之一。</p>                                                                                                                            |
| `default_action` | 对象                                                                                           | <p><em><strong>可选。</strong></em><a href="https://developers.facebook.com/docs/messenger-platform/send-api-reference/url-button#fields">网址按钮</a>，指定用户轻触列表项时要执行的默认操作。</p><p>仅当 <code>messenger\_extensions</code> 属性设置为 <code>true</code> 时允许使用</p> |
| `buttons`        | 一组<[按钮](https://developers.facebook.com/docs/messenger-platform/send-api-reference/buttons)> | ***可选。*** 要显示在列表项中的[按钮](https://developers.facebook.com/docs/messenger-platform/send-api-reference/buttons)。最多支持 1 个按钮。                                                                                                                           |

![](https://536261050-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LbSzTk1SGLwJ3VFu1kJ%2F-Lk3RUETYohsMvz3mNrU%2F-Lk3RVWOCnpEZYs9p2Cs%2Fimage.png?alt=media\&token=89513529-7500-42d2-8dfa-f2fcb13644cc)

## 回执消息

### 请求参数示例:

```javascript
{
    "page_id":12345,
    "recipient":{
        "uuid":"123456"
    },
    "message":{
        "template_type":"receipt",
        "recipient_name":"Stephane Crozatier",
        "order_number":"12345678902",
        "currency":"USD",
        "payment_method":"Visa 2345",        
        "order_url":"http://petersapparel.parseapp.com/order?order_id=123456",
        "timestamp":"1428444852",         
        "address":{
          "street_1":"1 Hacker Way",
          "street_2":"",
          "city":"Menlo Park",
          "postal_code":"94025",
          "state":"CA",
          "country":"US"
        },
        "summary":{
          "subtotal":75.00,
          "shipping_cost":4.95,
          "total_tax":6.19,
          "total_cost":56.14
        },
        "adjustments":[
          {
            "name":"New Customer Discount",
            "amount":20
          },
          {
            "name":"$10 Off Coupon",
            "amount":10
          }
        ],
        "elements":[
          {
            "title":"Classic White T-Shirt",
            "subtitle":"100% Soft and Luxurious Cotton",
            "quantity":2,
            "price":50,
            "currency":"USD",
            "image_url":"http://petersapparel.parseapp.com/img/whiteshirt.png"
          },
          {
            "title":"Classic Gray T-Shirt",
            "subtitle":"100% Soft and Luxurious Cotton",
            "quantity":1,
            "price":25,
            "currency":"USD",
            "image_url":"http://petersapparel.parseapp.com/img/grayshirt.png"
          }
        ]
      },
	"tag":"ACCOUNT_UPDATE",
	"delay": 3,
}
```

### 参数解释

#### `message` <a href="#payload" id="payload"></a>

| Property         | Type                                                                                                                 | Description                                                                                                                                                                                                                                |
| ---------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `template_type`  | String                                                                                                               | Value must be `receipt`.                                                                                                                                                                                                                   |
| `sharable`       | Boolean                                                                                                              | ***Optional.*** Set to `true` to enable the native share button in Messenger for the template message. Defaults to `false`.                                                                                                                |
| `recipient_name` | String                                                                                                               | The recipient's name.                                                                                                                                                                                                                      |
| `order_number`   | String                                                                                                               | The order number. Must be unique.                                                                                                                                                                                                          |
| `currency`       | String                                                                                                               | The currency of the payment.                                                                                                                                                                                                               |
| `payment_method` | String                                                                                                               | The payment method used. Providing enough information for the customer to decipher which payment method and account they used is recommended. This can be a custom string, such as, "Visa 1234".                                           |
| `timestamp`      | String                                                                                                               | ***Optional.*** Timestamp of the order in seconds.                                                                                                                                                                                         |
| `elements`       | Array<[element](https://developers.facebook.com/docs/messenger-platform/reference/template/receipt#elements)>        | ***Optional.*** Array of a maximum of 100 [`element`](https://developers.facebook.com/docs/messenger-platform/reference/template/receipt#elements) objects that describe items in the order. Sort order of the elements is not guaranteed. |
| `address`        | [`address`](https://developers.facebook.com/docs/messenger-platform/reference/template/receipt#address) object       | ***Optional.*** The shipping address of the order.                                                                                                                                                                                         |
| `summary`        | Object                                                                                                               | The payment summary. See [`summary`](https://developers.facebook.com/docs/messenger-platform/reference/template/receipt#summary).                                                                                                          |
| `adjustments`    | Array<[`adjustment`](https://developers.facebook.com/docs/messenger-platform/reference/template/receipt#adjustment)> | ***Optional.*** An array of [payment](https://developers.facebook.com/docs/messenger-platform/reference/template/receipt#payment)objects that describe payment adjustments, such as discounts.                                             |

#### `message.address` <a href="#address" id="address"></a>

| Property      | Type   | Description                                                                               |
| ------------- | ------ | ----------------------------------------------------------------------------------------- |
| `street_1`    | String | The street address, line 1.                                                               |
| `street_2`    | String | ***Optional.*** The street address, line 2.                                               |
| `city`        | String | The city name of the address.                                                             |
| `postal_code` | String | The postal code of the address.                                                           |
| `state`       | String | The state abbreviation for U.S. addresses, or the region/province for non-U.S. addresses. |
| `country`     | String | The two-letter country abbreviation of the address.                                       |

#### `message.summary` <a href="#summary" id="summary"></a>

The property values of the `summary` object should be valid, well-formatted decimal numbers, using '`.`' (dot) as the decimal separator. Please note that most currencies only accept up to 2 decimal places.

| Property        | Type   | Description                                                          |
| --------------- | ------ | -------------------------------------------------------------------- |
| `subtotal`      | Number | ***Optional.*** The sub-total of the order.                          |
| `shipping_cost` | Number | ***Optional.*** The shipping cost of the order.                      |
| `total_tax`     | Number | ***Optional.*** The tax of the order.                                |
| `total_cost`    | Number | The total cost of the order, including sub-total, shipping, and tax. |

#### `message.adjustments` <a href="#adjustments" id="adjustments"></a>

| Property | Type   | Description                                                               |
| -------- | ------ | ------------------------------------------------------------------------- |
| `name`   | String | Required if the `adjustments` array is set. Name of the adjustment.       |
| `amount` | Number | Required if the `adjustments` array is set. The amount of the adjustment. |

#### `message.elements` <a href="#elements" id="elements"></a>

| Property    | Type   | Description                                                                  |
| ----------- | ------ | ---------------------------------------------------------------------------- |
| `title`     | String | The name to display for the item.                                            |
| `subtitle`  | String | ***Optional.*** The subtitle for the item, usually a brief item description. |
| `quantity`  | Number | ***Optional.*** The quantity of the item purchased.                          |
| `price`     | Number | The price of the item. For free items, '0' is allowed.                       |
| `currency`  | String | ***Optional.*** The currency of the item price.                              |
| `image_url` | String | ***Optional.*** The URL of an image to be displayed with the item.           |

![](https://536261050-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LbSzTk1SGLwJ3VFu1kJ%2F-Lk8DfV0hnk0tacZPFBa%2F-Lk8IAR2g1dTmwZnE_WU%2Fimage.png?alt=media\&token=2a9ce000-04a0-4bc6-a1df-1b8f7e467864)

## 消息标签

> 借助消息标签，您可以在需要持续发送通知或最新消息的一些有限情况下，不受 24 小时时间窗的限制向用户发送消息。这样一来，您的智能助手就可以更灵活地与用户互动，您也可以在 Messenger 平台为用户打造更丰富的体验。
>
> **允许的用途 — 无推广内容**
>
> 请注意，消息标签仅用于发送非推广内容。
>
> 使用消息标签发送推广内容（例如，每日特惠、优惠券、折扣或促销公告）是违反 Messenger 平台政策的行为。

{% embed url="<https://developers.facebook.com/docs/messenger-platform/send-messages/message-tags>" %}

| 标签                             | 允许的用途                                                                                     | 示例                                                                                                                             |
| ------------------------------ | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `BUSINESS_PRODUCTIVITY`        | 发送非推广消息来帮助用户管理业务或相关活动的效率。                                                                 | <ul><li>关于公司已从服务提供商处订阅或购买的产品或服务的通知</li><li>针对即将支付的结算单或即将开始的服务维护发出的提醒或通知</li><li>有关公司表现、指标或推荐操作的报告</li></ul>                    |
| `COMMUNITY_ALERT`              | 向消息接收人通知紧急事件或公用设施问题，或在您的社群内询问平安状况。                                                        | <ul><li>询问平安状况</li><li>通知紧急事件或公用设施问题</li></ul>                                                                                 |
| `CONFIRMED_EVENT_REMINDER`     | 向消息接收人发送参加排期活动的提醒消息。                                                                      | <ul><li>用户注册参加的近期课程或活动</li><li>参加已接受邀请的活动或预约服务的确认消息</li></ul>                                                                  |
| `NON_PROMOTIONAL_SUBSCRIPTION` | 发送 Messenger 平台订阅消息政策中规定的几个类别的非推广消息：新闻资讯、工作效率和个人追踪。您可在主页的“设置”>“Messenger 平台”版块申请此标签的使用权限。 | 查看[开放平台政策概览的“订阅消息功能”部分](https://developers.facebook.com/docs/messenger-platform/policy/policy-overview#subscription_messaging) |
| `PAIRING_UPDATE`               | 通知消息接收人，已根据之前的请求找到匹配项。                                                                    | <ul><li>约会应用中找到了匹配的对象</li><li>停车位可用</li></ul>                                                                                  |
| `APPLICATION_UPDATE`           | 通知消息接收人其申请状态的更新。                                                                          | <ul><li>申请正在接受审核</li><li>申请已获得批准</li><li>求职申请状态</li></ul>                                                                      |
| `ACCOUNT_UPDATE`               | 通知消息接收人其帐户设置的更改。                                                                          | <ul><li>个人主页已更改</li><li>首选项已更新</li><li>设置已更改</li><li>会员身份已过期</li><li>密码已更改</li></ul>                                           |
| `PAYMENT_UPDATE`               | 通知消息接收人现有交易的支付状态更新。                                                                       | <ul><li>发送收据</li><li>发送缺货通知</li><li>通知拍卖已结束</li><li>支付交易的状态已更改</li></ul>                                                       |
| `PERSONAL_FINANCE_UPDATE`      | 确认消息接收人的财务活动。                                                                             | <ul><li>账单支付提醒</li><li>排期支付提醒</li><li>支付收据通知</li><li>资金转账确认或更新</li><li>其他金融服务类交易活动</li></ul>                                   |
| `SHIPPING_UPDATE`              | 通知消息接收人某件已购买商品的配送状态更改。                                                                    | <ul><li>商品已发货</li><li>状态更改为在途</li><li>商品已送达</li><li>配送延迟</li></ul>                                                             |
| `RESERVATION_UPDATE`           | 通知消息接收人现有预订的更新。                                                                           | <ul><li>行程更改</li><li>地点更改</li><li>取消已确认</li><li>酒店预订已取消</li><li>租车接人时间更改</li><li>房型升级已确认</li></ul>                             |
| `ISSUE_RESOLUTION`             | 通知消息接收人在 Messenger 对话中发起的客户服务问题有何更新。                                                      | <ul><li>问题已解决</li><li>问题状态已更新</li><li>该问题需要提供其他信息</li><li>跟进客户查询或支持工单</li></ul>                                                |
| `APPOINTMENT_UPDATE`           | 通知消息接收人现有预约的更改。                                                                           | <ul><li>预约时间更改</li><li>预约地点更改</li><li>预约已取消</li></ul>                                                                          |
| `GAME_EVENT`                   | 通知消息接收人，游戏内用户进度、全局活动或直播体育赛事的更改。                                                           | <ul><li>玩家的游戏内作物已可收割</li><li>玩家的每日比赛即将开始</li><li>用户最喜欢的足球队即将开踢</li></ul>                                                       |
| `TRANSPORTATION_UPDATE`        | 通知消息接收人现有交通运输服务预订的更新。                                                                     | <ul><li>航班状态更改</li><li>便车已取消</li><li>行程已开始</li><li>渡轮已抵达</li></ul>                                                             |
| `FEATURE_FUNCTIONALITY_UPDATE` | 通知消息接收人，智能助手推出了新特性或新功能。                                                                   | <ul><li>智能助手中添加了与在线客服聊天的功能</li><li>智能助手添加了新技能</li></ul>                                                                        |
| `TICKET_UPDATE`                | 向消息接收人发送已购票活动的更新或提醒。                                                                      | <ul><li>音乐会开始时间更改</li><li>活动地点更改</li><li>演出已取消</li><li>可以申请退款</li></ul>                                                        |