Messenger Platform

One-time Notification (Beta)

Summary

The Messenger Platform's One-Time Notification API (Beta) allows a page to request a user to send one follow-up message after 24-hour messaging window have ended. The user will be offered to receive a future notification. Once the user asks to be notified, the page will receive a token which is an equivalent to a permission to send a single message to the user. The token can only be used once and will expire within 1 year of creation.




Permissions

Pages interested in using this API need to apply for the “One-Time Notification” permission within the “Advanced Messaging” section of Page Settings. The page will need to agree to the beta terms and will be granted the permission if the page meets our criteria.




Contents

Usage

  • Don't confuse, deceive, defraud, mislead, spam or surprise anyone. Make sure that there is a clear and obvious relationship between the prompt, and the content of the message. The content of the one-time notification request and the message must comply with community standards.
  • Pages that receive high volumes of negative user feedback, or that confuse, deceive, defraud, mislead, or negatively surprise users will lose access to the API.

Sending One-Time Notification request

Using the Send API, the page can send a notification request message as a template. The template type should be one_time_notif_req. The body of the request follows a standard format for all template types, with the message.attachment.payload property containing the type and content details that are specific to each template type. You are only allowed to customize the title and payload of the request. The title field is limited to 65 characters.

{
  "recipient": {
    "id":"<PSID>"
  },
  "message": {
    "attachment": {
      "type":"template",
      "payload": {
        "template_type":"one_time_notif_req",
        "title":"<TITLE_TEXT>",
        "payload":"<USER_DEFINED_PAYLOAD>"
      }
    }
  }
}

The One-Time Notification request template template will be rendered and once the user clicks the Notify Me button, a message_optins webhook will be delivered to your backend and the one_time_notif_token can be used to send a one-time follow up message to the user outside of the 24hr period.

Sending follow up message

To send a follow up message, submit a POST request to the Send API, with one_time_notif_token obtained via webhook and message.text set in the request body:

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

To send a rich message, replace the text with rich content. Please refer to Send API Reference for the complete list of supported message types. The one_time_notif_token can only be used once and will be invalidated upon successful messsage send.

Webhook Events

When the user consents to be notified on a specific update, you will get a webhook event with the payload and one_time_notif_token. You will need to store both the payload and the token in order to send a follow up message when the information becomes available. Note that there will not be a separate API to query a list of one_time_notif_token, hence it is important that you process and store the webhook info as it is received. Each token can only be used once and will expire within one year of creation time.

{
   "sender": {
     "id":"<PSID>"
   },
   "recipient": {
     "id":"<PAGE_ID>"
   },
   "timestamp":1458692752478,
   "optin": {
     "type": "one_time_notif_req",
     "payload": "<USER_DEFINED_PAYLOAD>",
     "one_time_notif_token":"<ONE_TIME_TOKEN>",
   }
}

Restrictions and Limitations

  • Don’t use the payload field to send passwords, user credentials, information that personally identifies users (i.e., information such as name or email address that by itself can be used to contact a person or identifies who they are), or other sensitive information (such as health, financial, payment or cardholder data, or other categories of information defined as sensitive under applicable law).
  • The number of One-Time Notification request are subject to rate limit to avoid creating a bad user experience.

FAQ

You can find more information on our frequently asked questions page.

Developer Support