Send API 参考文档

Send API 是用于向用户发送消息的主要 API，支持发送文本、附件、模板及发送者操作等。

创建

创建消息并将消息发送给您的客户或对您的 Facebook 公共主页感兴趣的用户。

准备工作

您需要准备好以下各项：

由可以在公共主页上执行 MESSAGE 任务的用户请求的公共主页访问口令
pages_messaging 权限
消息接收者必须曾在过去 24 小时内向您的公共主页发送过消息，或者已同意在 24 小时标准消息时间范围过后接收您公共主页发送的消息

限制

消息标签无法用于发送推广内容

请注意，对于使用 recipient.user_ref 或 recipient.phone_number 发送的消息，发送 API 不会在响应中加入 recipient_id 来识别消息收信人。

请求示例

如要向用户发送消息，请向 /PAGE-ID/messsages 端点发送 POST 请求，并在其中设置 messaging_type 和 recipient 参数以及提供消息内容。

为方便阅读，示例格式已经过调整。

以下是针对用户消息的响应示例，其中公共主页发送的消息仅包含文本。

curl -i -X POST "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/messages
    ?recipient={'id':'PSID'}
    &messaging_type=RESPONSE
    &message={'text':'hello,world'}
    &access_token=PAGE-ACCESS-TOKEN

若请求成功，应用会收到以下 JSON 响应：

{
  "recipient_id": "PAGE-SCOPED-ID",
  "message_id": "AG5Hz2U..."
}

参数

参数描述

参数	描述
`message` 对象	公共主页所发送消息的类型。使用此参数时，必须将其设置为 `text` 或 `attachement`。 `attachment` 对象 – 预览网址。用于发送带有媒体内容的消息或结构化消息。必须设置 `text` 或 `attachment`。 `type` – 附件类型。可以是 `audio`、`file`、`image`、`template` 或 `video`。文件大小不得超过 25MB。 `payload` – 包含模板内容或文件内容的对象。 `metadata` – 您要在 `message_echo` Webhook 中传递的额外数据的字符串。必须少于 1,000 个字符。 `quick_replies` – 要在消息中发送的快速回复的数组。 `text` – 仅包含文本的消息。必须是 UTF-8 字符且字符数少于 2,000。
`messaging_type` 枚举必要	所发送消息的类型 `RESPONSE` – 用于回复已收到消息的消息。这包括在 24 小时标准消息时间范围内发送的推广消息和非推广消息。例如，在用户询问预约确认或状态更新情况时，您可以使用此标签回复。 `UPDATE` – 主动发出且并非用于回复已收到消息的消息。这包括在 24 小时标准消息时间范围内发送的推广消息和非推广消息。 `MESSAGE_TAG` – 属于非推广消息的消息，而且是在 24 小时标准消息时间范围过后使用消息标签发出。此类消息必须符合此标签的合理用途。
`notification_type` 枚举	用户将收到的推送通知的类型 `NO_PUSH` – 不发送通知 `REGULAR`（默认） – 系统在用户收到消息后发出声音或震动 `SILENT_PUSH` – 仅在屏幕上显示通知
`recipient` 对象必要	将收到公共主页所发送消息的用户 `id` – 回复您公共主页在过去 24 小时内收到的消息时所用的用户公共主页范围编号，或已同意在 24 小时标准消息时间范围过后接收您公共主页所发送消息的用户的公共主页范围编号 `user_ref` – 针对复选框或顾客聊天插件进行回复时所用的用户参照 `comment_id` – 针对公共主页帖子的访客评论发送私信回复时所用的评论编号 `post_id` – 针对公共主页的访客来帖发送私信回复时所用的公共主页帖子编号
`sender_action` 枚举	消息窗口中显示的操作图标，表示公共主页对收到的用户消息所执行的操作。 `typing_on` – 公共主页正在准备回复时，系统会显示输入气泡 `typing_off` – 不显示输入气泡 `mark_seen` – 公共主页阅读消息后，系统会显示“已读”图标仅可以与 `recipient` 参数一同发送。无法与 `message` 参数一同发送，而必须作为单独的请求发送。
`tag` 枚举	此标签可让您的公共主页在 24 小时标准消息时间范围过后向用户发送消息。 `ACCOUNT_UPDATE` – 将您要向客户发送的消息标记为针对其申请或帐户的不定期更新。查看合理用途。不适用于 Instagram 消息 API。 `CONFIRMED_EVENT_UPDATE` – 将您要向客户发送的消息标记为近期事件的提醒，或客户已报名参加的进行中事件的更新。查看合理用途。不适用于 Instagram 消息 API。 `CUSTOMER_FEEDBACK` – 将您要向客户发送的消息标记为客户反馈问卷调查。您必须在收到客户最后一条消息的 7 天内发送客户反馈消息。查看合理用途。不适用于 Instagram 消息 API。 `HUMAN_AGENT` – 对于 Instagram 消息 API 为必要项。在向客户发送的消息中添加此标签后，人工客服便可回复用户消息。人工客服可在收到用户消息的 7 天内发送消息。无法在标准消息时间范围内解决问题时，可以申请人工客服支持。查看合理用途。应用需通过开发者应用面板申请 `Human Agent` 权限。前往“应用面板”->“应用审核”->“权限和功能”->“人工客服”。如果应用之前获准使用公测版“人工客服”权限，则无需再为该应用申请访问权限。 `Human Agent` 权限尚未向标准访问级别和开发模式开放。在利用人工客服标签之前，您需要完成应用审核流程。在用于应用审核的提交材料中，请提供清晰的说明和演示，说明您打算如何在体验中利用人工客服标签。 `POST_PURCHASE_UPDATE` – 将您要向客户发送的消息标记为针对客户最近购买行为的更新。查看合理用途。不适用于 Instagram 消息 API。

