营销消息

本文档将向您介绍如何向用户请求权限以发送营销消息、有关发送请求的具体要求和限制，以及如何创建并发送营销消息权限请求。

概览

通过营销消息，Facebook 公共主页或 Instagram 专业帐户可以在标准消息时间范围过后，在用户授权下向该用户发送消息。您可以通过营销消息，与对您或您的业务感兴趣的用户建立关系。

营销消息是一项新的可选高级功能，我们计划未来对此进行收费。我们目前向使用 WhatsApp Business API 发送消息的企业收费，并且正在收集客户反馈，据此制定适当的定价模式。如果免费试用有任何变更，我们将预留充足的时间，提前通知客户和合作伙伴。

要求

• 使用营销消息或 Messenger 开放平台的其他功能时，您必须遵守所有适用的开发者政策

• 在标准消息时间范围内，您只能向每位用户发送 1 条营销消息订阅请求。用户订阅营销消息的操作不会开启标准消息时间范围

• 您的应用和/或消息体验不得收到过多的用户负面反馈。如果我们确定您的应用消息体验收到的用户负面反馈比例过高，消息功能可能受到限制或移除

• 不得使用订阅请求等营销消息向用户发送垃圾信息，其中包括非常频繁地向相同用户发送重复的订阅请求，以及发送开发者政策定义的其他类型垃圾信息

• 为了维持我们为您提供的服务范围，您必须遵守我们针对 Messenger 开放平台和营销消息功能制定的限制

限制

• 您每周只能向同一用户发送 1 条具有同一特定标题的订阅请求。其中包括使用默认值“更新和优惠”。
• 请勿向同一用户发送重复的订阅请求。重复订阅请求指从 Facebook 公共主页发送的多个通知具有相同的 title，或从 Instagram 专业帐户发送的多个通知具有相同的 title 和 image_url
• 您只能在标准消息时间范围内发送订阅请求
• 如果用户订阅营销消息，此操作不会开启标准消息时间范围
• 您只能看到用户是否已订阅营销消息，但不能看到待处理的订阅请求的状态
• 如果用户已选择停止接收营销消息，系统不会继续向该用户发送您的通知，并且您将会收到错误消息
• 用户可以屏蔽、不看或举报您的消息
• 对于使用 Instagram 专业帐户发送的营销消息，一般来说，每个用户在 7 天内最多可以发送 10 个不同标题的订阅请求。次级限制是 1 天内可以向每位用户发送最多 5 条订阅请求。但在发送之前，您应考虑用户是否有可能认为每条订阅请求与他们有关且有价值。

我们一直致力于打造最佳的用户和企业体验，因此这些要求和限制可能会时有变更。

最佳实践

为了打造高质量用户体验，您应通过执行以下操作来向用户发送与其相关且有价值的营销消息：

• 您的订阅请求（包括标题和图像）涵盖用户预期接收的营销消息类型，例如订单更新、商品推荐或特定优惠

• 向用户发送多个订阅请求时，每个订阅请求应清楚表明用户可预期接收的不同营销消息的具体类型

营销消息应与用户可能认为有价值的用例相关，并且应量身定制。

用户可针对消息体验提供反馈，比如屏蔽您的消息，这可能会导致您在使用营销消息时受限。您应该定期检查您的订阅请求和营销消息，以了解它们是否符合上述最佳实践。

消息频率

适用于 2023 年 2 月 2 日之前创建的通知消息口令。

• 用户订阅后，您可以按照每天、每周或每月的频率向用户发送消息，具体取决于用户在订阅时选择的频率。

请求发送营销消息所需的权限

用户必须授予订阅权限，才能接收从您 Facebook 公共主页或 Instagram 专业帐户发送的营销消息。Messenger 开放平台可提供多种方法助您启用该权限。您可以在以下消息体验中构建订阅请求：

• Messenger 直达广告 – 用户点击您的广告
• 聊天插件 – 用户在您的网站使用聊天插件发起对话
• 复选框插件 – 用户在表单中点击复选框并提交表单
• m.me 链接 – 用户点击您的网站、电子邮件、社交媒体帖子等内容中的 m.me 链接
• 私信回复 – 用户向您公司的 Facebook 公共主页发布访客帖或评论
• 二维码 – 用户扫描数字表面和印刷表面上的二维码（采用 m.me 链接）
• “发送到 Messenger”插件 – 用户使用预定义的行动号召 (CTA) 按钮或文本列表发起对话

订阅请求示例

如要发送营销消息订阅请求，请向 /PAGE-ID/messages 端点发送 POST 请求，将消息模板类型设置为 notification_messages。公共主页编号为您的 Facebook 公共主页编号，或与您 Instagram 专业帐户绑定的 Facebook 公共主页编号。

