Messenger Actions

Methods

Messaging: Send a Message, Send an Attachment, Send Button Template, Send Generic Template, Send Media Template
One Time Notifications: Send One Time Notification Request
Handover Protocol: Send to Inbox, Give Thread Control, Take Thread Control, Get Thread Owner

Overview

One of the great things about Flow XO is that you can build bots that will work the same across multiple channels, such as Telegram, Facebook Messenger, or WhatsApp. To enable this "build once deploy anywhere" functionality, we must limit the capabilities of our core messaging tools to features that are shared by all of the channels we support. This is great if you're building for multiple channels, but it can be limiting if you want to take full advantage of a particular platform, such as Facebook Messenger.

User Friendly Access to the Facebook Messenger API

Flow XO has always allowed users to take advantage of most of each channels special features using our Custom Request action. This allows you to call a particular channels API using raw JSON code. It works, but it requires some technical skill and makes it very easy to make mistakes. So while we still provide the option of sending a Custom Request for highly technical Facebook Messenger power users, we now offer a much more user friendly way to access Messengers features, the Messenger Actions integration. You can find this powerful tool under More Services, along with our third party integrations and chat utilities.

Filtering By Platform

Since the methods in this integration will ONLY work on Facebook Messenger, you can only use them in a flow that you only intend to deploy to Facebook Messenger OR you use a filter to only execute the task when the current channel is Facebook Messenger. Each trigger provides a 'Bot Platform' field that can be used for this purpose:

Messaging Actions

The messaging actions let you send different kinds of messages to your users, from simple messages to cards with titles and images. Most of the functionality available in the messaging actions is also available using our normal Send a Message, Send an Image, etc. However, the messaging tools in this integration do expose certain options unique to Facebook messenger, including:

Present the user with a quick reply button pre-populated with their email address to make it easy for them to share their email address with you
Present the user with a quick reply button pre-populated with their phone number
Include an image as an icon in quick replies
Ask Facebook to store an image on its servers and re-use the image using an Attachment ID. This can be useful if you have a bigger image or are doing high volume messaging, as Facebook Messenger will occasionally fail to download third party images, causing a flow to fail, or be slower than it would be if Facebook could use its own image cache.
Provide the user with a phone call button that they can click to initiate a phone call on a mobile device
Provide the user with a log-in button that can log them into your custom application
Send different kinds of attachments besides simple images and videos, such as audio and general purpose files.

Quick Replies

The Send a Message and Send an Attachment actions allow you to specify up to 13 quick replies with each message. These are exactly the same as the Shortcuts in our normal Send a Message action, except they have some special options not available in the standard action:

Ask the User for their email
Using the text 'user_email' for a Quick Reply label will create a quick reply button pre-populated with the users e-mail address.

Ask the User for their phone number
Using the text 'user_phone_number' for a Quick Reply label will create a quick reply button pre-populated with the users phone number.

Use a Quick Reply Image
Putting a url of an image in square brackets after the label text in a Quick Reply label will cause the image to be used as an icon on the quick reply button. For example:

Image Shortcut [https://static.thenounproject.com/png/90031-200.png]

Buttons

The Send Button Template and Send Generic Template allow you to send the user up to three buttons they can click. Unlike quick replies, the buttons do not disappear once clicked. You can include a label and a data value for the buttons, but you can also use a URL as the button value to make the button into a web link, and you can prefix the value with phone_number to make the button a 'Call' button which will interact with the users phone to give them the option to immediately initiate a phone call.

If you have a custom app integrated with Facebook authentication, you can also make a button into a login button by prefixing the login url with account_link, for example account_link:https://www.myapp.com/login or using the text account_unlink as a label value.

Getting User Input

When using the usual Flow XO messaging tasks, if you want to gather input from the user you would use an Ask a Question task. This send the user a message, some optional quick reply options, and then pauses the flow until the users responds. Once they do, the data they sent is available as an output of the Ask a Question.

The Messenger Actions integration does not have a concept of an Ask a Question, but it DOES give you the ability to prompt the user for input in more ways than Ask a Question, using special Quick Replies for example or a Button Template. To gather user input in these contexts, please use the Wait for a Response task. It behaves exactly like Ask a Question, except that it is lacking the validation features. You will have to handle any validation on our own.

As an added bonus, we have modified how file attachments are processed, and you can now ask your user to submit a file and then place a Wait for a Response action immediately afterwards. When your user uploads the file, be it an image, a video, a contact, or any other media that their messenger can send, the Wait for a Response action will capture the file info as metadata. It is no longer necessary to have separate flows and New File Triggers to collect uploads from users!

You can use this to collect media from your users and then grab the File ID from the received metadata and post that media in another group or channel, or you can simply store the file URL in a database for later use.

Send a Message

Send a text message, with up to 13 optional Quick Reply buttons.

Send an Attachment

Send a media file such as an image, video with up to 13 optional Quick Replies. You can also send an audio file or a generic file attachment like a PDF, but note these functions are not currently available in the EU and will fail if used there.

Getting an Attachment ID
When you send an attachment, you can set the "Is Attachment Reusable" button to instruct Facebook to store the attachment on their server and return an Attachment ID which you can subsequently use in a Send Media Template for increased performance and stability.

You can combine this feature with a New File Trigger to easily create an internal helper flow that allows you to upload images to Facebook via your Messenger bot and returns the Attachment ID for later use.

Send Button Template

Send a message with a set of up to three buttons to your users, along with a text message. To see more about the kinds of buttons you can send, please see the section on Buttons earlier in this document.

Send Generic Template

Sends a card with an image, a title and subtitle, and up to 3 buttons. To see more about what kinds of buttons you can send see here. The Generic Template also can be configured with a "Default Action" url which the user will be directed to if they click on the card itself rather than one of the action buttons.

Send Media Template

Send Media Template allows you to send a photo or a video along with an optional button.. The Media Template will ONLY allow you to use a Facebook URL or an attachment ID - you are not permitted to use files hosted off Facebook for this template. You can read more about this template here: https://developers.facebook.com/docs/messenger-platform/send-messages/template/media

One Time Notifications

As you may know, Facebook only allows you to send messages to your users within 24 hours of the last message they sent to your bot. There are a few exceptions, but they aren't relevant for most people using bots for promotional (marketing) purposes. Facebook provides a mechanism where you can gain one chance to re-engage your users after the 24 hour window. It is called the One Time Notification API, and the way it works is that you request permission from your user to contact them at some point in the future using a special kind of Messenger template. If they agree, you will get a code which you can use, as the name of the features suggests, exactly one time to send them a message outside of the 24 hour messaging window. You will not be able to send them another message until they engage with your bot, so it is VERY important that the one message you send is engaging and elicits a response, using a quick reply or a button or any other kind of prompt. You can use the Request a One Time Notification Token task to request permission for the one time notification from your user. NOTE: You have to opt in to the One Time Notification API and accept Facebooks terms. You can read about how to do that here: https://support.flowxo.com/article/235-facebook-one-time-notification-api.

The "payload" field will be sent back with the notification approval. Once yo use the One Time Notification, you should include a Wait for a Response task immediately after to collect the response. When the user clicks Notify Me, you will get the following fields returned as metadata:

The fb_optin_one_time_notif_token should be extracted from the metadata and stored as a user attribute for later use:

You can use whatever attribute name you want, but the important thing is to store the token in the user attributes for later. When you are ready to send your update, you will read the token from the user attributes and include it with your update message:

You should then update the attributes one more time to clear the token from the user record so that you don't attempt to use it again as any future use will fail.

Handover Protocol

Facebook provides a handy feature to transfer control of a conversation to another app to handle live-agent support scenarios. You have the option to send a conversation to the Facebook Inbox, or to another application that implements the handover protocol. Once you configure a page to use the Handover protocol, then new conversations will no longer show up in your Inbox, they will automatically be placed in the closed folder. You can then opt to move them to the inbox for human interaction, and when you are done move the conversation back into the closed status which will give control back to Flow XO for automated flows. For instructions on how to implement this, please see here: https://support.flowxo.com/article/237-facebook-handover-protocol

Send to Inbox

This command will transfer control of a conversation to the Facebook inbox. If you decide to use the Facebook Inbox for your live chat rather than our built in Live Chat feature, this is the command you would use.

Give Thread Control

Give Thread Control can be used to transfer thread control to a specific secondary app, like Sprinklr. You have the option of providing a custom data element in the "metadata" field that will be sent to the secondary app along with the notification of thread control.

Take Thread Control

Take thread control will immediately return thread control back to Flow XO. Since Flow XO must be set up as the primary app, it has the ability to seize thread control at any moment. You can use this command after a delay to automatically clean up any conversations you forget to move out of your inbox.

Get Thread Owner

This command will query Facebook and return information in the metadata showing which app currently has thread control. This can be helpful for troubleshooting handover issues.