notice

This is documentation for Rasa Documentation v2.x, which is no longer actively maintained.
For up-to-date documentation, see the latest version (3.x).

Version: 2.x

Facebook Messenger

Facebook Setup

You first need to set up a facebook page and app to get credentials to connect to Facebook Messenger. Once you have them you can add these to your credentials.yml.

Getting Credentials

How to get the Facebook credentials: You need to set up a Facebook app and a page.

  1. To create the app head over to Facebook for Developers and click on My AppsAdd New App.

  2. Go onto the dashboard for the app and under Products, find the Messenger section and click Set Up. Scroll down to Token Generation and click on the link to create a new page for your app.

  3. Create your page and select it in the dropdown menu for the Token Generation. The shown Page Access Token is the page-access-token needed later on.

  4. Locate the App Secret in the app dashboard under SettingsBasic. This will be your secret.

  5. Use the collected secret and page-access-token in your credentials.yml, and add a field called verify containing a string of your choice. Start rasa run with the --credentials credentials.yml option.

  6. Set up a Webhook and select at least the messaging and messaging_postback subscriptions. Insert your callback URL, which will look like https://<host>:<port>/webhooks/facebook/webhook, replacing the host and port with the appropriate values from your running Rasa X or Rasa Open Source server.

    Insert the Verify Token which has to match the verify entry in your credentials.yml.

configure https

Facebook Messenger only forwards messages to endpoints via https, so take appropriate measures to add it to your setup. For local testing of your bot, see Testing Channels on Your Local Machine.

For more detailed steps, visit the Messenger docs.

Running On Facebook Messenger

Add the Facebook credentials to your credentials.yml:

facebook:
verify: "rasa-bot"
secret: "3e34709d01ea89032asdebfe5a74518"
page-access-token: "EAAbHPa7H9rEBAAuFk4Q3gPKbDedQnx4djJJ1JmQ7CAqO4iJKrQcNT0wtD"

Restart your Rasa X or Rasa Open Source server to make the new channel endpoint available for Facebook Messenger to send messages to.

Supported response attachments

In addition to typical text, image, and custom responses, the Facebook Messenger channel supports the following additional response attachments:

  • Buttons are structured the same as other Rasa buttons. Facebook API limits the amount of buttons you can sent in a message to 3. If more than 3 buttons are provided in a message, Rasa will ignore all provided buttons.

  • Quick Replies provide a way to present a set of up to 13 buttons in-conversation that contain a title and optional image, and appear prominently above the composer. You can also use quick replies to request a person's email address or phone number.

    utter_fb_quick_reply_example:
    - text: Hello World!
    quick_replies:
    - title: Text quick reply
    payload: /example_intent
    - title: Image quick reply
    payload: /example_intent
    image_url: http://example.com/img/red.png
    # below are Facebook provided quick replies
    # the title and payload will be filled
    # with the user's information from their profile
    - content_type: user_email
    title:
    payload:
    - content_type: user_phone_number
    title:
    payload:
note

Both Quick Reply and Button titles in Facebook Messenger have a character limit of 20. Titles longer than 20 characters will be truncated.

  • Elements provide a way to create a horizontally scrollable list up to 10 content elements that integrate buttons, images, and more alongside text a single message.

    utter_fb_element_example:
    - text: Hello World!
    elements:
    - title: Element Title 1
    subtitle: Subtitles are supported
    buttons: # note the button limit still applies here
    - title: Example button A
    payload: /example_intent
    - title: Example button B
    payload: /example_intent
    - title: Example button C
    payload: /example_intent
    - title: Element Title 2
    image_url: http://example.com/img/red.png
    buttons:
    - title: Example button D
    payload: /example_intent
    - title: Example button E
    payload: /example_intent
    - title: Example button F
    payload: /example_intent