---
description: 快捷发送定制化的消息
---

# 发送消息API

## 发送消息API，快捷发送定制化的消息 <a href="#fa-song-xiao-xi-api-kuai-jie-fa-song-ding-zhi-hua-de-xiao-xi" id="fa-song-xiao-xi-api-kuai-jie-fa-song-ding-zhi-hua-de-xiao-xi"></a>

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

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

#### 发送请求 <a href="#fa-song-qing-qiu" id="fa-song-qing-qiu"></a>

您可以用任意一个已经启用的API Key([怎样申请APIKey](https://bothubdocs.gitbook.io/project/~/edit/drafts/-LCWfeDNA9QGt2vCxD8D/untitled-2/api-jie-shao/kai-shi-shi-yong-api)) 向Bothub发起请求，向一个手机号或一个官网账号发送一条消息。这个请求的说明如下：

| 请求属性      | 属性名               | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| --------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 地址        |                   | [https://api.bothub.ai/api](https://api.bothub.ai/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](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](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"
}
```

#### 同步方式请求返回值以及异步式调用回调内容 <a href="#tong-bu-fang-shi-qing-qiu-fan-hui-zhi-yi-ji-yi-bu-shi-tiao-yong-hui-tiao-nei-rong" id="tong-bu-fang-shi-qing-qiu-fan-hui-zhi-yi-ji-yi-bu-shi-tiao-yong-hui-tiao-nei-rong"></a>

| 返回值                  | 内容                     |
| -------------------- | ---------------------- |
| 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，姓名。
* 如果选择的是异步方式，那么返回值会作为参数发送到商户指定的回调地址处。

#### 错误码列表 <a href="#cuo-wu-ma-lie-biao" id="cuo-wu-ma-lie-biao"></a>

| 返回值   | 内容                   |
| ----- | -------------------- |
| 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支持的消息格式包括文本消息，橱窗消息，订单回执。

* 文本消息

文本信息是一条独立的文字信息。表现形式如下：\


![](https://1455238913-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LBxiFMKIFEMsz8J7IuU%2F-LCWgJ0INpg0iMxJtf3b%2F-LCWrhjng2D8MiZhceMo%2Fp3f3p501.png?alt=media\&token=7e14b9e8-0edf-4ccf-b238-b7ec74d63509)

消息格式如下(直接作为请求中Form Data的值即可)：

```
{  
  "text":"Welcome to Bothub. We provide Facebook messenger services to help users interested in shopping inside messengers."
}
```

* 橱窗信息

橱窗信息是一组说明文字，图片和选项的集合，并且可以一次性发送多个橱窗。表现形式如：\


![](https://1455238913-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LBxiFMKIFEMsz8J7IuU%2F-LCWgJ0INpg0iMxJtf3b%2F-LCWrkym9dgT_zFfBPw9%2Fp3f3p502.png?alt=media\&token=cedf0770-7469-41ff-bae5-d30f6c2577ea)

消息格式如下（带//的字样为说明部分，实际使用中请去掉）

```
{
  "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上付款之后的回执。提供了用戶付款的信息和購買的商品信息。&#x20;

![](https://1455238913-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LBxiFMKIFEMsz8J7IuU%2F-LCWgJ0INpg0iMxJtf3b%2F-LCWroCheJ1PBYEaACHh%2Fp3f3p503.png?alt=media\&token=8b9e15b6-f2ff-4ff4-bcf6-81b72749b589)

消息格式如下（带//的字样为说明部分，实际使用中请去掉）

```
{
  "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
        }
      }
    }
  }
```

* 通过按钮链接到别的内容 有时，我们希望展现给用户一些消息的集合，用户可以通过点击按钮查看更详细的信息。如下图 当用户点击了“完全开放”后，系统自动返回另一个卡片。

![](https://1455238913-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LBxiFMKIFEMsz8J7IuU%2F-LCWgJ0INpg0iMxJtf3b%2F-LCWrrV7pNbw8kKpXILA%2Fp3f3p504.png?alt=media\&token=96dfc660-3530-4f1a-a491-390d563e0466)

消息格式如下（带//的字样为说明部分，实际使用中请去掉）

```
{
  "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”。注意空格和大小写需要完全一致。&#x20;
* 特殊的内容，包括欢迎设置，问候消息，系统菜单，默认回答不能在这里被引用

![](https://1455238913-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LBxiFMKIFEMsz8J7IuU%2F-LCWgJ0INpg0iMxJtf3b%2F-LCWrwuvfHxka3bxwkl2%2Fp3f3p505.png?alt=media\&token=457be973-8ff1-4b79-b41f-dbf95f0bdd93)

### 用户个人信息

有时，我们希望在消息中包含用户的个人信息。例如：我们希望名叫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)

**请注意！！** 请勿在使用电话号码进行发送时使用用户姓名！因为仅凭手机号，我们是不知道用户的任何信息的。当用户回复了使用手机号发送的消息后（即使点击了开始对话就可以)，用户姓名的宏才会生效。
