Using Facebook Messenger¶
Authors: Jack Urbanek, Kurt Shuster
In ParlAI, you can allow people on Facebook to participate in a ParlAI world as an agent.
Facebookers can be viewed as another type of agent in ParlAI, and hence person-to-person, person-to-bot, or multiple people and bots in group chat can all talk to each other within the same framework.
Facebook agents communicate in observation/action dict format, the same as all other agents in ParlAI. During the conversation, messages are delivered to a person’s inbox from the page that you have set up for ParlAI.
Each messenger task has at least one messenger agent that connects to ParlAI using the Facebook messenger Send/Receive API, encapsulated as a
Each messenger task also consists of a
World where all agents live and interact within.
Messenger tasks can be grouped together within an
Overworld which can spawn the subtasks and allow people to pick between multiple conversations.
The task definition resides in a config file,
config.yml, in which you specify all the available worlds, and any additional command line arguments.
Finally, to run a task, simple run the following command from the
python run.py --config-path /path/to/config
We provide three examples of using Facebook Messenger with ParlAI:
QA Data Collection: collect questions and answers from people, given a random Wikipedia paragraph from SQuAD.
Overworld Demo: let people select between three different subtasks, namely an echo bot, a demo of onboarding data collection, and a random chat.
Task 1: Testing a Model¶
Oftentimes it’s important to host a created model against humans to evaluate how well it is performing on a number of metrics. This generic ChatBot world allows you to attach a model to a page, and then users who interact with that page will be paired into a conversation with that bot.
As it is currently implemented, the collected conversations can be observed and rated manually by the ParlAI user. It’s possible to imagine requesting that the human participant rate their conversational partner at the end of the conversation as another way to evaluate the model.
To run a bot with this world, you’ll need to provide in the
config.yml file the same model opts you would use elsewhere in a ParlAI environment.
For instance, one can try testing a model trained on the ConvAI2 dataset with the following
tasks: default: onboard_world: MessengerBotChatOnboardWorld task_world: MessengerBotChatTaskWorld timeout: 1800 agents_required: 1 task_name: chatbot world_module: parlai.messenger.tasks.chatbot.worlds overworld: MessengerOverworld page_id: 1 # Configure Your Own Page max_workers: 30 opt: # Additional model opts go here debug: True model: legacy:seq2seq:0 model_file: models:convai2/seq2seq/convai2_self_seq2seq_model override: model: legacy:seq2seq:0
Then, you would simply run the world via the following command (while in
python run.py --config-path ../tasks/chatbot/config.yml
This code will allow users to talk with a bot in conversations like the one displayed above.
Task 2: Collecting Training Data¶
One of the biggest use cases of Messenger in ParlAI is to connect people and collect natural language data.
As an example, the QA Data Collection task does the following:
Pick a random Wikipedia paragraph from SQuAD dataset.
Ask a person to provide a question given the paragraph.
Ask the person to provide an answer to their question.
QADataCollectionWorld, there are two agents: one is the person (
MessengerAgent), the other is the task agent (
DefaultTeacher from SQuAD) that provides the Wikipedia paragraph.
turn_index to denote what stage the conversation is at. One turn means that
world.parley() has been called once.
After two turns, the task is finished, and the person’s work can be saved during the
Task 3: Exposing People to Multiple Tasks¶
ParlAI messenger can also be used to create a multi-function world that users can choose multiple tasks or variations for. This can be used to expose multiple versions of a chatbot you want to test, to allow users to choose what kinds of tasks they do, amongst other things.
As an example, the Overworld Demo displays three separate tasks connected together by an overworld.
echotask is a simple example of an echo bot, and shows the functionality and flow of a simple single-person world.
onboard datatask is an example that shows how an onboarding world can collect information that is later exposed in the active task world.
chattask is an example of a task that requires multiple users, and shows how many people can be connected together in an instance of a world and then returned to the overworld upon completion of a task.
Creating Your Own Task¶
To create your own task, start with reading the tutorials on the provided examples, and then copy and modify the example
config.yml files to create your task.
A few things to keep in mind:
A conversation ends when a call between
Your world can utilize the complete set of Facebook Messenger Templates by putting the formatted data in the ‘payload’ field of the observed action.
Quick replies can be attached to any action, the
MessengerOverworldof the Overworld Demo displays this functionality.
Tasks with an overworld should return the name of the world that they want to queue a user into from the
parleycall in which the user makes that selection to enter a world.
Tasks with no overworld will immediately attempt to put a user into the queue for the default task onboarding world or actual task world (if no onboarding world exists), and will do so again following the completion of a world (via
To collect the conversation, data should be collected during every
parleyand saved during the
world.shutdowncall. You must inform the user of the fact that the data is being collected as well as your intended use.
Finally, if you wish to use and command line arguments as you would in ParlAI, specify those in the
optsection of the config file.
Running a Task¶
ParlAI’s Messenger functionality requires a free heroku account which can be obtained here. Running any ParlAI Messenger operation will walk you through linking the two.
Running and testing a bot on the Facebook Messenger Platform for yourself will require following the guide to set up a Facebook App for messenger. Skip the set up your webhook step, as ParlAI will do it for you.
When the guide asks you to configure your webhook URL, you’re ready to run the task. This can be done by running the
run.pyfile in with python.
After the heroku server is setup, the script will print out your webhook URL to the console, this should be used to continue the tutorial. The default verify token is
On the first run, the page will ask you for a “Page Access Token,” which is also referred to on the messenger setup page. Paste this in to finish the setup. You should now be able to communicate with your ParlAI world by messaging your page.
To open up your bot for the world to use, you’ll need to submit your bot for approval from the Developer Dashboard.
Note: When running a new task from a different directory, the webhook url will change. You will need to update this in the developer console from the webhook settings using “edit subscription.” Your Page Access token should not need to be changed unless you want to use a different page.
Additional flags can be used (you can also specify these in the
--password <value>requires that a user sends the message contained in value to the bot in order to access the rest of the communications.
--force-page-tokenforces the script to request a new page token from you, allowing you to switch what page you’re running your bot on.
--debugshould be used before reporting problems that arise that appear unrelated to your world, as they expose more of the internal state of the messenger manager.