消息推送API

开发人员可以调用Joinchat发送消息API, 向messenger用户发送消息, 是客户自助解决问题的高效方案

请求URL

https://joinchat.ai/api/send_message

请求示例和接口安全性验证

JoinChat会为每个机器人生成独一无二的私钥。在调取Joinchat发送API时，开发人员需要用此密钥对整个请求参数提进行sha256、base64加密，并将签名加在请求Header头的x-joinchat-signature字段里。JoinChat会根据请求体和签名验证接口安全性, 注意不要泄露自己的私钥。开发者可以随时在后台设置--API管理页面更改自己的私钥

下面是调用JoinChat发送API向用户发送消息的简单示例 ：

<?php
// API管理中秘钥
const API_SECRET  = 'xxxxx';

// 请求参数
$params = '{"page_id":12345,"recipient":{"id":"123456"},
"message":{"template_type":"text","text":"Hello World"},
"tag":"ACCOUNT_UPDATE","delay":1}';

// 将参数和秘钥加密生成签名
$sign = base64_encode(hash_hmac('sha256', $params, API_SECRET, true));

/*httpClient 是伪代码*/
$client = new httpClient();

// 伪代码, 将签名添加到请求头中
$client->setHeaders(['x-joinchat-signature' => $sign]);

// 调用JoinChat发送API向messenger用户发送消息
$resp = $client->post('https://joinchat.ai/api/send_message', $params);

请求参数解释

参数示例

{
    "page_id":12345,
    "recipient":{
        "uuid":"123456"
    },
    "message":{
        "template_type":"text",
		"text":"Hello World"
    },
	"tag":"ACCOUNT_UPDATE",
	"delay": 1
}

参数含义

字段	类型	说明
page_id	字符串	机器人绑定的facebook主页id, 可在设置-API中查看
recipient	对象	对消息接收人的说明。所有请求都必须包含下列任一属性：id, phone, email, uuid。参考发送者对象recipient
message	对象	消息对象, 有五种, 包括 文本消息, 菜单消息, 画册消息, 列表消息, 回执消息, 参考各类型消息文档
tag	字符串	消息标签, 可以不受24小时发送时间窗限制, 参考消息标签文档
delay	int	消息延时, 单位s, 连续发送消息时, 先后顺序不好控制, 可加入适当延时, 最大10

发送者对象recipient

开发者可以通过四种方式给用户发送messenger消息, 四者只能选一个

字段	类型	说明
id	字符串	消息接收人的facebook_id, 可在用户管理中查看
phone	字符串	消息接收人的phone, 可在用户管理中查看, 需用户绑定phone
email	字符串	消息接收人的email, 可在用户管理中查看, 需用户绑定email
uuid	字符串	见uuid介绍

recipient.uuid

介绍

uuid是JoinChat为开发者提供了一种非常灵活的消息发送方式, 开发者可以将自己网站的用户和uuid做关联, 当开发者随时想向自己网站用户发送 messenger 消息, 既可通过和用户关联的uuid请求JoinChat发送API, 从而将消息送达到facebook用户, 使用场景如下:

• 用户注册后, 给用户messenger推送积分信息, 并且发送优惠券

• 用户购物车弃购后, 给用户messenger推送召回消息, 提高转化率

• 用户下单后, 给用户推送订单回执

配置方法

如何将自己网站的用户和uuid做关联呢? 三步即可

创建插件

登录JoinChat后台, 点击推广插件, 创建Send to Messenger插件或者优惠券插件;

配置SDK并安装代码

创建推广插件后, 点击SDK管理, 选择刚创建的插件, 启用后, 然后复制链接插码到自己的网站

开发者打开自己网站, 即可看到send to messenger插件

编写Javascript回调函数

当用户点击Send to Messenger插件, JoinChat会执行开发者设置的Javascript回调函数, 在回调函数中开发者可以将uuid和自己网站的用户id关联起来, 回调函数设置方式如下

