Repository: RasaHQ/rasa
Pull request: update facebook docs with supported attachments
**Proposed changes**:
- update Facebook channel docs with supported attachments:
    - `buttons`
    - `quick_replies`
    - `elements`
- Fixes #5640 

**Status (please check what you already did)**:
- [x] updated the documentation
- [x] updated the changelog (please check [changelog](https://github.com/RasaHQ/rasa/tree/master/changelog) for instructions)


Problem statement:
Need docs on Facebook Messenger response template keys 
**Description of Problem**:
Had to add a Facebook messenger channel integration into a bot I spun up and found the Facebook Messenger docs lacking a bit especially on the special response template keys `quick_replies` and `elements`; I had to read through the Facebook channel source to figure out what was allowed/disallowed.

**Overview of the Solution**:
FB Messenger docs updated with additional response template information.


**Definition of Done**:
- [x] Facebook channel docs updated with caveats for default `buttons` option and explanation of omission if more than 3 buttons were passed.
- [x] Facebook channel docs updated with `quick_replies` description along with quick title character limitation mention
- [x] Facebook channel docs updated with `elements` description along with pointer to Messenger docs on allowed templates
- [x] Documentation update mentioned in the change log

Hints from issue discussion:
Thanks for submitting this feature request 🚀 @degiz will get back to you about it soon! ✨
Hey @ortsaCniveK 

Great that you could connect the bot the Facebook Messenger! 

Since you've just identified the issues with the current docs, maybe you can propose a PR with all the updated you've mentioned?
Currently working on updating docs as well as doing some maintenance on that module.

Commit message: Merge branch 'master' into docs-facebook

Patch to review:
diff --git a/changelog/5640.doc.rst b/changelog/5640.doc.rst
new file mode 100644
index 000000000000..1b9258b6fab7
--- /dev/null
+++ b/changelog/5640.doc.rst
@@ -0,0 +1 @@
+updated Facebook Messenger channel docs with supported attachment information
diff --git a/docs/user-guide/connectors/facebook-messenger.rst b/docs/user-guide/connectors/facebook-messenger.rst
index b0feba886f1a..6aaba249943d 100644
--- a/docs/user-guide/connectors/facebook-messenger.rst
+++ b/docs/user-guide/connectors/facebook-messenger.rst
@@ -69,3 +69,78 @@ The endpoint for receiving Facebook messenger messages is
 ``http://localhost:5005/webhooks/facebook/webhook``, replacing
 the host and port with the appropriate values. This is the URL
 you should add in the configuration of the webhook.
+
+Supported response attachments
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In addition to typical text, image, button, and custom responses, the Facebook Messenger channel supports the following additional response template attachments:
+
+* `Buttons <https://developers.facebook.com/docs/messenger-platform/send-messages/buttons>`_: sends a text message with up to three attached buttons
+
+.. code-block:: yaml
+
+   utter_fb_buttons_example:
+      - text: Hello World!
+        buttons:
+          - title: Button Title
+            payload: /example_intent
+          - title: Button Title
+            payload: /example_intent
+          - title: Button title over 20 characters # this will be truncated to: "Button title over..."
+            payload: /example_intent
+
+.. warning::
+
+   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 <https://developers.facebook.com/docs/messenger-platform/send-messages/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.
+
+.. code-block:: yaml
+
+   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.
+
+* `Generic Template Elements <https://developers.facebook.com/docs/messenger-platform/send-messages/template/generic>`_: 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.
+
+.. code-block:: yaml
+
+   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


Code review comments:
diff_hunk: @@ -69,3 +69,78 @@ The endpoint for receiving Facebook messenger messages is
 ``http://localhost:5005/webhooks/facebook/webhook``, replacing
 the host and port with the appropriate values. This is the URL
 you should add in the configuration of the webhook.
+
+Supported response attachments
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In addition to typical text, image, button, and custom responses, the Facebook Messenger channel supports the following additional response template attachments:
+
+* `Buttons <https://developers.facebook.com/docs/messenger-platform/send-messages/buttons>`_: sends a text message with up to three attached buttons
+
+.. code-block:: yaml
+
+   utter_fb_buttons_example:
+      - text: Hello World!
+        buttons:
+          - title: Button Title
+            payload: /example_intent
+          - title: Button Title
+            payload: /example_intent
+          - title: Button title over 20 characters # this will be truncated to: "Button title over..."
+            payload: /example_intent
+
+.. warning::
+
+   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.
path: docs/user-guide/connectors/facebook-messenger.rst
text: @user1:
```suggestion
* `Buttons <https://developers.facebook.com/docs/messenger-platform/send-messages/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.
```