注意：如果营销消息中包含来自 Facebook 公共主页 或 Instagram 专业帐户 的轮播广告，则请求中必须包含 title 参数。

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient":{
    "id":"PSID-OR-IGSID"
  },
  "message":{
    "attachment":{
      "type":"template", 
      "payload":{
         "template_type":"notification_messages", 
         "notification_messages_timezone": "UTC",
         "title":"TITLE",
         "image_url":"IMAGE-URL",
         "payload": "ADDITIONAL-WEBHOOK-INFORMATION",
      }
    }
  }
}' "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/messages?access_token=PAGE-ACCESS-TOKEN"

若请求成功，您的应用会收到附有收信人编号和消息编号的以下 JSON 响应。

{ 
        "recipient": {
          "id":"PSID-OR-IGSID",
          "message_id":"MESSAGE-ID",
}

消息附件对象参考文档

必须在要向 /PAGE-ID/messages 端点发送的 POST 请求中加入 messageattachment JSON 对象，以便执行营销消息订阅请求。

通知消息口令

用户订阅后，您的公司将收到一条 messaging_optin Webhooks 通知，其中包含通知消息口令以及有关消息标题、订阅用户所在时区等信息。您可借助通知消息口令向用户发送营销消息。

订阅 Webhooks 通知

{
  "sender": {
    "id": "PSID",
  },
  "recipient": {
    "id": "PAGE-ID",
  },
  "timestamp": "TIMESTAMP",
  "optin": {
    "type": "notification_messages", 
      "payload": "ADDITIONAL-WEBHOOK-INFORMATION",
      "notification_messages_token": "NOTIFICATION-MESSAGES-TOKEN", 
      "notification_messages_timezone": "TIMEZONE-ID",
      "token_expiry_timestamp": "TIMESTAMP",
      "user_token_status": "TOKEN-STATUS"  
      "notification_messages_status": "MESSAGE-STATUS", 
      "title": "TITLE-FOR-THE-NOTIFICATION"
    }
}

对于选择继续订阅营销消息的用户，系统会将其口令过期日期延长。用户可随时退订。

订阅跟进消息

用户订阅营销消息后，您可发送最多 3 条跟进消息。这些消息必须在发送第 1 条跟进消息后的 2 分钟内发送。第 2 和第 3 条跟进消息的长度不得超过 250 个字符。这些跟进消息可以在 24 小时标准消息时间范围过后发送。

如要发送跟进消息，请向 /PAGE-ID/messages 端点发出 POST 请求，在请求中加入包含通知消息口令的 recipient 对象和包含跟进消息文本的 message 对象。所有 3 条跟进消息的 API 请求都使用相同语法。

请求示例

curl -X POST -H "Content-Type: application/json" -d 
    '{ 
        "recipient":{ 
            "notification_messages_token":"NOTIFICATION-MESSAGE-TOKEN" 
        }, 
        "message":{ 
            "text":FOLLOWUP-MESSAGE-TEXT-HERE, 
        } 
    }' 
"https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/messages?access_token=TOKEN"

获取口令清单

您现在可以向 /PAGE-ID/notification_message_tokens 端点发送 GET 请求以获取所有有效通知消息口令清单。

请求示例

curl -i -X GET "https://graph.facebook.com/API-VERSION-NUMBER/PAGE-ID/notification_message_tokens
    ?access_token=PAGE-ACCESS-TOKEN"

默认情况下，系统将返回最多 25 个口令的清单，并按更新时间对这些口令排序。如需了解更多内容，您可以添加 limit 参数。目前，系统最多可以返回 100 个口令。无论 before 参数是否可用，您都可以将 after 参数用于分页。

若请求成功，您的应用将收到以下 JSON 响应，其中包含口令、收信人编号（Instagram 范围编号或公共主页范围编号）、口令创建时间、通知标题以及您可以向该收信人发送下一条营销消息的时间。

{
  "data":[
    {
      "notification_messages_token":"NOTIFICATION-MESSAGE-TOKEN-ID-1",
      "recipient_id":"PAGE-OR-INSTAGRAM-SCOPED-ID-1",
      "notification_messages_reoptin":"RE-OPT-IN-STATUS",
      "creation_timestamp":TIMESTAMP,
      "token_expiry_timestamp":UNIX-TIMESTAMP-EXPIRATION-DATE,
      "user_token_status":"TOKEN-STATUS",
      "topic_title":"NOTIFICATION-TITLE",
      "notification_messages_timezone":"TIMEZONE-ID",
      "next_eligible_time": TIMESTAMP
    },
...
    {
      "notification_messages_token":"NOTIFICATION-MESSAGE-TOKEN-ID-25",
      "recipient_id":"PAGE-OR-INSTAGRAM-SCOPED-ID-25",
      "notification_messages_reoptin":"RE-OPT-IN-STATUS",
      "creation_timestamp":TIMESTAMP,
      "token_expiry_timestamp":UNIX-TIMESTAMP-EXPIRATION-DATE,
      "user_token_status":"TOKEN-STATUS",
      "topic_title":"NOTIFICATION-TITLE",
      "notification_messages_timezone":"TIMEZONE-ID",
      "next_eligible_time": TIMESTAMP
    }
  ],
  "paging":{"cursors":{"before":"QVFIU...","after":"QVFIU..."},"next":"https:\/\/graph.facebook.com\/LATEST-API-VERSION\/PAGE-ID\/notification_message_tokens?access_token=PAGE-ACCESS-TOKEN"}
}

