发送消息API
快捷发送定制化的消息
利用bothub,您可以便捷的推送Messenger消息或者应答。但有时您可能有一些更灵活的需求,比如在消息中包含用户的一些过往订单的信息,或者是姓名等信息,抑或是在过往和用户的沟通中获取了用户的手机号,但此用户并没有在Messenger上和您的fans page沟通过,现在需要此用户推送消息等等。
为此我们推出发送消息API,为用户提供这些灵活性。
请求属性 | 属性名 | 说明 |
地址 | | |
请求方式 | POST | |
Header | APIKEY | 您的API KEY |
Header | Content-Type | application/json |
Form Data | request.method | 需要调用的api。此处设置为send_message |
Form Data | request.id | 用来唯一标识此发送请求的id。由调用方生成 |
Form Data | request.sync | 为true或false。若为true,Bothub会等待发送完所有消息后再返回请求。若为false,则会立即返回,等到发送完消息后再发一个请求给api调用方 |
Form Data | request.recipient | 要发送消息的用户信息,只能指定一个用户 |
Form Data | message | 要发送的消息。形式会在下方详述。 |
Form Data | request.meta | 预留字段 |
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": {
"phone_number": "18900001111",
"name": {
"first_name": "Michael",
"last_name": "Smith"
}, // name为可选字段
"country": {
"phone_code: "86"
}
},
"message": {
"text": "This is a sample message"
},
"request": {
"method": "send_message",
"id" : "F4js0Za1",
"sync": true,
"meta": ""
} ,
"messaging_type": "MESSAGE_TAG",
"message_tag": "NON_PROMOTIONAL_SUBSCRIPTION"
}
返回值 | 内容 |
request_id | 调用者在请求中设置的同名字段 |
recipient_id | 若调用成功,返回用户的Facebook账号 |
error.code | 错误码 |
error.message | 错误信息 |
error.error_subcode | 子错误码 |
请注意 使用phone_number方式进行调用,返回的recipient_id不是立刻生效的,而是要等到用户回复了这条消息(或者点击了和Page开始对话)才可以。目前对于phone_number方式指定的用户,若需要发后续消息, 请暂时还是使用phone_number方式指定。
- 成功返回值样例
{
"request_id": "F4js0Za1",
"recipient_id" : "100000111"
}
- 失败返回值样例
{
"error" : {
"message": "Phone Number not matching",
"type": "RuntimeException",
"code": 10000,
"error_subcode": 1234567,
"request_id": "F4js0Za1"
}
}
注意点
- 如果指定的用户是手机号,并且发送成功了,那么会返回用户信息,包含用户id,姓名。
- 如果选择的是异步方式,那么返回值会作为参数发送到商户指定的回调地址处。
返回值 | 内容 |
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 | 未定义交易通知地址 |
20004 | Message字段结构错误 |
- 如果选择的是异步方式,那么返回值会作为参数发送到商户指定的回调地址处。
- 示例
传进facebook user id的情形
"recipient" : {
"id": "70162731"
}
对已经绑定过的账号,传进用户名的情形
"recipient" : {
"username": "70162731"
}
对已经绑定过的账号,传进电话号码的情形。
"recipient" : {
"user_phone_number": "18900001111"
}
对于已绑定的账号,请保持账号和之前账号绑定时给定的值完全一致.
- 若通过手机号指定,必须带上加号和区号。
目前Bothub支持的消息格式包括文本消息,橱窗消息,订单回执。
- 文本消息
文本信息是一条独立的文字信息。表现形式如下:

消息格式如下(直接作为请求中Form Data的值即可):
{
"text":"Welcome to Bothub. We provide Facebook messenger services to help users interested in shopping inside messengers."
}
- 橱窗信息
橱窗信息是一组说明文字,图片和选项的集合,并且可以一次性发送多个橱窗。表现形式如:

