发送模板消息

Last updated 6 months ago

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

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

此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_typeMESSAGE_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)