Facebook One Time Notification API

UPDATE: As of March 28, 2021, we have added a new integration to make interacting with unique Facebook Messenger features easier. This tool includes a Request One Time Notification task which eliminates the need to use a Custom Request. The below instructions will still work as described, but you can replace the Custom Request with the more user friendly Send One Time Notification Request documented here.

Starting March 4, 2020, Facebook started only allowing automated messages (Bots!) to communicate with a user within 24 hours of their last interaction with your bot. Prior to this date, you also had the opportunity to communicate one last time, fondly known as 24+1, to attempt to re-engage them, any time outside of that 24 hour window.

On March 4, 2020, that free re-engagement message was removed, and a new permission-based feature replaced it, called the One Time Notification API. 

This feature restores the 24+1 capability, but ONLY after you have received permission from the user to do so. The way it works is this:

  1. Your user engages with your bot for the duration of some conversation. You want to be able to re-engage them later as part of your marketing sequence, maybe a 48 hours later, or one week later, or whenever an event happens, like an event being scheduled that your users are interested in.
  2. You send the user a very specifically formatted request for permission to notify them. It has a short title, and a button that says "Notify Me". When they click this button:
  3. Facebook will send a code, which must be stored and included with the next message you send outside the 24 hour window.
  4. You can use that code once and only once. If they re-engage with with the message you send, you can ask them for permission again. So you can continuously communicate with your users, even after long periods of time, but only if they engage with your message and only if they give you explicit permission to send the next message.

This Facebook update, and the context surrounding it, was documented very nicely by our friends over at Chatimize: https://chatimize.com/one-time-notification/

IMPORTANT NOTE: Before you go any further, you should enable One Time Notifications on your Messenger Settings of your Facebook page(s):

Although the language on the settings page suggests you have to request access, requesting access is just confirming you understand the feature is in beta. 

Using the One Time Notification API in Flow XO

We have implemented support for the One Time Notification API in Flow XO using the Facebook Actions integration (you will find it under More Services). I'll walk you through how to set it up now, but if you prefer to just dig in and play around, here are the two flows you can install and try out:

Request and Store a One Time Code

Broadcast using One Time Code

We'll go through these flows in detail. Here are the important pieces of the overall structure:

1. Requesting a Code

  • Ask the user for permission to notify them of something later using a custom request
  • Wait for them to click Notify Me, and store the resulting code in a user attribute

2. Sending a message after 24 hours

  • Trigger a broadcast, using a filter to only select those who have a notification token stored
  • Send the user a message that prompts them to engage with your bot.
    This is extremely important: you can only send ONE message to the user using your notification code. That means you cannot send them a sequence of short phrases and a question, or send a card and then a follow up question. You must prompt the user to engage with your bot with a single message. That means you should send an interactive message with choices that have a high chance of prompting your user to choose on of your quick replies, type a response, or click a button in a card
  • Clear the attribute where you originally stored the notification token. It can only be used once, so you want to make sure you clear it so that next time you broadcast, if the user hasn't provided you with new permission, they will be excluded from the broadcast. 
  • Ask the user for permission to notify them again later using a custom request
  • Wait for them to click Notify Me, and store the resulting code in the same user attribute

Something to Keep in Mind: Alternative Contact Channels

While it isn't demonstrated in the sample flows, a very good strategy is to collect an e-mail or a phone number from your user at the earliest moment you believe they may be likely to provide this information. This is because there is (obviously) no limit to how and when you can send an SMS or e-mail message to your users - if you fail to get their consent for a new Facebook notification, you can easily send them an e-mail or an SMS message with a link to your Messenger bot, which, if they click it, will cause them to re-engage and open up the 24 hour messaging window.

An elegant way to arrange this is to have TWO broadcasts - one that sends messages in Messenger filtered to those with a notification token in their attributes, and the other to send an SMS or e-mail filtered to users that do not have a notification token in their profile, encouraging them to engage with your messenger bot.

Now, at long last, let's walk through the flows...

Flow # 1 - Requesting a One Time Notification Request Token

We'll leave up to you to examine most of these steps, as they are just routine chat elements. Two however, we'll take a closer look at. Let's start with the Custom Request to send a Notify Me button:

The only thing you have to set on this step is the Request JSON. And the only thing you need to configure in that JSON is the "title" and the "payload". You must have SOMETHING in the payload, but wasn't doesn't usually matter except in an advanced scenario. If you want to copy and paste the custom request code:

{
  "attachment": {
      "type":"template",
      "payload": {
        "template_type":"one_time_notif_req",
        "title":"--> YOUR TITLE GOES HERE <--",
        "payload":"anything_you_like"
      }
   }
}

The next step, Wait for a Request, requires no configuration at all, unless you want to customize the expiration timeout/messages. This step simply acts to turn a non-question, such as Send a Custom Request, Send Card, etc, into a Question that can capture input.

After the user has responded, the Wait for a Response step will be completed with two values in its Metadata (note this screenshot is from the Interaction log, after this flow has run successfully, you will NOT see it when setting up the flow in the editor):

This is the value you need to store in a user attribute. We'll do that in the next step:

In this step, you need to save the 

fb_optin_one_time_notif_token

metadata value from the Wait for a Response step into the users attributes:

And...that's it for the flow that requests the one time token. In the sample, we send a final message saying "Thanks" - and you can do anything you want in the rest of your own flow. The hard part is done.

A note on multiple tokens and attribute names

You can use any name you want when storing the attribute. In the sample, we called it "my_topic_notification_token" - in order to demonstrate that a user can have any number of one time tokens. A good strategy is to name each token along with the type of broadcast or message you want to receive. If you only plan on having ONE long lasting conversation with your user, you could just as well name it simply "notification_token". It's entirely up to you

Now, for part two - using the token:

Flow # 2 - Using a One Time Notification Request Token

This flow is a little longer, but it's really very simple. We are simply sending an interactive message (in this case a Question, but you can also use any combination of Card/Card Set/Messge/Image etc coupled with a Wait for a Response. The important thing is, before you send ANY other messages, you get the user to respond - or your flow will fail because your token only works for ONE message).

It's also good practice to request a new token once you have re-engaged the user, for next time. Here is where you configure the token on the re-engagement message:

You will have stored your notification token in the users attributes, which are always included in the attributes of each trigger.  So for your re-engagement messages, you will simply expand the "Configure a one time notification token" area of your message, and fill in the resulting field with the attribute value that holds your token.

That's it! Happy notifying. While it is definitely more complicated than it used to be, this method is the only safe way to continue to message your users with promotional material outside of the 24 hour messaging window. Please be sure to reach out to support@flowxo.com for any help you may need in implementing this approach. Here is a video of this technique in action:

https://share.getcloudapp.com/DOu8oGpP

Thanks for reading!

Your friends at support@flowxo.com

Still need help? Contact Us Contact Us