发送消息API,快捷发送定制化的消息
利用bothub,您可以便捷的推送Messenger消息或者应答。但有时您可能有一些更灵活的需求,比如在消息中包含用户的一些过往订单的信息,或者是姓名等信息,抑或是在过往和用户的沟通中获取了用户的手机号,但此用户并没有在Messenger上和您的fans page沟通过,现在需要此用户推送消息等等。
为此我们推出发送消息API,为用户提供这些灵活性。
发送请求
您可以用任意一个已经启用的API Key(怎样申请APIKey ) 向Bothub发起请求,向一个手机号或一个官网账号发送一条消息。这个请求的说明如下:
需要调用的api。此处设置为send_message
为true或false。若为true,Bothub会等待发送完所有消息后再返回请求。若为false,则会立即返回,等到发送完消息后再发一个请求给api调用方
消息标签, 枚举值包括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
请求样例
Copy {
"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"
}
同步方式请求返回值以及异步式调用回调内容
请注意 使用phone_number方式进行调用,返回的recipient_id不是立刻生效的,而是要等到用户回复了这条消息(或者点击了和Page开始对话)才可以。目前对于phone_number方式指定的用户,若需要发后续消息,请暂时还是使用phone_number方式指定。
Copy {
"request_id": "F4js0Za1",
"recipient_id" : "100000111"
}
Copy {
"error" : {
"message": "Phone Number not matching",
"type": "RuntimeException",
"code": 10000,
"error_subcode": 1234567,
"request_id": "F4js0Za1"
}
}
注意点
如果指定的用户是手机号,并且发送成功了,那么会返回用户信息,包含用户id,姓名。
如果选择的是异步方式,那么返回值会作为参数发送到商户指定的回调地址处。
错误码列表
如果选择的是异步方式,那么返回值会作为参数发送到商户指定的回调地址处。
用户指定
在一个请求中可以指定1个用户。如果是已经做过账号绑定的账号(在Messenger内登录 或者 通过接口关联) , user 为一个json对象,示例如下
Copy 传进facebook user id的情形
"recipient" : {
"id": "70162731"
}
Copy 对已经绑定过的账号,传进用户名的情形
"recipient" : {
"username": "70162731"
}
Copy 对已经绑定过的账号,传进邮箱的情形
"recipient" : {
"email": "mike@example.com"
}
Copy 对已经绑定过的账号,传进电话号码的情形。
"recipient" : {
"user_phone_number": "18900001111"
}
对于已绑定的账号,请保持账号和之前账号绑定时给定的值完全一致.
消息格式
目前Bothub支持的消息格式包括文本消息,橱窗消息,订单回执。
文本信息是一条独立的文字信息。表现形式如下:
消息格式如下(直接作为请求中Form Data的值即可):
Copy {
"text":"Welcome to Bothub. We provide Facebook messenger services to help users interested in shopping inside messengers."
}
橱窗信息是一组说明文字,图片和选项的集合,并且可以一次性发送多个橱窗。表现形式如:
消息格式如下(带//的字样为说明部分,实际使用中请去掉)
Copy {
"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上付款之后的回执。提供了用戶付款的信息和購買的商品信息。
消息格式如下(带//的字样为说明部分,实际使用中请去掉)
Copy {
"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
}
}
}
}
通过按钮链接到别的内容 有时,我们希望展现给用户一些消息的集合,用户可以通过点击按钮查看更详细的信息。如下图 当用户点击了“完全开放”后,系统自动返回另一个卡片。
消息格式如下(带//的字样为说明部分,实际使用中请去掉)
Copy {
"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.
: 用户的位置信息(形式如en-US, zh-CN)