<script type="text/javascript">
    /**
     * 回调函数必须命名为joinchatSendToMessengerCallback
     * 用户可以在回调函数中执行任何js原生代码, 包括发送Ajax请求
     * Joinchat会将uuid传给回调函数
     * 开发者可以向后端发送ajax请求, 将uuid和用户id做关联
     * @param uuid JoinChat为每个用户生成的唯一标识, 存到Cookie中
     */
    let joinchatSendToMessengerCallback = function (uuid) {
        console.log('hello Joinchat, uuid is: ' + uuid);
        let ajax = new XMLHttpRequest();
        // 向开发者后端发送ajax请求, 将uuid和用户id做关联
        ajax.open('get','/save-uuid?uuid='+uuid);
        ajax.send();
        ajax.onreadystatechange = function () {
            if (ajax.readyState==4 &&ajax.status==200) {
                console.log(ajax.responseText);
            }
        }
    }
</script>

<script src="https://joinchat.ai/js/analytics/sdk/15150c9d53ccc1eb21ffef1af5b6b184.js"></script>

开发者自己网站用户和uuid做了关联, 即可以随时向用户发送messenger消息

消息类型

joinchat支持用户发送文本消息, 菜单消息, 画册消息, 列表消息和回执消息,

其中文本消息为普通消息, 其他消息都被模板消息.

模板消息可以增加按钮, 首先先介绍支持的按钮类型, 然后介绍支持的各种消息类型

开发者想了解messenger消息类型, 可参阅facebook messenger 官方文档

Messaging - Messenger Platform - Documentation - Facebook for DevelopersFacebook for Developers

按钮类型

网址按钮

格式

{
  "type": "web_url",
  "url": "<URL_TO_OPEN_IN_WEBVIEW>",
  "title": "<BUTTON_TEXT>",
}

参数解释

• type: 值必须为web_url

• url: 点击按钮要打开的网址,

• title: 按钮标题。请勿超过 20 个字符。

属性	类型	说明
type	字符串	按钮的类型。必须是 web_url。
title	字符串	按钮标题。请勿超过 20 个字符。
url	字符串	用户轻触按钮后，此网址将在移动浏览器中打开。需要在Joinchat管理端将该网址域名添加到白名单中
webview_height_ratio	字符串	可选。 WebView 的高度。有效值：compact、tall、full。默认为 full。

回传按钮

格式

{
  "type":"postback",
  "title":"<BUTTON_TEXT>",
  "payload":"{\"block_id\":1}"
}

参数解释

字段	类型	说明
type	字符串	按钮的类型。必须为 postback。
title	字符串	按钮标题。请勿超过 20 个字符。
payload	字符串	点击按钮, 发送到Joinchat的数据, 目前支持格式为: block_id: 点击按钮, 触发的block flow_id: 点击按钮, 触发的flow

文本消息

请求参数示例:

{
    "page_id":12345,
    "recipient":{
        "id":"123456"
    },
    "message":{
        "template_type":"text",
		"text":"Hello World",
    },
	"tag":"ACCOUNT_UPDATE",
	"delay": 1,
}

参数解释

• template_type: 值必须为text

• text: UTF-8 编码文本，最多 640 个字符。

菜单消息

请求参数示例:

{
    "page_id":12345,
    "recipient":{
        "id":"123456"
    },
    "message":{
		"template_type":"button",
		"text":"What do you want to do next?",
		"buttons":[
		  {
			"type":"web_url",
			"url":"https://www.messenger.com",
			"title":"Visit Messenger"
		  }
		]
    },
	"tag":"ACCOUNT_UPDATE",
	"delay": 3,
}

参数解释

message

属性	类型	说明
template_type	字符串	值必须为 button
text	字符串	UTF-8 编码文本，最多 640 个字符。文本显示在按钮上方。
buttons	阵列<按钮>	显示为行动号召的一组按钮，包括 1-3 个按钮。
sharable	Boolean	可选。 设置为 true，可为模板消息启用 Messenger 原生分享按钮。默认为 false。

画册消息

请求参数示例:

{
    "page_id":12345,
    "recipient":{
        "id":"123456"
    },
    "message":{
        "template_type":"generic",
        "elements":[
            {
                "title":"Welcome!",
                "image_url":"https://petersfancybrownhats.com/company_image.png",
                "subtitle":"We have the right hat for everyone.",
                "default_action":{
                    "type":"web_url",
                    "url":"https://petersfancybrownhats.com/view?item=103",
                    "webview_height_ratio":"tall"
                },
                "buttons":[
                    {
                        "type":"web_url",
                        "url":"https://petersfancybrownhats.com",
                        "title":"View Website"
                    },
                    {
                        "type":"postback",
                        "title":"Start Chatting",
                        "payload":"DEVELOPER_DEFINED_PAYLOAD"
                    }
                ]
            }
        ]
    },
	"tag":"ACCOUNT_UPDATE",
	"delay": 3,
}

参数解释

message

属性	类型	说明
template_type	字符串	值必须为 generic
sharable	Boolean	可选。 设置为 true，可为模板消息启用 Messenger 原生分享按钮。默认为 false。
image_aspect_ratio	字符串	可选。 呈现 element.image_url指定的图片时使用的宽高比。必须为 horizontal (1.91:1) 或 square(1:1)。默认为 horizontal。
elements	数组<element>	element 对象的数组，描述要发送的常规模板的实例。指定多个元素时，会发送可水平滚动的模板轮播。最多支持 10 个元素。

message.elements

对于每一条消息，常规模板最多支持 10 个元素。除 title 之外，还必须至少设置一种属性。

属性名称	类型	说明
title	字符串	显示在模板中的标题。不超过 80 个字符。
subtitle	字符串	可选。 显示在模板中的副标题。不超过 80 个字符。
image_url	字符串	可选。 显示在模板中的图片网址。
default_action	对象	可选。 用户轻触模板时执行的默认操作。接受与网址按钮相同的属性，title 除外。
buttons	数组<button>	可选。 要添加到模板中的按钮数组。每个元素最多支持 3 个按钮。

列表消息

请求参数示例:

{
    "page_id":12345,
    "recipient":{
        "id":"123456"
    },
    "message":{
        "template_type":"list",
        "top_element_style":"compact",
        "elements":[
            {
                "title":"Classic T-Shirt Collection",
                "subtitle":"See all our colors",
                "image_url":"https://peterssendreceiveapp.ngrok.io/img/collection.png",
                "buttons":[
                    {
                        "title":"View",
                        "type":"web_url",
                        "url":"https://joinchat.ai",
                        "messenger_extensions":true,
                        "webview_height_ratio":"tall",
                        "fallback_url":"https://peterssendreceiveapp.ngrok.io/"
                    }
                ]
            },
            {
                "title":"Classic White T-Shirt",
                "subtitle":"See all our colors",
                "default_action":{
                    "type":"web_url",
                    "url":"https://joinchat.ai",
                    "messenger_extensions":false,
                    "webview_height_ratio":"tall"
                }
            },
            {
                "title":"Classic Blue T-Shirt",
                "image_url":"https://peterssendreceiveapp.ngrok.io/img/blue-t-shirt.png",
                "subtitle":"100% Cotton, 200% Comfortable",
                "default_action":{
                    "type":"web_url",
                    "url":"https://joinchat.ai",
                    "messenger_extensions":true,
                    "webview_height_ratio":"tall",
                    "fallback_url":"https://peterssendreceiveapp.ngrok.io/"
                },
                "buttons":[
                    {
                        "title":"Shop Now",
                        "type":"web_url",
                        "url":"https://joinchat.ai",
                        "messenger_extensions":true,
                        "webview_height_ratio":"tall",
                        "fallback_url":"https://peterssendreceiveapp.ngrok.io/"
                    }
                ]
            }
        ],
        "buttons":[
            {
                "title":"View More",
                "type":"postback",
                "payload":"payload"
            }
        ]
    },
	"tag":"ACCOUNT_UPDATE",
	"delay": 3,
}

参数解释

message

属性	类型	说明
template_type	字符串	值必须为 list
top_element_style	字符串	可选。 设置第一个列表项的格式。Messenger 网页客户端目前仅呈现 compact 格式。 compact:呈现无格式的列表项。 large:将第一个列表项呈现为封面项。
buttons	一组<按钮>	可选。 显示在列表底部的按钮。最多支持 1 个按钮。
elements	一组<元素>	描述列表中各项目的一组元素。 要求最少 2 个元素。最多支持 4 个元素。
sharable	Boolean	可选。 设置为 true，可为模板消息启用 Messenger 原生分享按钮。默认为 false。