获取口令信息

虽然我们推荐您使用 messaging_optin Webhooks 来收集营销消息信息，但您可以向口令端点发送 GET 请求，并在请求中将口令附加至 notification_messages_ 之后，以 notification_messages_NOTIFICATION-MESSAGES-TOKEN 的形式获取口令信息。

请求示例

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/notification_messages_NOTIFICATION-MESSAGES-TOKEN
    ?access_token=PAGE-ACCESS-TOKEN"

若请求成功，您的应用将收到以下 JSON 响应，其中包含通知消息口令、收信人编号和其他口令信息。您将使用通知消息口令和收信人编号发送营销消息。

{
  "notification_messages_token": "NOTIFICATION-MESSAGES-TOKEN",
  "recipient_id": "PAGE-OR-INSTAGRAM-SCOPED-ID",
  "creation_timestamp": "TIMESTAMP",
  "token_expiry_timestamp": "TIMESTAMP",
  "user_token_status": "REFRESHED",
  "notification_messages_reoptin": "ENABLED",
  "notification_messages_timezone": "TIMEZONE-ID"
  "next_eligible_time": TIMESTAMP
}

这些 API 调用会记入应用的流量限制。

发送营销消息

准备工作

您将需要：

• 已订阅通知的用户的通知消息口令
• 您公司的 Facebook 公共主页编号
• 从可以在公共主页上执行 MESSAGING 任务的用户处请求获取的公共主页访问口令
• 使用 Facebook 登录所需的 pages_messaging 权限
• 要纳入营销消息的任何资产
• 应用的 messaging_referrals Webhooks 订阅

如要发送营销消息，请向 /PAGE-ID/messages 端点发送 POST 请求，并在消息附件中设置收件人 NOTIFICATION-MESSAGES-TOKEN 值和消息信息。

限制

• 每天只能使用每个通知消息口令发送 1 条消息。如果您要发送多条消息，请务必确保后续消息的发送间隔为 24 小时，否则您会收到错误。（不适用于订阅跟进消息。）

建议

• 我们强烈建议在发送营销消息时参考收信人的时区，以确保收信人在适当的时间收到消息。

请求示例

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient":{
    "notification_messages_token": "NOTIFICATION-MESSAGES-TOKEN"
  },
  "message":{
    "attachment":{
      "type":"template",
      "payload":{
        "template_type":"generic",
        "elements":[
           {
            "title":"Welcome!",
            "image_url":"https://raw.githubusercontent.com/fbsamples/original-coast-clothing/main/public/styles/male-work.jpg",
            "subtitle":"We have the right hat for everyone.",
            "default_action": {
              "type": "web_url",
              "url": "https://www.originalcoastclothing.com/",
              "webview_height_ratio": "tall"
            },
            "buttons":[
              {
                "type":"web_url",
                "url":"https://www.originalcoastclothing.com/",
                "title":"View Website"
              },{
                "type":"postback",
                "title":"Start Chatting",
                "payload":"ADDITIONAL-WEBHOOK-INFORMATION"
              }              
            ]      
          }
        ]
      }
    }
  }
}' "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/messages?access_token=PAGE-ACCESS-TOKEN"

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

{ 
  "recipient": "PAGE-OR-INSTAGRAM-SCOPED-ID",
  "message_id": "MESSAGE-ID"      
}

测试营销消息

您可以随时测试您的营销消息。

准备工作

您将需要：

• 接收通知的用户，即测试者。此用户必须在应用中拥有某种身份。

测试订阅选项

您可以按照以下步骤随时测试您的营销消息。

• 第 1 步：向测试者发送包含营销消息订阅模板的消息。
• 第 2 步：确保测试者点击对话中的订阅按钮，如接收 5 折促销消息。
• 第 3 步：向测试者发送第 1 条营销消息
• 第 4 步：在发送第 1 条营销消息后，立即发送另一条营销消息，并将 developer_action 参数设置为 ENABLE_FOLLOWUP_MESSAGE。
• 第 5 步：向测试者再次发送一条营销消息，此即测试消息。

请求示例

curl -X POST "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/notification_messages_dev_support
    ?recipient={
        "notification_messages_token": "NOTIFICATION-MESSAGES-TOKEN"
    }
    &developer_action=ENABLE_FOLLOWUP_MESSAGE
    &access_token=PAGE-ACCESS-TOKEN"

若请求成功，您的应用将收到以下 JSON 响应，其中包含 success（值设为 true）。

{ "success": true }

如要测试重新订阅情况，请重复执行上述步骤，并将第 4 步中的 developer_action 参数设置为 SEND_RE_OPTIN。

后续步骤

• 消息订阅 Webhooks 通知
• 请访问消息类型概览 ，了解您可以发送的不同消息类型。

另请参阅

• 公共主页消息参考文件 ，了解有关定期消息可用字段的更多信息。
• 可用时区列表
• Messenger 开放平台错误代码