README.md in stealth-facebook-0.9.2 vs README.md in stealth-facebook-0.10.0

- old
+ new

@@ -1,367 +1,734 @@ # Stealth Facebook + +This integration adds support for Facebook bots within Stealth. + +## Configure Your Facebook Page + +Add instructions + +## Configure The Integration + +```yaml +default: &default + facebook: + verify_token: <%= ENV['FACEBOOK_VERIFY_TOKEN'] %> + page_access_token: <%= ENV['FACEBOOK_ACCESS_TOKEN'] %> + setup: + greeting: # Greetings are broken up by locale + - locale: default + text: "Welcome to my Facebook Bot." + get_started: + payload: new_user + persistent_menu: + - locale: default + composer_input_disabled: false + call_to_actions: + - type: payload + text: Some Button + payload: some_button + +production: + <<: *default + +development: + facebook: + verify_token: <%= ENV['FACEBOOK_VERIFY_TOKEN'] %> + page_access_token: <%= ENV['FACEBOOK_ACCESS_TOKEN'] %> + setup: + greeting: # Greetings are broken up by locale + - locale: default + text: "Welcome to my Facebook Bot." + get_started: + payload: new_user + persistent_menu: + - locale: default + composer_input_disabled: false + call_to_actions: + - type: payload + text: Some Button + payload: some_button + - type: nested + text: Developer + buttons: + - type: payload + text: Restart + payload: developer_restart + +test: + <<: *default +``` + +As with all Stealth integrations, integrations can be specified by environment. You'll want to replace `FACEBOOK_VERIFY_TOKEN` and `FACEBOOK_ACCESS_TOKEN` with your respective keys from your Facebook page. + +These are the supported setup options: + +### greeting +This is the message a user will see via Messenger before they have ever sent your bot a message. + +### get_started +When the user presses the `Get Started` button in Messenger, the `payload` specified here is the payload that will be sent to your bot. + +### persistent_menu +These are the items that appear in the Facebook Messenger drawer. You can specify menu items for each locale individually or use `default` to make the menu apply to all locales. + +The `composer_input_disabled` disables the keyboard input. This is helpful if you anticipate all user replies will come from suggested replies. It defaults to `false` which means the keyboard input is enabled. + +The `call_to_actions` list defines the buttons. In the above example, the production environment has a single button defined with the label `Some Button`. It's type is set to `payload`. The `payload` value specifies the payload that will be sent to the bot when the button is pressed. + +In the `development` environment, there is a `Developer` sub-menu that contains a single button labeled `Restart`. This just showcases the ability to have sub-menus within the drawer. It's a common practice to introduce a `developer_restart` payload button in development so you can easily restart the bot. + +In addition to the `payload` type, the persistent menu supports `url` and `call` type buttons. + +### Uploading the Persistent Menu + +Each time you make a change to the persistent menu, you will have to upload the change to Facebook. This integration provides a command line task to automate this: + +``` +stealth setup facebook +``` + +## Replies + +Here are the supported replies for the Facebook integration: + +### text + +These are standard text replies. It can sent like: + +```yaml +- reply_type: text + text: Hello World! +``` + +Text replies can also include suggestions, which will be rendered as quick replies: + +```yaml +- reply_type: text + text: What is your favorite color? + suggestions: + - text: Blue + - text: Red +``` + +Although not as common, text replies can also include buttons: + +```yaml +- reply_type: text + text: Would you like to give us a call? + buttons: + - type: call + phone_number: "+15552991212" + text: 'Yes' + - type: payload + text: 'No' + payload: 'No' +``` + +### suggestions + +Though suggestions are not a reply type on their own, they are frequently used to optimize the accuracy and speed of your bot. In the `text` reply type above, we used simple labels for our suggestions. Facebook supports a few special types of quick replies, however. + +#### Location + +You can ask a user for their location: + +```yaml +- reply_type: text + text: "Where are you located?" + suggestions: + - type: location +``` + +If the user chooses to share their location, the `lat` and `lng` will be available via `current_message.location`: + +```ruby +current_message.location[:lat] +current_message.location[:lng] +``` + +#### Email + +As of Facebook Messenger Platform 2.3, Facebook now supports a standard way to ask for a user's email: + +```yaml +- reply_type: text + text: "What is your email address?" + suggestions: + - type: email +``` + +The email address the user sends back will be available as the string in `current_message.payload` + +#### Phone + +As of Facebook Messenger Platform 2.3, Facebook now supports a standard way to ask for a user's phone number: + +```yaml +- reply_type: text + text: "What is your phone number?" + suggestions: + - type: phone +``` + +The phone number the user sends back will be available as the string in `current_message.payload` + +#### Images + +While images are not a special quick reply type, you can include and `image_url` for a quick reply as way of adding an icon to a quick reply button: + +```yaml +- reply_type: text + text: "What is your favorite color?" + suggestions: + - text: Red + image_url: "http://example.com/img/red.png" + - text: Blue + image_url: "http://example.com/img/blue.png" +``` + +More info [here](https://developers.facebook.com/docs/messenger-platform/send-messages/quick-replies). + +### buttons + +As with `suggestions`, `buttons` are not a reply type of their own but are used to make your bot more efficient. Facebook supports a few button types and these are the ones currently supported by this integration: + +#### payload + +This is the most common button type. When a user presses a button that is `payload` type, that payload string will be sent to your bot. For example: + +```yaml +- reply_type: text + text: Please press the button below + buttons: + - type: payload + text: 'Press me!' + payload: 'button pressed' + +``` + +When a user presses the button labeled "Press me!", the payload `button pressed` will be accessible in bot via `current_message.payload`. + +#### url + +The `url` button is useful when sharing a link to a website. By default, it will open up within Facebook Messenger. + +```yaml +- reply_type: text + text: Find out more via our website + buttons: + - type: url + text: 'Visit website' + url: 'https://example.org' + +``` + +You can also specify the height of the webview window that opens up in Messenger via: `webview_height`. You can choose between `compact`, `tall`, and `full`. + +More info [here](https://developers.facebook.com/docs/messenger-platform/webview). + +#### call + +The `call` button type will prompt the user to dial the specified number. The number will be pre-filled in, but the user will still have to confirm by confirming via the modal that is shown. To create a `call` button: + +```yaml +- reply_type: text + text: Give us a ring! + buttons: + - type: call + text: 'Call' + phone_number: "+15552991212" + +``` + +### Delay + +Delays are a very important part of bot design. They introduce a pause between text replies to give the user a chance to read each reply. With this integration, in addition to introducing a delay, we will also send a typing indicator to the user to indicate another reply is forthcoming. To insert a delay in your bot: + +```yaml +- reply_type: delay + duration: 2 +``` + +This will add a `2` second delay (with typing indicator). The `duration` can be specified as any floating point value, in seconds. + +### Cards + +Facebook distinguishes between a single card and a carousel of cards. This integration does not, however. You can send a single card the same way you would send 10 cards (the current maximum). + +```yaml +- reply_type: cards + sharable: true + aspect_ratio: horizontal + elements: + - title: My App + subtitle: Download our app below or visit our website for more info. + image_url: "https://my-app.com/app-image.png" + buttons: + - type: url + url: "https://my-app.com" + text: 'View' + webview_height: 'tall' + - type: url + url: "https://itunes.apple.com/us/app/my-app" + text: 'Download iOS App' +``` + +The above is a single card with two buttons. If you want to include more cards, though, you would just need to specify another listing under the `elements` heading. + +The `sharable` and `aspect_ratio` attributes are optional. When `sharable` is set to `true`, a native share button is shown in Messenger for the message. The `aspect_ratio` attribute specifies the aspect ratio of the main card image (specified by `image_url`). It can be set to `horizontal` or `square` with the default being `horizontal`. + +More info about Facebook cards [here](https://developers.facebook.com/docs/messenger-platform/send-messages/template/generic). + +### List + +A Facebook list is useful for displaying things like a news feed. You can find more info about Facebook lists [here](https://developers.facebook.com/docs/messenger-platform/send-messages/template/list). + +To generate a list via Stealth Facebook: + +```yaml +- reply_type: list + top_element_style: large + buttons: + - type: payload + title: View More + payload: view_more + elements: + - title: Your Daily News Update + subtitle: The following stories have been curated just for you. + image_url: "https://news-articles.com/logo.png" + buttons: + - type: url + url: "https://news-articles.com/199" + text: 'View' + webview_height: 'tall' + - title: Breakthrough in AI + subtitle: Major breakthrough in the AI space. + image_url: "https://news-articles.com/ai.png" + default_action: + - url: "https://news-articles.com/232" + webview_height: 'tall' +``` + +The list itself supports having a single button that will be rendered on the bottom of the list. Each individual list item supports having one button as well. List items should have between 2-4 elements. + +In addition to the button, a list item can specify a default action. The default action is what will fired when a user taps the list item. A default action can be specified by setting the `default_action` attribute. The `default_action` should be configured as you would a `url` type button. + +The image of the first item in the list is displayed as a cover photo by default. To disable the cover image, set `top_element_style` to `compact`. + +### Images + +To send an image: + +```yaml +- reply_type: image + image_url: 'https://example.org/image.png' +``` + +The `image_url` should be set to URL where the image has been uploaded. + +Image replies support buttons and suggestions like text replies. + +### Files + +To send a file: + +```yaml +- reply_type: file + file_url: 'https://example.org/some.pdf' +``` + +The `file_url` should be set to URL where the file has been uploaded. + +File replies support buttons and suggestions like text replies. + +### Video + +To send a video: + +```yaml +- reply_type: video + video_url: 'https://example.org/cool_video.mp4' +``` + +The `video_url` should be set to URL where the video has been uploaded. + +Video replies support buttons and suggestions like text replies. + +### Audio + +To send an audio clip: + +```yaml +- reply_type: audio + audio_url: 'https://example.org/podcast.mp3' +``` + +The `audio_url` should be set to URL where the video has been uploaded. + +Audio replies support buttons and suggestions like text replies.