Messenger发送消息API

快捷发送定制化的消息

利用Meetbot，您可以便捷的推送Messenger消息或者应答。但有时您可能有一些更灵活的需求，比如在消息中包含用户的一些过往订单的信息，或者是姓名等信息，抑或是在过往和用户的沟通中获取了用户的手机号，但此用户并没有在Messenger上和您的fans page沟通过，现在需要此用户推送消息等等。

为此我们推出发送消息API，为用户提供这些灵活性。

您可以用任意一个已经启用的API Key向Meetbot发起请求，向一个手机号或一个官网账号发送一条消息。

这个请求的说明如下：

请求属性	属性名	说明
地址		https://api.meetbot.biz/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，Meetbot会等待发送完所有消息后再返回请求。若为false，则会立即返回，等到发送完消息后再发一个请求给api调用方
Form Data	request.recipient	要发送消息的用户信息，只能指定一个用户
Form Data	message	要发送的消息。形式会在下方详述。
Form Data	request.meta	预留字段
Form Data	messaging_type	消息类别，枚举值包括`RESPONSEUPDATEMESSAGE_TAG`, 根据facebook政策，2018.5.7之后必须带`messaging_type`才能发送消息，详见https://developers.facebook.com/docs/messenger-platform/send-messages
Form Data	message_tag	消息标签，枚举值包括`POST_PURCHASE_UPDATECONFIRMED_EVENT_UPDATEACCOUNT_UPDATE`, 当`messaging_type`为`MESSAGE_TAG`时必填，标记消息使用场景，详见https://developers.facebook.com/docs/messenger-platform/send-messages/message-tags

{
    "recipient":{
        "id":"70162731",
        "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 KEY10002无效的API KEY10003未指定Request id10004未指定调用API的种类10005无效的API种类10005无效的API种类10006Bot不存在或者已经被删除10007未指定recipient字段10008recipient结构不正确10009无效的用户指定方式10010用户不存在10011Request id与之前的重复10100参数无效18000内部错误19000回调超时20001未定义Message字段20002未定义交易通知地址20004Message字段结构错误

如果选择的是异步方式，那么返回值会作为参数发送到商户指定的回调地址处。

在一个请求中可以指定1个用户。如果是已经做过账号绑定的账号（在Messenger内登录或者通过接口关联)， user 为一个json对象，示例如下

示例

1.传进facebook user id 的情形

"recipient" : {
    "id":"70162731"
}

2. 对已经绑定过账号，传进用户名的情形

"recipient" : {
    "username":"70162731"
}

3.对已经绑定过的账号，传进邮箱的情形

"recipient" : {
    "email":"mike@example.com"
}

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":"200050",      // 收货邮编
                "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
用户的ID：facebook_user_id
用户的位置信息：形式如en-US, zh-CN
用户性别：male/female

2024-03-25

Messenger发送消息API

发送请求

请求样例

同步方式请求返回值以及异步式调用回调内容

错误码列表

用户指定

消息格式

用户个人信息

本页目录

若有疑问，请提交工单