> For the complete documentation index, see [llms.txt](https://bothub.gitbook.io/project/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bothub.gitbook.io/project/bothub.ai-2.0/untitled-2/api-jie-shao/untitled-1.md). # 发送消息API ## 发送消息API，快捷发送定制化的消息 利用bothub，您可以便捷的推送Messenger消息或者应答。但有时您可能有一些更灵活的需求，比如在消息中包含用户的一些过往订单的信息，或者是姓名等信息，抑或是在过往和用户的沟通中获取了用户的手机号，但此用户并没有在Messenger上和您的fans page沟通过，现在需要此用户推送消息等等。 为此我们推出发送消息API，为用户提供这些灵活性。 #### 发送请求 您可以用任意一个已经启用的API Key([怎样申请APIKey](https://bothubdocs.gitbook.io/project/~/edit/drafts/-LCWfeDNA9QGt2vCxD8D/untitled-2/api-jie-shao/kai-shi-shi-yong-api)) 向Bothub发起请求，向一个手机号或一个官网账号发送一条消息。这个请求的说明如下： | 请求属性 | 属性名 | 说明 | | --------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 地址 | | | | 请求方式 | 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`才能发送消息，详见 | | 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`时必填， 标记消息使用场景， 详见 | ### **请求样例** ``` { "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 | 未定义交易通知地址 | | 20003 | 无法将手机号匹配为Messenger用户 | | 20004 | Message字段结构错误 | * 如果指定的用户是手机号，并且发送成功了，那么会返回用户信息，包含用户id，姓名。以后指定该用户就可以使用id。 * 如果选择的是异步方式，那么返回值会作为参数发送到商户指定的回调地址处。 ### 用户指定 在一个请求中可以指定1个用户，用户可以手机号的方式指定。如果是已经做过账号绑定的账号（[在Messenger内登录](https://bothubdocs.gitbook.io/project/~/edit/drafts/-LCWfeDNA9QGt2vCxD8D/untitled-2/api-jie-shao/messenger-nei-de-deng-lu-an-niu-guan-lian-facebook-zhang-hao-he-nin-wang-zhan-de-zhang-hao) 或者 [通过接口关联](https://bothubdocs.gitbook.io/project/~/edit/drafts/-LCWfeDNA9QGt2vCxD8D/untitled-2/api-jie-shao/untitled))， user 为一个json对象，示例如下 * 示例 ``` 传进手机号的情形 recipient参数中的name是可选字段。如果传此参数并且信息准确的话，facebook匹配此手机号并发送消息成功的概率将大幅度提高。 "recipient" : { "phone_number": "13900001111", "name": { "first_name": "Michael", "last_name": "Smith" }, "country": { "code": "CN" } } 或 "recipient" : { "phone_number": "13900001111", "name": { "first_name": "Michael", "last_name": "Smith" }, "country": { "phone_code": "86" } } ``` 手机号支持的格式为:**不含区号**的**纯数字**电话号码，例如 * 18611112222 //中国号码 * 6267800000 //美国号码 country是指定的方式为code（2位ISO码，例如CN，US）和phone\_code(区号，纯数字不带加号，例如86，1等），两者择一即可 ``` 传进facebook user id的情形 "recipient" : { "id": "70162731" } ``` ``` 对已经绑定过的账号，传进用户名的情形 "recipient" : { "username": "70162731" } ``` ``` 对已经绑定过的账号，传进邮箱的情形 "recipient" : { "email": "mike@example.com" } ``` ``` 对已经绑定过的账号，传进电话号码的情形。 "recipient" : { "user_phone_number": "18900001111" } ``` 对于已绑定的账号，请保持账号和之前账号绑定时给定的值完全一致. {% hint style="info" %} * 若通过手机号指定，必须带上加号和区号。 {% endhint %} ### 消息格式 目前Bothub支持的消息格式包括文本消息，橱窗消息，订单回执。 * 文本消息 文本信息是一条独立的文字信息。表现形式如下：
![](/files/-LCWrhjng2D8MiZhceMo) 消息格式如下(直接作为请求中Form Data的值即可)： ``` { "text":"Welcome to Bothub. We provide Facebook messenger services to help users interested in shopping inside messengers." } ``` * 橱窗信息 橱窗信息是一组说明文字，图片和选项的集合，并且可以一次性发送多个橱窗。表现形式如：
![](/files/-LCWrkym9dgT_zFfBPw9) 消息格式如下（带//的字样为说明部分，实际使用中请去掉） ``` { "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上付款之后的回执。提供了用戶付款的信息和購買的商品信息。 ![](/files/-LCWroCheJ1PBYEaACHh) 消息格式如下（带//的字样为说明部分，实际使用中请去掉） ``` { "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 } } } } ``` * 通过按钮链接到别的内容 有时，我们希望展现给用户一些消息的集合，用户可以通过点击按钮查看更详细的信息。如下图 当用户点击了“完全开放”后，系统自动返回另一个卡片。 ![](/files/-LCWrrV7pNbw8kKpXILA) 消息格式如下（带//的字样为说明部分，实际使用中请去掉） ``` { "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”。注意空格和大小写需要完全一致。 * 特殊的内容，包括欢迎设置，问候消息，系统菜单，默认回答不能在这里被引用 ![](/files/-LCWrwuvfHxka3bxwkl2) ### 用户个人信息 有时，我们希望在消息中包含用户的个人信息。例如：我们希望名叫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) **请注意！！** 请勿在使用电话号码进行发送时使用用户姓名！因为仅凭手机号，我们是不知道用户的任何信息的。当用户回复了使用手机号发送的消息后（即使点击了开始对话就可以)，用户姓名的宏才会生效。