Recurring Notifications

Overview

This feature allows Pages to send Recurring Notifications on a topic, and a frequency, a user has opted-in to. During the 24 hour messaging window, a Page can request to send users notifications at a set frequency, either on a daily, a weekly, or a monthly basis, for a period of time. Users can opt-in to receive Recurring Notifications any time after this opt-in request is sent. Once a user opts-in, a Page can send Recurring Notifications related to ongoing promotions and campaigns that the user is interested in at the set frequency. Recurring Notifications are a great way for Pages to build relationships with customers and keep them apprised of updates.

Recurring Notifications is a new, optional premium feature that we intend to charge businesses for in the future. It is currently available to all businesses using Messenger Platform as part of a free trial period. We currently charge businesses to send messages from the WhatsApp Business API and listening to customer feedback to guide decisions on our pricing model. We will inform customers and partners of any changes to the free trial with ample advance notice.

Best Practices

You should send people relevant, valuable Recurring Notifications, in order to create a high-quality user experience by doing the following:

  • Your opt-in request, including the title and image, encompasses the types of Recurring Notifications users can expect to receive, such as order updates, product recommendations, or certain offers

  • When sending more than one opt-in request to a user, each opt-in request should clearly state the different, specific types of Recurring Notifications the user can expect to receive

Recurring Notifications should be relevant and tailored to use cases that a user is likely to find valuable.

Users can provide feedback on your messaging experience, including blocking your messaging, which may result in restrictions on your use of Recurring Notifications. You should regularly review your opt-in requests and Recurring Notifications to see if they meet the best practices above.

Requirements

  • You must comply with all applicable Developer Policies when using Recurring Notifications or other Messenger Platform features

  • You may only send a request for a user to opt-in to Recurring Notifications within the standard 24 hour messaging window. A user’s action of opting-in to Recurring Notifications does not open the 24 hour messaging window

  • Your app and/or messaging experience must not receive excessive negative feedback from users. Messaging capabilities may be restricted or removed if we determine your app’s messaging experience has received excessive rates of negative feedback from users

  • You must not use Recurring Notifications, including opt-in requests, to spam users. This includes sending duplicate opt-in requests at high frequencies to the same user/s and other types of spam as defined by our Developer Policies

  • You must respect the limitations we have placed on the functionality of Messenger Platform and Recurring Notifications in order to maintain the scope of service we are providing you

  • Do not offer users rewards in exchange for opting-into Recurring Notifications. This includes tangible or intangible rewards, as well as financial or non-financial rewards, such as coupons, discounts, points, merchandise, cashback or other rewards or incentives

Limitations

  • Our Recurring Notifications service limits the number of opt-in requests that can be sent to a user. This limit helps avoid negative user experiences and protects the integrity of Messenger Platform

  • Generally, up to 10 opt-in requests can be sent per user over a 7 day period. A sub-limit of up to 5 opt-in requests may be sent to a user in a day. However, you should consider whether users are likely to find each opt-in request relevant and valuable before sending. Users can block, mute or report your Page’s messaging

  • If you have received recent, sustained low opt-in rates for Recurring Notifications or your messaging experience has violated our Community Standards within the last 90 days, your service may be subject to a lower limit of up to 5 opt-in requests per user over a 7 day period. Page admins can check if their Page has a recent Community Standards strikes in the Page Quality Tab

  • Do not send duplicate opt-in requests to users

These requirements and limitations are subject to change as we are always striving for the best user and business experience.

Recurring Notifications Opt-In

Pages must obtain opt-in from users before sending them Recurring Notifications.

Pages must not send more than one opt-in request to a user per week on the same, specific topic. This applies even if the opt-in request is for a different frequency on the same topic. If Pages attempt to send an opt-in request to a user for the same topic in less than a week, the app will receive an error message with error code 613 and the request will not be sent. In addition, there must be an open 24 hour messaging window before a Page can send an opt-in request to the user. Users can opt-in to receive Recurring Notifications for multiple topics in the same thread.

A Recurring Notification opt-in request is sent to the user using the Send API as follows:

Request