message.elements

属性	类型	说明
title	字符串	显示为列表项标题的字符串。 不超过 80 个字符。如果标题跨越太多行，则可能会被截断。 元素也必须至少设置 image_url 或 subtitle 之一。
subtitle	字符串	可选。 显示为列表项副标题的字符串。不超过 80 个字符。如果副标题跨越太多行，则可能会被截断。 元素必须至少设置 image_url 或 subtitle 之一。
image_url	字符串	可选。 要显示在列表项中的图片网址。 元素必须至少设置 image_url 或 subtitle 之一。
default_action	对象	可选。网址按钮，指定用户轻触列表项时要执行的默认操作。 仅当 messenger_extensions 属性设置为 true 时允许使用
buttons	一组<按钮>	可选。 要显示在列表项中的按钮。最多支持 1 个按钮。

回执消息

请求参数示例:

{
    "page_id":12345,
    "recipient":{
        "uuid":"123456"
    },
    "message":{
        "template_type":"receipt",
        "recipient_name":"Stephane Crozatier",
        "order_number":"12345678902",
        "currency":"USD",
        "payment_method":"Visa 2345",        
        "order_url":"http://petersapparel.parseapp.com/order?order_id=123456",
        "timestamp":"1428444852",         
        "address":{
          "street_1":"1 Hacker Way",
          "street_2":"",
          "city":"Menlo Park",
          "postal_code":"94025",
          "state":"CA",
          "country":"US"
        },
        "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
          }
        ],
        "elements":[
          {
            "title":"Classic White T-Shirt",
            "subtitle":"100% Soft and Luxurious Cotton",
            "quantity":2,
            "price":50,
            "currency":"USD",
            "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":"USD",
            "image_url":"http://petersapparel.parseapp.com/img/grayshirt.png"
          }
        ]
      },
	"tag":"ACCOUNT_UPDATE",
	"delay": 3,
}

参数解释

message

Property	Type	Description
template_type	String	Value must be receipt.
sharable	Boolean	Optional. Set to true to enable the native share button in Messenger for the template message. Defaults to false.
recipient_name	String	The recipient's name.
order_number	String	The order number. Must be unique.
currency	String	The currency of the payment.
payment_method	String	The payment method used. Providing enough information for the customer to decipher which payment method and account they used is recommended. This can be a custom string, such as, "Visa 1234".
timestamp	String	Optional. Timestamp of the order in seconds.
elements	Array<element>	Optional. Array of a maximum of 100 element objects that describe items in the order. Sort order of the elements is not guaranteed.
address	address object	Optional. The shipping address of the order.
summary	Object	The payment summary. See summary.
adjustments	Array<adjustment>	Optional. An array of paymentobjects that describe payment adjustments, such as discounts.

message.address

Property	Type	Description
street_1	String	The street address, line 1.
street_2	String	Optional. The street address, line 2.
city	String	The city name of the address.
postal_code	String	The postal code of the address.
state	String	The state abbreviation for U.S. addresses, or the region/province for non-U.S. addresses.
country	String	The two-letter country abbreviation of the address.

message.summary

The property values of the summary object should be valid, well-formatted decimal numbers, using '.' (dot) as the decimal separator. Please note that most currencies only accept up to 2 decimal places.

Property	Type	Description
subtotal	Number	Optional. The sub-total of the order.
shipping_cost	Number	Optional. The shipping cost of the order.
total_tax	Number	Optional. The tax of the order.
total_cost	Number	The total cost of the order, including sub-total, shipping, and tax.

message.adjustments

Property	Type	Description
name	String	Required if the adjustments array is set. Name of the adjustment.
amount	Number	Required if the adjustments array is set. The amount of the adjustment.

message.elements

