Marketing Messages

This document shows you how to request permission from a person to send marketing messages, about the specific requirements and limitations for sending requests, and how to create and send marketing messages permissions requests.

Overview

Marketing Messages allows a Facebook Page or Instagram Professional Account to send messages outside the standard messaging window for people who have given you permission to do so. Marketing Messages allow you to build relationships with people who are interested in you or your business.

Marketing Messages is a new, optional premium feature that we intend to charge for in the future. We currently charge businesses to send messages from the WhatsApp Business API and listen 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.

Requirements

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

• You may only send a request for a user to opt in to Marketing Messages within the standard messaging window. A user’s action of opting in to Marketing Messages does not open the standard 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 Marketing Messages, including opt in requests, to spam users. This includes sending duplicate opt in requests at high frequencies to the same user or users 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 Marketing Messages in order to maintain the scope of service we are providing you

Limitations

• You can only send one opt in request per week with the same, specific title to a person. This includes the default value of "Updates and promotions".
• Do not send duplicate opt in requests to a person. A duplicate opt in request is defined as having the same title for notifications from a Facebook Page or the same title and image_url for notifications from an Instagram Professional account
• You can only send in opt in requests during the standard messaging window
• If a person opts in to marketing messages, this action does not open a standard messaging window
• You can only see if a person has opted in to receiving marketing messages but not the statuses for pending opt in requests
• If a person has chosen to stop receiving marketing messages, your notifications will no longer be delivered to that person and you will receive an error
• A person can block, mute, or report your messaging
• For marketing message sent from an Instagram Professional account, generally, up to 10 opt in requests for different titles 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.

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

Best Practices

You should send people relevant, valuable Marketing Messages, 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 Marketing Messages 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 Marketing Messages the user can expect to receive

Marketing Messages 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 Marketing Messages. You should regularly review your opt in requests and Marketing Messages to see if they meet the best practices above.

Message Frequency

Applies to notification message tokens created before February 2, 2023.

• After a person opts in, you can send the person messages on a daily, weekly, or monthly cadence depending on which cadence the person selected during opt in.

Request Permission to Send Marketing Messages

A person must give permission, opt in, to receive marketing messages from your Facebook Page or Instagram Professional account. The Messenger Platform offers multiple ways for you to get opt in. You can build opt in requests into the following messaging experiences:

• Ads That Click to Messenger – when a person clicks your ad
• Checkbox Plugin – when a person clicks the checkbox in a from and submits the form
• m.me Links – when a person clicks your m.me link on your website, emails, social media posts, and more
• Private Replies – when a person publishes a visitor post or comment to your business' Facebook Page
• QR Codes – when a person scans your QR Code on digital and print surfaces (supported by m.me Links)
• Send to Messenger Plugin – when a person inititates a conversation using a list of predefined CTA buttons or text

Sample Opt In Request

To send a marketing message opt in request, send a POST request to the /PAGE-ID/messages endpoint with the message template type set to notification_messages. The Page ID is the ID for your Facebook Page or the Facebook Page linked to your Instagram Professional account.

Note: The title parameter is required for marketing messages that contain a carousel from your Facebook Page or Instagram Professional account .

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"

On success, your app receives the following JSON response which includes a IDs for the recipient and the message.

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

Message Attachment Object Reference

A message attachment JSON object must be included in the POST request to the /PAGE-ID/messages endpoint for a marketing message opt in request.

Notification Message Tokens

When a person opts in, your business will receive a messaging_optin webhooks notification with a notification message token and information such as message title and timezone of the person who opted in. The notification message token allows you to send marketing messages to the person.

Opt In Webhook Notification

{
  "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"
    }
}

Token expiration dates will be extended for people who choose to stay opted in to receiving marketing messages. People can opt out at any time.

Opt In Followup Messages

Once a person has opted in to receiving marketing messages, you can send up to three followup messages. These messages must be sent within two minutes of the first followup message. The second and third followup messages can not exceed 250 characters. These followup messages can be sent outside the standard 24 hour messaging window.

To send a followup message, send a POST request to the /PAGE-ID/messages endpoint with the recipient object containing the notification message token and message object containing the text of the followup messages. The syntax for the API requests for all three followup message is the same.

Sample Request

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"

Get a List of Tokens

To get a list of all valid notification message tokens send a GET request to the /PAGE-ID/notification_message_tokens endpoint.

Sample Request

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

A list of up to 25 tokens is returned by default and are ordered by updated time. To read more you can add the limit parameter. Currently, there is a limit of 100 tokens that can be returned. You can use the after parameter for pagination however the before parameter is not available.

On success, your app will receive the following JSON response including the token, the recepient ID either an Instagram-scoped ID or Page-scoped ID, the time when the token was created, the title for the notification, and the time at which you can send the next marketing message to that recipient.

{
  "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"}
}

Get Token Information

While we recommend using the messaging_optin webhook to gather marketing message information, you can send a GET request to the token endpoint where your token is appended to notification_messages_, notification_messages_NOTIFICATION-MESSAGES-TOKEN, to get token information.

Sample Request

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

On success, your app will receive the following JSON response which includes the notification messages token, the ID for the person receiving the message, and other token information. You will use the notification messages token and recipient's ID send marketing messages.

{
  "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
}

These API calls will count against your app's rate limit.

Send a marketing message

Before You Start

You will need:

• The notification message token of the person who has opted in to receiving notifications
• The ID for your business' Facebook Page
• A Page access token requested from a person who can perform the MESSAGING task on the Page
• The pages_messaging permission, using Facebook Login
• Any assets to include in the marketing message
• The messaging_referrals webhook subscription for your app

To send a marketing message, send a POST request to the /PAGE-ID/messages endpoint with the recipient NOTIFICATION-MESSAGES-TOKEN value and message information in the message attachment.

Limitations

• You can only send one message per day per notification message token. If you are sending multiple messages be sure to delay subsequent messages by 24 hours or you will receive an error. (Does not apply to Opt In Followup messages.)

Recommendations

• We strongly recommend referring to a recipient's timezone when sending marketing messages to ensure messages are recieved at an appropriate time for the recipient.

Sample Request

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"

Upon success your app will receive the following response:

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

Test Marketing Messages

You can test your marketing messages at any time.

Before You Start

You will need:

• A person, the tester, to receive the notification. This person must have a role on the app.

Test Opt Ins

You can test your marketing messages at any time by following these steps.

• Step 1. Send your tester a message with a marketing message opt in template.
• Step 2. Make sure the tester clicks the opt in button, such as Receive 50% off sales messages, in the conversation.
• Step 3. Send the first marketing message to your tester
• Step 4. Send another marketing message immediately after the first with the developer_action parameter set to ENABLE_FOLLOWUP_MESSAGE.
• Step 5. Send another marketing message to the tester, this is your test message.

Sample Request

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"

On success, your app will receive the following JSON response containing success set to true.

{ "success": true }

To test re-opt ins, repeat the steps with the developer_action parameter set to SEND_RE_OPTIN in Step 4.

Next Steps

• Messaging Opt In Webhooks Notification
• Visit the Message Types overview to learn about the different types of messages you can send.

See Also

• The Page Messages Reference for more information on available fields for recurring messages.
• A list of available Time Zones
• Error Codes for Messenger Platform