{ 
     "recipient": {
          "id": "<PSID>"
        },
        "message": {
           "attachment": {
           "type": "template",
              "payload": {
              "template_type": "notification_messages", 
              "image_url": "<IMAGE_URL>",
              "title": "<TITLE_TEXT>",
              "payload": "<USER_DEFINED_PAYLOAD>",
              "notification_messages_frequency": "[DAILY|WEEKLY|MONTHLY]",
              "notification_messages_reoptin": "[ENABLED|DISABLED]",
              "notification_messages_timezone": "[TIMEZONE ID]" 
           }
        }
     }
 }

notification_messages_reoptin can be set as part of the opt-in template to ENABLED or DISABLED for the Re Opt-In process. This gives Pages the option of whether or not to continue sending opt-in messages to the user. This field is optional and the default value is ENABLED.

notification_messages_timezone can be set by Pages which determine when they can send Recurring Notifications after user opt-in. If Pages do not specify a timezone, the default timezone is UTC. Please see below for a list of valid time zones.

Time Zones

Response

{ 
        "recipient": 
        "id": "<PSID>",
        "message_id": "<MID>"      
}

Recurring Notification opt-in requests are subject to rate limits to help ensure the best user experience. We actively monitor the number of opt-in requests sent to a user. If we determine a Page exceeds the request limit then API calls from the app will fail with error code 9.

Opt-In Webhook Notification

There are two scenarios for which the app will receive this webhook notification:

  1. When the user opts-in to receive Recurring Notifications based on a set frequency such as "Get Weekly Messages"
  2. When the user clicks on the Continue messages button just before the token expires. The webhook notification will have the user_token_status set to REFRESHED and the token_expiry_timestamp extended
{
  "sender": {
    "id": "<PSID>",
  },
  "recipient": {
    "id": "<PAGE_ID>",
  },
  "timestamp": "<TIMESTAMP>",
  "optin": {
    "type": "notification_messages", 
      "payload": "<USER_DEFINED_PAYLOAD>",
      "notification_messages_token": "<NOTIFICATION_MESSAGES_TOKEN>", 
      "notification_messages_frequency": "[DAILY|WEEKLY|MONTHLY]",
      "notification_messages_timezone": "[TIMEZONE ID]",
      "token_expiry_timestamp": "<TIMESTAMP>",
      "user_token_status": "[REFRESHED|NOT_REFRESHED]"
    }
}

Sending Recurring Notifications After User Opt-In

After user opt-in, depending on the frequency of the Recurring Notification, this is how often notifications can be sent to the user:

Daily Recurring NotificationsWeekly Recurring NotificationsMonthly Recurring Notifications

Once every calendar day which starts from 12:00am until 11:59pm in the time zone set by the Page. Default time zone is UTC

Once every calendar week which starts from Monday at 12:00am until Sunday at 11:59pm in the time zone set by the Page. Default time zone is UTC

Once every calendar month which starts from the 1st at 12:00am until the last day of the month at 11:59pm in the time zone set by the Page. Default time zone is UTC

For example, if the user opted-into receiving weekly Recurring Notifications, and the Page set the time zone to America/New_York, this is a possible schedule of Recurring Notifications sent by the Page:

  1. First Recurring Notification sent on Monday @ 5:00 PM EDT

  2. Next Recurring Notification sent on Tuesday the following week @ 9:00 AM EDT

A Recurring Notification message token is generated per opt-in which can then be used to send Recurring Notifications.

If the user opted-in to both daily and weekly Recurring Notifications, two separate notification message tokens are generated. If the user opted-in to daily, weekly, and monthly Recurring Notifications, then three separate notification message tokens will be generated.

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient": {
    "notification_messages_token": "<NOTIFICATION_MESSAGES_TOKEN>"
    },
  "message": {
    "text": "<MESSAGE_CONTENT>"
    }
  }'
  "https://graph.facebook.com/v13.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"

You can also send rich messages by replacing text with rich content. For a complete list of supported message types, refer to Send API Reference.

Testing Recurring Notifications

Developers can test sending Recurring Notifications using the Enable Recurring Notifications feature.

This feature of enabling Recurring Notifications can be tested only if the recipient has one of these roles on the app: Administrator, Developer, or Tester.

