Facebook Messenger

With this node.js example connector for Facebook Messenger you can make your Teneo bot available on Facebook Messenger. This guide will take you through the steps of installing the connector (we will be using Heroku to host it) and connecting it to a business page on Facebook.

You can find the source code of this connector on Github.


Server that is available via https

Facebook requires that you have a server that is available via https. We will be using Heroku as an example here. If you prefer not to use Heroku, see Running the connector locally.

A Facebook Page

A Facebook page with a configured "Send Message" associated to your profile is necessary to host the conversation between users and a Teneo bot. Create a Page here. Fill in the required fields, and click "Add a Button", select 'Contact You' and activate the 'Send Message' checkbox. In 'Step 2' click 'Messenger' > 'Finish'.

Teneo Engine

Your bot needs to be published and you need to know the engine url.

Setup instructions

Create a new Faceboook app

Login to developers.facebook.com and create a new app.

After you have created the app, a new page appears called 'Add a Product'. On that page find the tile that says 'Messenger' and click the 'Set Up' button.

You have now added Messenger as a product to your Facebook app. Next you need to get a page token.

Generate a Facebook Page Token

Facebook Messenger bots need to be connected to businesses and those businesses need to be present on Facebook with a Facebook Page. For your bot to be able to respond to questions that are sent to your business Facebook page (via Facebook Messenger) you need to generate a page token. Scroll down to the section that say 'Access Tokens'. You can either select an existing Facebook Page or create a new Facebook (see prerequisites). Then, Activate 'Manage and Access Page conversations in Messenger'.

After you have selected the page, generate a token. Make sure you copy and store the page token in a safe place, because this is the only time it will be visible.

At this point, it is not necessary to submit any aspect of the facebook app for review, The in development status is enough to test your Teneo bot.

Deploy the connector to Heroku

Click the button below to create a new Heroku app that contains the connector:


  1. Give the app a name (lowercase, no spaces)
  2. In the 'Config Vars' section, add the following:
    • FB_PAGE_ACCESS_TOKEN: The page token you got from Facebook
    • FB_VERIFY_TOKEN: A random token of your choice. Make sure you remember it, you will need to enter it later when you finish the Facebook configuration
    • TENEO_ENGINE_URL: The engine url
  3. Click 'Deploy app'.

After the app has been deployed, choose 'Open app'. This will open a browser window (it will say show an error page 'Cannot GET /', but you can ignore that). Copy the url of the page and remember it, you will need to enter it later when you finish the Facebook configuration.

If you prefer to run your bot locally, see Running the connector locally.

Setup webhook on Facebook

Next we will need to setup the webhook. Scroll to the 'Webhooks' section and click on the 'Setup Webhooks' button. A window appears in which you need to provide a 'Callback URL' and a 'Verify Token'.

  • In the 'Callback URL' field paste your Heroku server url appended with /webhook/. It should look something like this: https://yourappname.herokuapp.com/webhook/
  • In the 'Verify Token' field, enter the verify token you declared when your started the Heroku app.
  • For Subscription Fields select: messages and messaging_postbacks.
  • Click 'Verify and Save'.
  • Lastly, next to 'Select a page to subscribe your webhook to the page events' select your Facebook page.

If all verification were successful, your bot is now available via Facebook Messenger.

Test your bot

To test your bot, go to your Facebook page and add a button:

  1. Click 'Add a button'
  2. You will be presented by five different categories of buttons, choose the one that says 'Contact you'
  3. Select 'Send message' and press next
  4. Facebook will now ask you what should happen when they press the button, choose 'Messenger'

That's it! To test it, hover over the 'Send message' button and choose 'Test button'. A messenger windows appear, allowing you chat with your bot.

Sending attachments

To send message templates or message attachments, this connector looks for an output parameter fbmessenger in the engine response. The value of that parameter is assumed to contain the attachment or message template JSON as defined by Facebook.

If we look at Facebook's specification of an image attachment, to attach an image, the value of the fbmessenger output parameter would need to look like this:

    "type": "image",
    "payload": {
        "url": "https://url.to/an/image.png",
        "is_reusable": true

For more details on how to populate output parameters in Teneo, please see: How to populate output parameters in the Build your bot section.

Running the connector locally

If you prefer to manually install this connector or want to run it locally so you can extend it, proceed as follows:

  1. Clone or download the connector from Github
  2. Install dependencies by running npm install in the folder where you cloned or unzipped the connector.
  3. Start the connector with the following command (replacing the environment variables with the appropriate values):
    FB_PAGE_ACCESS_TOKEN=<your_facebook_page_access_token> FB_VERIFY_TOKEN=<your_facebook_verify_token> TENEO_ENGINE_URL=<your_engine_url> node server.js
  4. Your connector should be available via https. When running locally you can for example use ngrok: ngrok.com. The connector runs on port 4649 by default, so the command to start ngrok looks like this:
    ngrok http 4649

    Use the https url provided by ngrok appended with /webhook/ for the 'Callback URL' of your webhook on Facebook:

    • In the left menu of your Facebook App go to: Webhooks > Edit Page Subscription
    • Set Callback URL to: https://<HTTPS address provided by ngrok>/webhook/
    • Set Verify token to: <The FB_VERIFY_TOKEN you chose in step 4>
    • Click: Verify and Save

      Note: If clicking on "Verify and Save" returns an error, make sure your server.js script in step 4 has already been running for at least 2 or 3 minutes.

Was this page helpful?