Property	Type	Description
title	String	The name to display for the item.
subtitle	String	Optional. The subtitle for the item, usually a brief item description.
quantity	Number	Optional. The quantity of the item purchased.
price	Number	The price of the item. For free items, '0' is allowed.
currency	String	Optional. The currency of the item price.
image_url	String	Optional. The URL of an image to be displayed with the item.

消息标签

借助消息标签，您可以在需要持续发送通知或最新消息的一些有限情况下，不受 24 小时时间窗的限制向用户发送消息。这样一来，您的智能助手就可以更灵活地与用户互动，您也可以在 Messenger 平台为用户打造更丰富的体验。

允许的用途 — 无推广内容

请注意，消息标签仅用于发送非推广内容。

使用消息标签发送推广内容（例如，每日特惠、优惠券、折扣或促销公告）是违反 Messenger 平台政策的行为。

Message Tags - Messenger Platform - Documentation - Facebook for DevelopersFacebook for Developers

标签	允许的用途	示例
BUSINESS_PRODUCTIVITY	发送非推广消息来帮助用户管理业务或相关活动的效率。	关于公司已从服务提供商处订阅或购买的产品或服务的通知 针对即将支付的结算单或即将开始的服务维护发出的提醒或通知 有关公司表现、指标或推荐操作的报告
COMMUNITY_ALERT	向消息接收人通知紧急事件或公用设施问题，或在您的社群内询问平安状况。	询问平安状况 通知紧急事件或公用设施问题
CONFIRMED_EVENT_REMINDER	向消息接收人发送参加排期活动的提醒消息。	用户注册参加的近期课程或活动 参加已接受邀请的活动或预约服务的确认消息
NON_PROMOTIONAL_SUBSCRIPTION	发送 Messenger 平台订阅消息政策中规定的几个类别的非推广消息：新闻资讯、工作效率和个人追踪。您可在主页的“设置”>“Messenger 平台”版块申请此标签的使用权限。	查看开放平台政策概览的“订阅消息功能”部分
PAIRING_UPDATE	通知消息接收人，已根据之前的请求找到匹配项。	约会应用中找到了匹配的对象 停车位可用
APPLICATION_UPDATE	通知消息接收人其申请状态的更新。	申请正在接受审核 申请已获得批准 求职申请状态
ACCOUNT_UPDATE	通知消息接收人其帐户设置的更改。	个人主页已更改 首选项已更新 设置已更改 会员身份已过期 密码已更改
PAYMENT_UPDATE	通知消息接收人现有交易的支付状态更新。	发送收据 发送缺货通知 通知拍卖已结束 支付交易的状态已更改
PERSONAL_FINANCE_UPDATE	确认消息接收人的财务活动。	账单支付提醒 排期支付提醒 支付收据通知 资金转账确认或更新 其他金融服务类交易活动
SHIPPING_UPDATE	通知消息接收人某件已购买商品的配送状态更改。	商品已发货 状态更改为在途 商品已送达 配送延迟
RESERVATION_UPDATE	通知消息接收人现有预订的更新。	行程更改 地点更改 取消已确认 酒店预订已取消 租车接人时间更改 房型升级已确认
ISSUE_RESOLUTION	通知消息接收人在 Messenger 对话中发起的客户服务问题有何更新。	问题已解决 问题状态已更新 该问题需要提供其他信息 跟进客户查询或支持工单
APPOINTMENT_UPDATE	通知消息接收人现有预约的更改。	预约时间更改 预约地点更改 预约已取消
GAME_EVENT	通知消息接收人，游戏内用户进度、全局活动或直播体育赛事的更改。	玩家的游戏内作物已可收割 玩家的每日比赛即将开始 用户最喜欢的足球队即将开踢
TRANSPORTATION_UPDATE	通知消息接收人现有交通运输服务预订的更新。	航班状态更改 便车已取消 行程已开始 渡轮已抵达
FEATURE_FUNCTIONALITY_UPDATE	通知消息接收人，智能助手推出了新特性或新功能。	智能助手中添加了与在线客服聊天的功能 智能助手添加了新技能
TICKET_UPDATE	向消息接收人发送已购票活动的更新或提醒。	音乐会开始时间更改 活动地点更改 演出已取消 可以申请退款