Pages can bypass the frequency set in notification_message_frequency to send a second Recurring Notification right after the first one. This makes it possible to immediately test sending Recurring Notifications regardless of the set frequency.

To enable Recurring Notifications:

  1. A Page sends a Recurring Notification opt-in template to a user who has either a Administrator/Developer/Tester role on the app
  2. In this example, notification_message_frequency is set to WEEKLY, so the user receives an opt-in template with “Get weekly messages” on Messenger. Click on that button.
  3. Send the first Recurring Notification to the user
  4. To send another Recurring Notification immediately rather than waiting for a week make the following API call:

    Request

    curl -X POST -H "Content-Type: application/json" -d '{
      "recipient": {
        "notification_messages_token": "<NOTIFICATION_MESSAGES_TOKEN>"
        },
       "developer_action": "ENABLE_FOLLOWUP_MESSAGE"
      }' 
      "https://graph.facebook.com/v13.0/me/notification_messages_dev_support?access_token=<PAGE_ACCESS_TOKEN>"

    Response

    {"success": true}
  5. Now send another Recurring Notification to the user

You can continue to test sending Recurring Notifications that bypass the set frequency by repeating these steps.

Get Token Information

Apps can use the GET request to obtain more details such as the recipient ID or the frequency of the Recurring Notifications token.

Request

curl -X GET 
"https://graph.facebook.com/v13.0/notification_messages_<NOTIFICATION_MESSAGES_TOKEN>
?access_token=<PAGE_ACCESS_TOKEN>"

Response

{
  "notification_messages_token": "<NOTIFICATION_MESSAGES_TOKEN>",
  "recipient_id": "<PSID>",
  "payload": "<USER_DEFINED_PAYLOAD>",
  "notification_messages_frequency": "[DAILY|WEEKLY|MONTHLY]",
  "creation_timestamp": "<TIMESTAMP>",
  "token_expiry_timestamp": "<TIMESTAMP>",
  "user_token_status": "[REFRESHED|NOT_REFRESHED]",
  "notification_messages_reoptin": "[ENABLED|DISABLED]",
  "notification_messages_timezone": "[TIMEZONE ID]"
}

Manage Opt-In

Once users opt-in, they can easily manage their Recurring Notifications, including stopping and resuming them, by clicking the “Manage” button:

A webhook notification with the notification_message_status field denoting whether the user stopped or resumed notifications is sent to the app:

{
"sender": {
    "id": "<PSID>",
  },
  "recipient": {
    "id": "<PAGE_ID>",
  },
  "timestamp": "<TIMESTAMP>",
  "optin": {
    "type": "notification_messages", 
      "payload": "<USER_DEFINED_PAYLOAD>",
      "notification_messages_token": "<NOTIFICATION_MESSAGES_TOKEN>", 
      "notification_messages_frequency": "[DAILY|WEEKLY|MONTHLY]",
      "notification_messages_timezone": "[TIMEZONE ID]",
      "token_expiry_timestamp": "<TIMESTAMP>",
      "user_token_status": "[REFRESHED|NOT_REFRESHED]",
      "notification_message_status": "[STOP_NOTIFICATIONS|RESUME_NOTIFICATIONS]"
    }
}

If the app tries to send Recurring Notifications after a user has chosen to stop receiving them, it will receive an error message with error code 10.

Pages can only see if the user has opted-in to receive Recurring Notifications. We currently do not share other conversation data to protect user privacy. In the future we will explore how to help Pages understand their Recurring Notification performance metrics.

Re Opt-In

Just before the token associated with the Recurring Notification opt-in is about to expire, users will receive a re opt-in request. Users will then have the choice of whether or not to continue receiving the Recurring Notifications.

Based on the Recurring Notification frequency the user had opted into, this is when a re opt-in request is sent:

Recurring Notification FrequencyRe Opt-In Request Sent

Daily

After six months

Weekly

After nine months

Monthly

After twelve months

Testing Re Opt-Ins

Developers can test sending re opt-ins by making the following API call:

This re opt-in request feature can be tested only if the recipient has one of these roles on the app: Administrator, Developer, or Tester.