message

对象

公共主页所发送消息的类型。使用此参数时，必须将其设置为 text 或 attachement。

attachment 对象 – 预览网址。用于发送带有媒体内容的消息或结构化消息。必须设置 text 或 attachment。
- type – 附件类型。可以是 audio、file、image、template 或 video。文件大小不得超过 25MB。
- payload – 包含模板内容或文件内容的对象。
metadata – 您要在 message_echo Webhook 中传递的额外数据的字符串。必须少于 1,000 个字符。
quick_replies – 要在消息中发送的快速回复的数组。
text – 仅包含文本的消息。必须是 UTF-8 字符且字符数少于 2,000。

messaging_type

枚举

必要

所发送消息的类型

RESPONSE – 用于回复已收到消息的消息。这包括在 24 小时标准消息时间范围内发送的推广消息和非推广消息。例如，在用户询问预约确认或状态更新情况时，您可以使用此标签回复。
UPDATE – 主动发出且并非用于回复已收到消息的消息。这包括在 24 小时标准消息时间范围内发送的推广消息和非推广消息。
MESSAGE_TAG – 属于非推广消息的消息，而且是在 24 小时标准消息时间范围过后使用消息标签发出。此类消息必须符合此标签的合理用途。

notification_type

枚举

用户将收到的推送通知的类型

NO_PUSH – 不发送通知
REGULAR（默认） – 系统在用户收到消息后发出声音或震动
SILENT_PUSH – 仅在屏幕上显示通知

recipient

对象

必要

将收到公共主页所发送消息的用户

id – 回复您公共主页在过去 24 小时内收到的消息时所用的用户公共主页范围编号，或已同意在 24 小时标准消息时间范围过后接收您公共主页所发送消息的用户的公共主页范围编号
user_ref – 针对复选框或顾客聊天插件进行回复时所用的用户参照
comment_id – 针对公共主页帖子的访客评论发送私信回复时所用的评论编号
post_id – 针对公共主页的访客来帖发送私信回复时所用的公共主页帖子编号

sender_action

枚举

消息窗口中显示的操作图标，表示公共主页对收到的用户消息所执行的操作。

typing_on – 公共主页正在准备回复时，系统会显示输入气泡
typing_off – 不显示输入气泡
mark_seen – 公共主页阅读消息后，系统会显示“已读”图标

仅可以与 recipient 参数一同发送。无法与 message 参数一同发送，而必须作为单独的请求发送。

tag

枚举

此标签可让您的公共主页在 24 小时标准消息时间范围过后向用户发送消息。

