发送消息API

发送消息API，快捷发送定制化的消息

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

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

发送请求

您可以用任意一个已经启用的API Key(怎样申请APIKey) 向Bothub发起请求，向一个手机号或一个官网账号发送一条消息。这个请求的说明如下：

请求样例

{
    "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方式指定。

• 成功返回值样例

{
    "request_id": "F4js0Za1",
    "recipient_id" : "100000111"
}

• 失败返回值样例

{
    "error" : {
        "message": "Phone Number not matching",
        "type": "RuntimeException",
        "code": 10000,
        "error_subcode": 1234567,
        "request_id": "F4js0Za1"
    }
}

注意点

• 如果指定的用户是手机号，并且发送成功了，那么会返回用户信息，包含用户id，姓名。
• 如果选择的是异步方式，那么返回值会作为参数发送到商户指定的回调地址处。

错误码列表

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

用户指定

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

• 示例

传进facebook user id的情形
"recipient" : {
    "id": "70162731"    
}

对已经绑定过的账号，传进用户名的情形
"recipient" : {
    "username": "70162731"    
}

对已经绑定过的账号，传进邮箱的情形
"recipient" : {
    "email": "mike@example.com"    
}

对已经绑定过的账号，传进电话号码的情形。
"recipient" : {
    "user_phone_number": "18900001111"     
}

对于已绑定的账号，请保持账号和之前账号绑定时给定的值完全一致.

消息格式

目前Bothub支持的消息格式包括文本消息，橱窗消息，订单回执。

• 文本消息

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

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

{  
  "text":"Welcome to Bothub. 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.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上付款之后的回执。提供了用戶付款的信息和購買的商品信息。

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

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

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

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

{
  "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.

• : 用户的名（first name)
• : 用户的姓 (last name)
• : 用户的facebook user id
• : 用户的位置信息(形式如en-US, zh-CN)
• : 用户性别(male/female)