Bothub.AI 用户手册简体中文版
Primary version
Primary version
  • 概览
  • 介绍
    • 什么是 Messenger Bot 🤔
  • 快速入门
    • 5分钟创建一个机器人
  • BotHub 基础知识
    • Messenger 机器人的基本功能
    • 多用户管理功能
    • 数据分析
      • 内容分析
      • 流量来源
    • 内容管理
      • 内容结构介绍
      • 文本、图片和视频卡片
      • 菜单卡片及各类按钮
      • 橱窗卡片以及快捷回复
      • 列表卡片
      • 系统设置介绍
      • 标签化内容
      • 广告消息
    • 受众人群
      • 查看历史消息
      • 推送事件
    • 消息群发
      • 广播消息
      • 订阅消息
      • 多时区支持
      • 问卷调研
    • Handover Protocol
    • 人工智能
      • 对话管理
      • 识别优先级
  • BotHub高级工具
    • 高级插件
      • Messenger 网页插件
      • RSS Feed插件
      • 用户输入插件
      • Google搜索插件
      • 订阅管理插件
      • 订阅插件“加入受众”和“移出受众”
      • 商品选取插件
      • 商品搜索插件
      • 购物车展示插件
      • Json Api组件
      • 条件跳转插件
      • 属性设置插件
      • 随机回复插件
      • Typing插件
      • 计数器
      • 语境跳转插件
    • 数据集成
      • 知识库-自动获取Gitbook的文档数据
    • API介绍
      • 开始使用API
      • 关联账号
      • Messenger内的登录按钮
      • 交易信息通知
      • 发送消息API
      • 发送模板消息
      • 生成优惠券的接口的写法
      • 发送知识库条目
      • 参数设置API
      • 呼叫人工
      • whatsapp消息入口
      • 发送whatsapp消息
      • 发送liveChat请求
    • 推广
      • 推广工具
      • 广告管理
      • 再营销SDK的集成
      • 评论回复功能
      • 砍价免费拿
      • Messenger 广告
    • 电商机器人
      • 电商机器人功能介绍
      • 配置你的电商机器人
      • 顾客查询
      • 商家推送
      • 场景应用:顾客查询订单 & 包裹
      • 场景应用:推送订单回执
      • 场景应用:推送订单回执(旧版SDK)
      • 场景应用:包裹更新提醒
      • 场景应用:购物车召回配置
      • 场景应用:购物车召回配置(旧版SDK)
    • 商品管理
      • 商品Feed-Facebook商品数据集成
      • 自定义商品-手动创建活动商品
  • WhatsApp相关说明
    • whatsapp消息入口
    • 发送Whatsapp消息
    • 发送liveChat请求
  • FAQ常见问题
    • Bot 配置常见问题
    • Bot 操作流程问题
      • 如何授权新的FB Page 至Bot平台
      • 首次登录 messenger.bothub.ai 邮箱验证流程
      • 设置仅工作时间段人工客服有效
    • Facebook平台政策问题
      • FB 平台政策
      • Messenger page禁封影响&解封流程
      • 24小时窗口期与24+1 政策解读
Powered by GitBook
On this page
  • 发送消息API,快捷发送定制化的消息
  • 请求样例
  • 用户指定
  • 消息格式
  • 用户个人信息
  1. BotHub高级工具
  2. API介绍

发送消息API

快捷发送定制化的消息

Previous交易信息通知Next发送模板消息

Last updated 6 years ago

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

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

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

发送请求

您可以用任意一个已经启用的API Key() 向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

Form Data

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

未定义交易通知地址

20004

Message字段结构错误

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

用户指定

  • 示例

传进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)

消息类别,枚举值包括RESPONSE UPDATEMESSAGE_TAG, 根据facebook政策,2018.5.7之后必须带messaging_type才能发送消息,详见

消息标签, 枚举值包括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时必填, 标记消息使用场景, 详见

在一个请求中可以指定1个用户。如果是已经做过账号绑定的账号(或者 , user 为一个json对象,示例如下

怎样申请APIKey
在Messenger内登录
通过接口关联)
https://api.bothub.ai/api
https://developers.facebook.com/docs/messenger-platform/send-messages
https://developers.facebook.com/docs/messenger-platform/send-messages/message-tags