发送 API 参考文档

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

创建

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

前期准备

您需要提供:

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

限制

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

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

请求示例

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

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

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

curl -X POST "https://graph.facebook.com/v20.0/{PAGE_ID}/messages" \
      -d "recipient={'id':'{PSID}'}" \
      -d "messaging_type=RESPONSE" \
      -d "message={'text':'hello, world'}" \
      -d "access_token={PAGE_ACCESS_TOKEN}"

若请求成功,应用会收到以下 JSON 响应:

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

参数

参数描述

message

对象

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

  • attachment 对象 — 预览网址。用于发送带有媒体的消息或结构化消息。必须设置 textattachment

    • type — 附件类型。可以是 audiofileimagetemplatevideo。文件大小不得超过 25MB
    • payload — 包含模板内容文件内容的对象
  • metadata — 您要在 message_echo Webhooks 中传递的额外数据的字符串。必须少于 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 权限,则无需再为该应用申请访问权限。

    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。

读取

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

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

更新

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

删除

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

另请参阅

开发者支持