发送消息API
快捷发送定制化的消息
利用Meetbot，您可以便捷的推送Messenger消息或者应答。但有时您可能有一些更灵活的需求，比如在消息中包含用户的一些过往订单的信息，或者是姓名等信息，抑或是在过往和用户的沟通中获取了用户的手机号，但此用户并没有在Messenger上和您的fans page沟通过，现在需要此用户推送消息等等。
为此我们推出发送消息API， 为用户提供这些灵活性。
您可以用任意一个已经启用的API Key向Meetbot发起请求，向一个手机号或一个官网账号发送一条消息。这个请求的说明如下：
请求属性 | 属性名 | 说明 |
地址 | | |
请求方式 | 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，Meetbot会等待发送完所有消息后再返回请求。若为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 | 消息标签，枚举值包括 POST_PURCHASE_UPDATE CONFIRMED_EVENT_UPDATE ACCOUNT_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"
},
"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":"POST_PURCHASE_UPDATE"
}
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字段结构错误 |
- 如果选择的是异步方式，那么返回值会作为参数发送到商户指定的回调地址处。
- 示例
- 1.传进facebook user id 的情形。
"recipient" : {
"id":"70162731"
}
2. 对已经绑定过账号，传进用户名的情形。
"recipient" : {
"username":"70162731"
}
3. 对已经绑定过的账号，传进邮箱的情形。
4. 对已经绑定过的账号，传进电话号码的情形。
"recipient" : {
"user_phone_number":"18900001111"
}
对于已绑定的账号，请保持账号和之前账号绑定时给定的值完全一致.
- 若通过手机号指定，必须带上加号和区号。
目前Meetbot支持的消息格式包括文本消息，橱窗消息，订单回执。
- 文本消息
文本信息是一条独立的文字信息。表现形式如下：
消息格式如下(直接作为请求中Form Data的值即可)：
{
"text":"Welcome to Meetbot. 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.meetbot.biz/company_logo.png",//橱窗卡片的图片地址
"subtitle":"你好，我是小Bo為你服務。我們是一個可以把Messenger升級為你的粉絲專業智能助手的軟件", //橱窗卡片的副标题
"default_action":{
"type":"weburl", //表示点击之后跳转到一个链接
"url":"https://www.meetbot.biz" //按钮点击后跳转的链接
},
"buttons":[
{
"type":"web_url", //第一个按钮的类型
"url":"https://meetbot.biz", //第一个按钮的地址
"title":"什麼是Meetbot" //第一个按钮的文字说明
},
{
"type":"web_url", //第二个按钮的类型
"url":"https://meetbot.biz/readme",//第二个按钮的地址
"title":"Meetbot如何工作" //第二个按钮的文字说明
},
{
"type":"web_url", //第三个按钮的类型
"url":"https://meetbot.biz/open", //第三个按钮的地址
"title":"完全開放" //第三个按钮的文字说明
}
]
}
]
}
}
}
- 订单回执
订单回执是用户在Messenger上付款之后的回执。提供了用戶付款的信息和購買的商品信息。
消息格式如下（带//的字样为说明部分，实际使用中请去掉）
{
"attachment":{
"type":"template",
"payload":{
"template_type":"receipt", // 必须为该值
"recipient_name":"Stephane Crozatier",// 购买者姓名
"order_number":"12345678902", // 商户系统中该订单的订单号
"currency":"TWD", // 订单货币
"payment_method":"Visa 2345", // 付款方式，此字段在提供的付款通知中会给出
"order_url":"http://www.meetbot.biz/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, // 商品总金额（不含税费，运费）
"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.meetbot.biz/company_logo.png",//橱窗卡片的图片地址
"subtitle":"你好，我是小Bo為你服務。我們是一個可以把Messenger升級為你的粉絲專業智能助手的軟件",//橱窗卡片的副标题
"buttons":[
{
"type":"block", // 按钮类型 - 显示其他块
"block_name":"view_details", // 需要显示的其他块的名字
"title":"完全開放" // 按钮的文字说明
}
]
}
]
}
}
}
- 块的名字（上面代码中block_name属性需要使用Meetbot后台中存在的自定义内容块的名字，如下图的“view_details”。注意空格和大小写需要完全一致。
有时，我们希望在消息中包含用户的个人信息。例如：我们希望名叫Mike Smith的用户收到如下文本信息： Hello Mike Smith, here is your order receipt. 此时可以以模板来指代用户的个人信息。例如上面那条信息可以写为： Hello {{first_name}} {{last_name}}, here is your order receipt.
- : 用户的名（first_name)
- : 用户的姓（last_name）
- : 用户的（facebook_user_id）
- : 用户的位置信息（形式如en-US, zh-CN）
- : 用户性别（male/female）
Last modified 1yr ago