Request

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient": {
    "notification_messages_token": "<NOTIFICATION_MESSAGES_TOKEN>"
    },
   "developer_action": "SEND_RE_OPTIN"
    }' 
    "https://graph.facebook.com/v13.0/me/notification_messages_dev_support?access_token=<PAGE_ACCESS_TOKEN>"

Response

{
   "success": true
}

Properties

recipient

Description of the notification recipient

Property Type Description

recipient.id

String

Page Scoped User ID (PSID) of the notification recipient which is generated through an opt-in entry point

Facebook Login integrations return user IDs that are app-scoped and will not work with the Messenger platform.

recipient.message_id

String

The unique ID for this message

message

Description of the notification recipient

Property Type Description

message.attachment

Object

An object describing attachments to the notification

message.attachment

Property Type Description

type

String

Value must be template

payload

Object

payload of the template

message.attachment.payload

Property Type Description

template_type


Required

String

Value must be notification_messages

image_url


String

The URL of the image to display in the template

title


Required

String

The title to display in the template. The character limit is 65

payload


Required

String

User defined payload

notification_messages_frequency


Required

Enum

enum {DAILY, WEEKLY, MONTHLY}


The enum values are defined as follows:

  • DAILY - send 1 notification on a daily frequency for a set period of 6 months
  • WEEKLY - send 1 notification on a weekly frequency for a set period of 9 months
  • MONTHLY - send 1 notification on a monthly frequency for a set period of 12 months

notification_messages_reoptin

Enum

enum {ENABLED, DISABLED}


The enum values are defined as follows:

  • ENABLED - send a re opt-in template to the user after the set period for Recurring Notifications ends
  • DISABLED - do not send a re opt-in template to the user after the set period for Recurring Notifications ends

optin

Property Type Description

type

String

Value must be notification_messages

payload

String

User defined payload

notification_message_token

String

Token used by the Send API to send recurring notifications

notification_messages_frequency

Enum

enum {DAILY, WEEKLY, MONTHLY}


The enum values are defined as follows:

  • DAILY - send 1 notification on a daily frequency for a set period of 6 months
  • WEEKLY - send 1 notification on a weekly frequency for a set period of 9 months
  • MONTHLY - send 1 notification on a monthly frequency for a set period of 12 months

token_expiry_timestamp

String

Expiration timestamp for the notification_message_token

user_token_status

Enum

enum {REFRESHED, NOT_REFRESHED}


The enum values are defined as follows:

  • REFRESHED - This is set when the user chooses to re opt-in to receiving Recurring Notifications after the token has expired
  • NOT_REFRESHED - Default value and is set when the user does not re opt-in to receiving Recurring Notifications after the token has expired

notification_message_status

This field is present only when the user stops or resumes Recurring notifications.

Enum

enum {STOP NOTIFICATIONS, RESUME NOTIFICATIONS}


The enum values are defined as follows:

  • STOP NOTIFICATIONS - User has clicked "Stop these messages"
  • RESUME NOTIFICATIONS - User has clicked "Resume these messages"

Error Codes

Code Error Message Description

4

Recurring Notifications - There has to be a minimum delay between 2 notifications for the given notification


error_subcode - 2018354

When a Recurring Notification bypasses the frequency set in the notification_messages_frequency field

9

User is performing too many actions


error_subcode - 2018352

When the Recurring Notification opt-in request limit has been exceeded

10

Application does not have permission for this action

error_subcode - 1404170

When the Page is temporarily restricted from sending Recurring Notification opt-in requests

10

(#10) This user has currently stopped notification messages for this topic

error_subcode - 1893015

When the Page sends a Recurring Notification after the user clicks on

"Stop these messages"

100

notification_messages_token is invalid

When the token entered is invalid

100

notification_messages_token has expired

When the token entered is expired

613

Scope of service exceeded: You may not send multiple opt-in requests with the same topic to a user.


error_subcode - 1893016

When a Page sends more than 1 opt-in request to the user on the same topic.

If a user receives this type of error through opting-in via Send to Messenger, you will need to inform the user on your website that an opt-in request was already sent to Messenger.

Support

If you encounter an issue that you are unable to resolve after troubleshooting, please contact Support and select API and Technical Support.