Features

This Drupal module provides a tool to build a chat bot to work on Facebook's Messenger Platform.

Requirements

Drupal 8
PHP 5.6 or greater
Facebook App and Page

Installation

Enable the fb_messenger_bot module.
Visit /admin/config/fb-messenger and enter a custom value for the Facebook Verify Token (save the configuration).
Complete steps 1-4 outlined in Facebook's quickstart documentation including the copying of the page access token in step 3 (note: this module sets up the webhook at /webhook/contact).
Return to /admin/config/fb-messenger and paste the page access token into the Facebook Page Access Token field (save the configuration).
Clear caches.
Visit the Facebook page your app is subscribed to and send it a message. You should receive a response from the bot!

Customizing your bot

Note: You can use the demo_fb_messenger_bot folder as a starting point or reference.

In a custom module, create a custom workflow by creating a class that extends the FBMessengerBotWorkflow class.
Modify the fb_messenger_bot.workflow service to use your custom workflow by creating a class that extends ServiceProviderBase and implements the alter() method (documentation from d.o.).

Supported message types

As of right now, this module can handle sending text, button, generic, and video messages from Facebook's Send API.

Text message

$textMessage =  new TextMessage('Text Message!');

Button message

$buttonMessage = new ButtonMessage(
  array(
    new PostbackButton('Next Step', 'buttonMessage_Next'),
    new UrlButton('URL Button', 'http://www.example.com');
  )
);

Video message

$videoMessage = new VideoMessage('http://techslides.com/demos/sample-videos/small.mp4');

Steps

The meat of a workflow resides in its steps. Each step is an object responsible for providing the workflow with a human readable name (see Roadmap), machine name, and message(s) to send the user. In addition to those basics, steps need to indicate what the next step to go to in the workflow based on a user's response. Lastly, steps should provide a validation callback which will be invoked to validate the user's response to the step, as well as an invalid response message, which will be sent to the user in the event that the callback returns false.

Instantiating a step in your workflow

$stepHumanReadableName
$stepMachineName
$messageToSend = array(new TextMessage('Hi there!'));

// Set step welcoming user to conversation.
$welcomeStep = new BotWorkflowStep($humanReadableName, $stepMachineName, $messageToSend);

Adding response handlers

As mentioned above, every step needs to indicate the next step to go to based on a user's response to that step. This is achieved with response handlers.

$welcomeStep->setResponseHandlers(
  array(
    '*' => array(
      'handlerMessage' => NULL,
      'goto' => 'builtABot',
    ),
  )
);

In the example above, we indicate that regardless of what the user sends us (the asterisk), we want to proceed to the step in the workflow with machine name 'builtABot'. By indicating 'NULL' for the handlerMessage, we are saying we want to send whatever message text is configured in the builtABot step. If we want to override that behavior, we can simply set the handlerMessage value to be an array of messages(s) of type MessageInterface.

If you sent out a message with buttons, and want to route a user to different steps depending on which button they clicked, you would achieve that using response handlers:

$builtStep = new BotWorkflowStep('Built A Bot', 'builtABot',
  new ButtonMessage('Glad you stopped by for a chat. Have you ever built a chat bot?',
    array(
      new PostbackButton('Yep!', 'builtABot_Yes'),
      new PostbackButton("Nope!", 'builtABot_No'),
    )
  )
);

$builtStep->setResponseHandlers(
  array(
    'builtABot_Yes' => array(
      'handlerMessage' => NULL,
      'goto' => 'veteranBuilder',
    ),
    'builtABot_No' => array(
      'handlerMessage' => NULL,
      'goto' => 'neverBuilt',
    ),
  )
);

Step validation

Often times, you'll want to collect some sort of information from the user that requires validation prior to saving it. The module ships with a few validation callbacks you can use, but you're free to override them, and/or implement your own. These include:

text message (ensure the user sent text)
postback (ensure the user clicked one of the buttons you sent them)
zip code
e-mail
phone number (U.S.)

$validationFunction = $this->getTextMessageValidatorFunction();
$invalidResponse = $this->getGenericValidationFailMessage();
$welcomeStep->setValidationCallback($validationFunction);
$welcomeStep->setInvalidResponseMessage($invalidResponse);

Roadmap

Documentation Improvements

Add documentation on:

starting over a conversation
fetching and storing a user's info from Facebook
pre and post conversation process methods
handling trolling users

Enhancements and hopes

We'd love to:

Refactor as much of the code as possible to be usable in a general PHP context, outside of Drupal.
Convert objects to be Drupal entities where appropriate. Refactoring steps to being config entities, for example, would allow for configuration of steps by an admin.
Support multiple workflows (e.g. you could have a intro workflow with certain steps and then transition a user to a gather contact info workflow with a different set of steps etc.)
See you all fork and contribute to the module! (It would be great to see someone from the community polish the code and contribute it to drupal.org).

WhiteHouse/fb_messenger_bot