ACCOUNT_UPDATE – 将您要向客户发送的消息标记为针对其申请或帐户的不定期更新。查看合理用途。
不适用于 Instagram 消息 API。
CONFIRMED_EVENT_UPDATE – 将您要向客户发送的消息标记为近期事件的提醒，或客户已报名参加的进行中事件的更新。查看合理用途。
不适用于 Instagram 消息 API。
CUSTOMER_FEEDBACK – 将您要向客户发送的消息标记为客户反馈问卷调查。您必须在收到客户最后一条消息的 7 天内发送客户反馈消息。查看合理用途。
不适用于 Instagram 消息 API。
HUMAN_AGENT – 对于 Instagram 消息 API 为必要项。在向客户发送的消息中添加此标签后，人工客服便可回复用户消息。人工客服可在收到用户消息的 7 天内发送消息。无法在标准消息时间范围内解决问题时，可以申请人工客服支持。查看合理用途。
- 应用需通过开发者应用面板申请 Human Agent 权限。前往“应用面板”->“应用审核”->“权限和功能”->“人工客服”。如果应用之前获准使用公测版“人工客服”权限，则无需再为该应用申请访问权限。
Human Agent 权限尚未向标准访问级别和开发模式开放。在利用人工客服标签之前，您需要完成应用审核流程。在用于应用审核的提交材料中，请提供清晰的说明和演示，说明您打算如何在体验中利用人工客服标签。
POST_PURCHASE_UPDATE – 将您要向客户发送的消息标记为针对客户最近购买行为的更新。查看合理用途。
不适用于 Instagram 消息 API。

消息标签的合理用途

以下表格列出了每个消息标签所对应的消息类型。

消息标签	合理用途
`ACCOUNT_UPDATE`	合理用途通知申请（如信用卡或求职申请）的状态变更通知系统发现的可疑活动（如欺诈提醒）禁止用途（非详尽清单）推广内容，包括但不限于特卖、促销、优惠券和折扣等定期提示的内容（例如对账单已就绪，账单已到期或者有新的招聘帖）邀请用户参与任何跟以往的 Messenger 互动无关的调查、投票或点评的提示信息不适用于 Instagram 消息 API。
`CONFIRMED_EVENT_UPDATE`	合理用途提醒用户已安排的近期课程、预约或活动确认用户预约或参加已接受邀请的活动或预约通知用户交通或旅程安排，例如抵达、取消、行李延误或其他旅程状态变更禁止用途（非详尽清单）推广内容，包括但不限于特卖、促销、优惠券和折扣与用户未报名的活动相关的内容（例如购买活动门票、交叉推广其他活动的门票、行程安排等的提醒）与往期活动相关的消息邀请用户参与任何跟以往的 Messenger 互动无关的调查、投票或点评的提示信息不适用于 Instagram 消息 API。
`CUSTOMER_FEEDBACK`	合理用途调查购买支持反馈调查活动反馈点评商品禁止用途（非详尽清单）此标签仅可与客户反馈模板一同使用。禁止且无法用于其他任何形式。不适用于 Instagram 消息 API。
`HUMAN_AGENT`	合理用途人工客服可支持 24 小时标准消息时间范围内无法解决的问题，如正常营业时间之外出现的问题，或者需要 24 小时以上才能解决的问题禁止用途（非详尽清单）自动消息与用户咨询无关的内容对于 Instagram 消息 API 为必要项。
`POST_PURCHASE_UPDATE`	合理用途确认交易，例如结算单或收据更新配送状态，例如商品在运输途中、已发货、已派送或延误更新用户已下订单的状态，例如信用卡遭拒、商品缺货或其他需要用户采取操作的订单状态禁止用途（非详尽清单）推广内容，包括但不限于特卖、促销、优惠券和折扣交叉销售或追加销售商品或服务的消息邀请用户参与任何跟以往的 Messenger 互动无关的调查、投票或点评的提示信息不适用于 Instagram 消息 API。

读取

您无法在此端点上执行该操作。

如需了解您公共主页参与的对话，请访问公共主页对话参考文档。

更新

您无法在此端点上执行该操作。

删除

您无法在此端点上执行该操作。

其他参考文档

开发者支持

使用 Meta 状态工具可查看 Meta 商务产品的状态和中断情况。
使用 Meta 开发者支持工具可报告漏洞、查看报告的漏洞、获取有关广告或商务管理平台的帮助等等。
访问 Messenger 开放平台支持资源可查看 Messenger 开放平台的更多支持资源。

Send API 参考文档

创建

准备工作

限制

请求示例

参数

消息标签的合理用途

合理用途

禁止用途（非详尽清单）

合理用途

禁止用途（非详尽清单）

合理用途

禁止用途（非详尽清单）

合理用途

禁止用途（非详尽清单）

合理用途

禁止用途（非详尽清单）

读取

更新

删除

其他参考文档

开发者支持