发送模板消息

模版消息：让您轻松定制消息，修改更便利。

发送模板消息，使用自助定义的变量

此API提供了发送Bothub后台中预定义的消息模板，但是对每个用户可以以自定义变量替换消息中占位符，以达到定制化的效果。 例如，我们在Bothub后台定义如下文本消息: "您的目前积分为" 而我们在发送信息时可以为每个用户指定参数为他的实际积分数。这样我们就实现了发送用户积分数量的功能。如果我们希望更改文字，或是使用除纯文字之外的模板，直接在Bothub后台修改模板即可，完全不需要任何代码级的修改。

发送请求

您可以用任意一个已经启用的API Key(怎样申请APIKey) 向Bothub发起请求，向一个手机号或一个官网账号发送一条消息。这个请求的说明如下：

请求属性	属性名	说明
地址		https://api.bothub.ai/api
请求方式	POST
Header	APIKEY	您的API KEY
Form Data	request.method	需要调用的api。此处设置为send_block
Form Data	request.id	用来唯一标识此发送请求的id。由调用方生成
Form Data	request.sync	为true或false。若为true，Bothub会等待发送完所有消息后再返回请求。若为false，则会立即返回，等到发送完消息后再发一个请求给api调用方
Form Data	request.meta	预留字段
Form Data	recipient	要发送消息的用户信息，只能指定一个用户
Form Data	message	要发送的消息。形式会在下方详述。
Form Data	params	要替换的参数。形式会在下方详述。
Form Data	messaging_type	消息类别，枚举值包括RESPONSE UPDATEMESSAGE_TAG, 根据facebook政策，2018.5.7之后必须带messaging_type才能发送消息，详见https://developers.facebook.com/docs/messenger-platform/send-messages
Form Data	message_tag	消息标签, 枚举值包括COMMUNITY_ALERTCONFIRMED_EVENT_REMINDERNON_PROMOTIONAL_SUBSCRIPTION PAIRING_UPDATEAPPLICATION_UPDATE ACCOUNT_UPDATEPAYMENT_UPDATE PERSONAL_FINANCE_UPDATESHIPPING_UPDATE RESERVATION_UPDATEISSUE_RESOLUTION APPOINTMENT_UPDATE GAME_EVENTTRANSPORTATION_UPDATEFEATURE_FUNCTIONALITY_UPDATE TICKET_UPDATE, 当messaging_type为MESSAGE_TAG时必填， 标记消息使用场景， 详见https://developers.facebook.com/docs/messenger-platform/send-messages/message-tags

请求样例

{
    "recipient": {
        "id": "7819201"
    },
    "message": {
        "block_name": "points_info",
        "params": [
            {
                "key": "points",
                "value": "20000"
            },
            {
                "key": "prize",
                "value": "Gold Medal"
            }
        ]
    },
    "request": {
        "method": "send_block",
        "id" : "F4js0Za1",
        "sync": true,
        "meta": ""
    },
    "messaging_type": "MESSAGE_TAG",
    "message_tag": "NON_PROMOTIONAL_SUBSCRIPTION"
}

同步方式请求返回值以及异步式调用回调内容

请详见请求返回值

错误码列表

返回值	内容
10000	内部错误
10001	未指定API KEY
10002	无效的API KEY
10003	未指定Request id
10004	未指定调用API的种类
10005	无效的API种类
10005	无效的API种类
10006	Bot不存在或者已经被删除
10007	未指定recipient字段
10008	recipient结构不正确
10009	无效的用户指定方式
10010	用户不存在
10011	Request id与之前的重复
10100	参数无效
18000	内部错误
19000	回调超时
20001	未定义Message字段
20002	未定义交易通知地址
20003	无法将手机号匹配为Messenger用户
20004	Message字段结构错误

• 如果指定的用户是手机号，并且发送成功了，那么会返回用户信息，包含用户id，姓名。以后指定该用户就可以使用id。

• 如果选择的是异步方式，那么返回值会作为参数发送到商户指定的回调地址处。

用户指定

请参见 用户指定

消息格式

样例格式如下

"message": {
    "block_name": "points_info",
}

block_name为必填，为本API中发送的消息。其值为商户在bothub后台中创建的block的名字

如上图中的“points_info"

参数指定

params是message的属性之一，用于指定模板参数用什么值加以替换。 样例格式如下:

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

例如，这条消息发送时，points_info这个block中的所有卡片的文本，只要含有模板，就会被替换为20000，则会被替换为Gold Medal.

• 对于文本消息而言，文字中的模板会被替换

• 对于菜单，橱窗等消息而言，title，subtitle，按钮的title中若含有模板，都会被替换。

• 当此API种设置的参数和设置参数API设置过的参数同名时，以此API指定的参数为准。但此API种定义的参数并不会作为用户的参数被保存下来。因此本API的参数适合被定义为一次性使用的参数。

模板编写

模板编写方式为

• template_name由大小写字母，数字和下划线组成。不含其它字符和空格。

• template_name不能为first_name和last_name.这两个是用于用户姓名的替换。

• template_name区分大小写。此api仅当template和params的key属性完全相等时，才会以params的value属性替换模板。

用户姓名

有时，我们希望在消息中包含用户的个人姓名。例如：我们希望名叫Mike Smith的用户收到如下文本信息： Hello Mike Smith, here is your order receipt. 此时可以以模板来指代用户的个人信息。例如上面那条信息可以写为： Hello , here is your order receipt.

• 将被转化为用户的名（first name)

• 将被转化为用户的姓 (last name)