消息格式如下(带//的字样为说明部分,实际使用中请去掉)
{
"attachment":{
"type":"template",
"payload":{
"template_type":"generic", // 必须为该值
"elements":[
{
"title":"嘿,你終於來了,實在是太棒了!", //橱窗卡片的主标题
"image_url":"https://www.bothub.ai/company_logo.png", //橱窗卡片的图片地址
"subtitle":"你好,我是小Bo為你服務。我們是一個可以把Messenger升級為你的粉絲專業智能助手的軟件", //橱窗卡片的副标题
"default_action":{
"type":"weburl", // 表示点击之后跳转到一个链接
"url":"https://www.bothub.ai", //按钮点击后跳转的链接
},
"buttons":[
{
"type":"web_url", //第一个按钮的类型
"url":"https://bothub.ai", //第一个按钮的地址
"title":"什麼是Bothub" // 第一个按钮的文字说明
},
{
"type":"web_url", //第二个按钮的类型
"url":"https://bothub.ai/readme", //第二个按钮的地址
"title":"Bothub如何工作" // 第二个按钮的文字说明
},
{
"type":"web_url", //第三个按钮的类型
"url":"https://bothub.ai/open", //第三个按钮的地址
"title":"完全開放" // 第三个按钮的文字说明
}
]
}
]
}
}
}
- 订单回执
订单回执是用户在Messenger上付款之后的回执。提供了用戶付款的信息和購買的商品信息。

消息格式如下(带//的字样为说明部分,实际使用中请去掉)
{
"attachment"::{
"type":"template",
"payload":{
"template_type":"receipt", // 必须为该值
"recipient_name":"Stephane Crozatier", // 购买者姓名
"order_number":"12345678902", // 商户系统中该订单的订单号
"currency":"TWD", // 订单货币
"payment_method":"Visa 2345", // 付款方式,此字段在Bothub提供的付款通知中会给出
"order_url":"http://www.bothub.ai/order?order_id=123456", //订单链接
"timestamp":"1428444852", //时间戳
"elements":{
{
"title":"Classic White T-Shirt",
"subtitle":"100% Soft and Luxurious Cotton",
"quantity":2,
"price":50,
"currency":"TWD",
"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":"TWD", // 货币
"image_url":"http://petersapparel.parseapp.com/img/grayshirt.png" // 商品图片链接
}
},
"address":{
"street_1":"1 Hacker Way", // 收货地址
"street_2":"",
"city":"台北", // 收货城市
"postal_code":"", // 收货邮编
"state":"TW", // 收货的省/州
"country":"TW" // 收货国家
},
"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
}
}
}
}
- 通过按钮链接到别的内容 有时,我们希望展现给用户一些消息的集合,用户可以通过点击按钮查看更详细的信息。如下图 当用户点击了“完全开放”后,系统自动返回另一个卡片。

消息格式如下(带//的字样为说明部分,实际使用中请去掉)
{
"attachment":{
"type":"template",
"payload":{
"template_type":"generic", // 必须为该值
"elements":[
{
"title":"嘿,你終於來了,實在是太棒了!", //橱窗卡片的主标题
"image_url":"https://www.bothub.ai/company_logo.png", //橱窗卡片的图片地址
"subtitle":"你好,我是小Bo為你服務。我們是一個可以把Messenger升級為你的粉絲專業智能助手的軟件", //橱窗卡片的副标题
"buttons":[
{
"type":"block", //按钮类型 - 显示其他块
"block_name":"view_details", //需要显示的其他块的名字
"title":"完全開放" // 按钮的文字说明
}
]
}
]
}
}
}
- 块的名字(上面代码中block_name属性需要使用bothub.ai后台中存在的块内容的名字,如下图上方黑色的“view_details”。注意空格和大小写需要完全一致。
- 特殊的内容,包括欢迎设置,问候消息,系统菜单,默认回答不能在这里被引用

有时,我们希望在消息中包含用户的个人信息。例如:我们希望名叫Mike Smith的用户收到如下文本信息: Hello Mike Smith, here is your order receipt. 此时可以以模板来指代用户的个人信息。例如上面那条信息可以写为: Hello , here is your order receipt.
- : 用户的名(first name)
- : 用户的姓 (last name)
- : 用户的facebook user id
- : 用户的位置信息(形式如en-US, zh-CN)
- : 用户性别(male/female)
Last modified 3yr ago