# 发送模板消息 ## 发送模板消息，使用自助定义的变量 此API提供了发送Bothub后台中预定义的消息模板，但是对每个用户可以以自定义变量替换消息中占位符，以达到定制化的效果。 例如，我们在Bothub后台定义如下文本消息: "您的目前积分为" 而我们在发送信息时可以为每个用户指定参数为他的实际积分数。这样我们就实现了发送用户积分数量的功能。如果我们希望更改文字，或是使用除纯文字之外的模板，直接在Bothub后台修改模板即可，完全不需要任何代码级的修改。 ### 发送请求 您可以用任意一个已经启用的API Key([怎样申请APIKey](https://bothubdocs.gitbook.io/project/~/edit/drafts/-LCWfeDNA9QGt2vCxD8D/untitled-2/api-jie-shao/kai-shi-shi-yong-api)) 向Bothub发起请求，向一个手机号或一个官网账号发送一条消息。这个请求的说明如下： | 请求属性 | 属性名 | 说明 | | --------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 地址 | | | | 请求方式 | 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`才能发送消息，详见 | | 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`时必填， 标记消息使用场景， 详见 | ### **请求样例** ``` { "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的名字 ![](https://3545383198-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LBxiFMKIFEMsz8J7IuU%2F-LCWsZYrv8U7bETGyjzP%2F-LCWtDJD8zfO_S97bW7f%2Fp3f3p601.png?alt=media\&token=0fc92f11-3aa4-461d-a19c-00991cd7f3c3) 如上图中的“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种设置的参数和[设置参数AP](https://bothubdocs.gitbook.io/project/~/edit/drafts/-LCWfeDNA9QGt2vCxD8D/untitled-2/api-jie-shao/can-shu-she-zhi-api)I设置过的参数同名时，以此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)