ActionFrames, Events and AutoReplies

The FB-BotMill framework architecture is based on ActionFrames. An ActionFrame is a made up by an Event (Facebook's Messenger Platform callbacks) and and an AutoReply (developer-defined replies to that event).

Basically, an Event tells when the FaceBot should reply, an AutoReply tells how the FB-BotMill should reply and the ActionFrame wraps all this together, adding the possibility of implementing extra logic before and after the reply is sent.

Event

An Event defines wheter the FB-BotMill should reply to an incoming callback or not. Each Event implements the FaceBotEvent interface. This interface is defined as follow:

public interface FBBotMillEvent {

/**
 * A method which evaluates whether the event is verified or not.
 * 
 * @param envelope
 *            the callback message.
 * @return true if the event is verified, false otherwise.
 */
public boolean verifyEventCondition(MessageEnvelope envelope);

}

The verifyEventCondition method takes as an input the incoming callback from Facebook Messenger Platform and returns a boolean that indicates wheter the callback should be handled or not.

The FaceBot frameworks offers some basic implementation of this interface:

• AnyEvent: evaluates to true at each callback.
• AnyMessageEvent: evaluates to true at each message callback (i.e. each time a user writes a message in Messenger chat).
• MessageEvent: evaluates to true if a message callback contains an exact text. Can be either case sensitive or insensitive.
• MessagePatternEvent: evaluates to true if a message callback matches against a regex pattern.
• AnyPostbackEvent: evaluates to true at each postback callback (i.e. each time a user interacts with UI elements like buttons).
• PostbackEvent: evaluates to true if a postback callback contains an exact text. Can be either case sensitive or insensitive.
• PostbackPatternEvent: evaluates to true if a postback callback matches against a regex pattern.

If you want to know more about callbacks, you can read the official Facebook documentation.

AutoReply

An AutoReply incapsulates the logic which creates a reply from a FaceBot to a user. Each AutoReply extends the abstract class AutoReply. This class contains an abstract method createResponse which you will override. The method is defined as follows:

/**
 * Method which defines the response to send back as a response to the
 * current message.
 * 
 * @param envelope
 *            the current message.
 * @return a {@link FaceBotResponse} which contains the response to the
 *         current message.
 */
public abstract FaceBotResponse createResponse(MessageEnvelope envelope);

It takes as argument the incoming callback and returns a FaceBotResponse object which represents the response that the FaceBot will return back to the user. It's recommended to use the ReplyFactory facility to produce the response to return, since it's designed to make easier to build a valid and well-formed response and also adds supports for testing. However, this is not compulsory since FaceBot gives the possibility to create your own response object with the provided model classes.

The AutoReply classes comes with a set of utility methods that you may use in order to process the response. They are the following:

• eventKind: returns the type of callback received.
• safeGetSender: returns the sender of the incoming message.
• safeGetRecipient: returns the recipient of the incoming message.
• safeGetSenderId: returns the sender ID of the incoming message.
• safeGetRecipientId: returns the recipient ID of the incoming message.
• safeGetPostbackPayload: returns the postback payload of the incoming message.
• safeGetMessage: returns the message text of the incoming message.

When using the sender/recipient methods, remember that the sender of an incoming message will be the recipient of your response in order to reply to that message. If you want to send a message at any moment to a user after the first interaction, you will need the pages_messaging_subscriptions permission on your Facebook app.

As for the Events, the FaceBot framework offers some basic implementations of the AutoReply class:

• MessageAutoReply: replies with a text message.
• AttachmentAutoReply: replies with an attachment (file, image, audio or video).
• ActionAutoReply: replies with a chat action. This may be start typing, stop typing or mark message as seen.
• EchoAutoReply: replies with the same text message written by the user. Useful for testing purposes.

If you want to know more about callbacks, you can read the official Facebook documentation.

ActionFrame

The whole purpose of an ActionFrame is to encapsulate logic that you want to execute before and after the reply is sent back to the user. In order to do so, you will need to extend the ActionFrame class and override this two methods:

/**
 * Executed before the reply is sent to the user.
 * 
 * @param envelope the incoming message.
 */
public void beforeReply(MessageEnvelope envelope) {
};

/**
 * Executed after the reply is sent to the user.
 * 
 * @param envelope the incoming message.
 */
public void afterReply(MessageEnvelope envelope) {
};

For example, if you want to save to a database the user message, you may create a DBActionFrame object that extends the ActionFrame and overrides the method afterReply (you want to return the reply to the user immediately, since DB communication is slow) in which you will save the data.