Facebook Messenger

Start off by generating the App Secret and the Page Access token in Facebook Messenger.

1. Log into your Facebook developer’s account.
2. Create the Facebook app that you’ll use for the channel:
   1. In your browser, go to https://developers.facebook.com/apps/.
   2. Select the My Apps tab and click Create App.
   3. On the App details page of the Create App wizard, enter the name you want to use for the app and the email address you want to use as the contact for the app. Then click Next.
   4. On the Use cases page, under Filter by, select Business messaging. Then select Engage with customers on Messenger from Meta and click Next.
   5. Click through the rest of the pages in the wizard and then, on the Overview page, click Create App.
3. Once the app is created, select the app (on the left side of the My Apps page), and then, in the App Settings section, select Basic.
4. Copy the value of the App secret field and paste it somewhere convenient on your system.

   You’ll need the app secret later on to complete your Facebook channel configuration.

5. In the App page section, click Create new Page.
6. On the Create a Page page, fill in the required fields and then click Create Page.
   Note
   
   The page name should contain the app name.
7. Generate an access token:
   1. Select Tools > Graph API Explorer.
   2. In the Access Token section of the page, for Meta App, select the name of your app.
   3. For the User or Page field, select Get Token.
   4. In the Permissions section, click Add a Permission and select the following permissions:
      • business_management
      • pages_manage_metadata
      • pages_messaging
      • pages_show_list
   5. Click Generate Access Token.
8. Copy the access token and paste it somewhere convenient.

   You’ll use this token, which gives your Facebook App access to Facebook’s Messaging API, to complete your channel definition in Digital Assistant.

In Facebook Messenger, define the Callback URL using the Webhook URL generated by Digital Assistant in the previous step.

1. In the Facebook Messenger console, go to the project that you initially created for the webhook.
2. Select Messenger API Settings to open the Messenger API Setup page.
3. In the CallBack URL field, paste the Webhook URL that you got from the Digital Assistant Channels page.
4. In the Verify Token field in the Messenger console, paste the Verify Token from the Digital Assistant Channels page.
5. In the Webhook fields section, select the messages and messaging_postbacks callback events.
6. Click Verify and Save.
7. Subscribe to the page:
   1. In the Generate access tokens section of the Messenger API Setup page, select the Facebook page for your channel.
   2. Click Add Subscription.
   3. In the Edit Page Subscriptions dialog, verify that messages and messaging_postbacks are selected, and click Confirm.

With the configuration complete, you’re ready to activate the Facebook channel.

• In Digital Assistant, select the channel and switch on the Channel Enabled control.
• Click and select the digital assistant or skill that you want to associate with the channel.

You can now test the bot through the channel.

With the Facebook Channel and messaging configuration complete, you can test your bot using your Facebook page, Facebook Messenger (https://www.messenger.com/) and the Facebook Messenger app on your device.

1. Go to https://www.messenger.com/.
2. Within the Messenger interface, enter the name of your page to search for the page.
3. Start chatting with your digital assistant (or standalone skill).

Facebook Messenger enables you to create a persistent menu next to its Message field. See https://developers.facebook.com/docs/messenger-platform/send-messages/persistent-menu/ for details on the feature.

Here's an example that shows persistent menu items for "Order Pizza" and "Order Pasta":

Description of the illustration persistent-menu1.jpg

Facebook Messenger channels in Digital Assistant support the following capabilities:

• text (both sending and receiving)
• images (both sending and receiving)
• files (both sending and receiving)
• emojis (both sending and receiving)
• location, but deprecated (both sending and receiving)
• links
• postbacks
• location requests
• custom properties
• carousel components
• list components

If you are targeting your skill to multiple channels with different formatting capabilities and syntax, you can use basic HTML markup in your messages. If you do so, that markup will be automatically converted to Facebook Messenger's markdown format when the message is transmitted to the channel. This is particularly useful if you are targeting your skills to other channels in addition to Facebook Messenger. See Rich Text Formatting in Channels.

Facebook Messenger channels in Digital Assistant have the following message constraints:

• Text Messages
  • Maximum length of text message: 640 characters. If the length exceeds 640, the text is split over multiple messages.
  • Maximum length of text action label: 20 characters
  • Types of text actions allowed: Postback, Call, URL
  • Maximum number of text actions: 3. If there are more text actions, the message is converted to multiple horizontal cards, with the same text used as the title on each card, and each card containing up to 3 actions.
• Horizontal Cards
  • Maximum length of title: 80 characters
  • Maximum length of description: 80 characters
  • Maximum length of card action label: 20 characters
  • Maximum number of cards: 10
  • Maximum number of card actions: 3. If the number of card actions exceeds 3, the card is duplicated to render remaining card actions.
  • Minimum number of card actions: 0
  • Maximum number of card list actions: 0
  • At least one description, image or action required?: Yes
  • Types of card actions allowed: Postback, Call, URL, Share
  • Types of card list actions allowed: N/A
• Vertical Cards
  • Not supported
• Attachment Messages
  • Supported?: Yes
  • Attachment actions allowed?: No
• Action Buttons
  • Maximum length of global action label: 20 characters
  • Maximum number of global actions: 11
  • Types of global actions allowed: Postback

For Facebook Messenger channels, you can extend the functionality of Common Response components with capabilities that are specific to Facebook.

You access the extensions by using the channelCustomProperties element in the Common Response component's metadata and setting the appropriate properties. The code has the following format:

...
            channelCustomProperties:
            - channel: "facebook"
              properties:
                PROPERTY_NAME: "PROPERTY_VALUE"
...

Here are the available custom properties for Facebook Messenger channels:

Here is an example of custom properties defined at the response item level (top_element_style) and the cards level (webview_height_ratio and fallback_url):

responseItems:
  - type: "cards"
    cardLayout: "vertical"
    cards:
      - title: "${pizzas.name}"
        description: "${pizzas.description}"
        imageUrl: "${pizzas.image}"
        url: "${pizzas.moreInfo}"
        iteratorVariable: "pizzas"
        channelCustomProperties:
          - channel: "facebook"
            properties:
              webview_height_ratio: "compact"
              fallback_url: "http://www.oracle.com"
    channelCustomProperties:
      - channel: "facebook"
        properties:
          top_element_style: "large"
...

For more general information on channelCustomProperties, see Channel-Specific Extensions.