{"id":13747349,"url":"https://github.com/hellostealth/stealth-facebook","last_synced_at":"2025-03-20T02:13:17.727Z","repository":{"id":32440694,"uuid":"109910565","full_name":"hellostealth/stealth-facebook","owner":"hellostealth","description":"Facebook Messenger driver for Stealth","archived":false,"fork":false,"pushed_at":"2024-01-04T21:43:15.000Z","size":152,"stargazers_count":12,"open_issues_count":15,"forks_count":12,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-05-13T10:03:43.818Z","etag":null,"topics":["chatbot","facebook-bot","facebook-messenger","facebook-messenger-bot","ruby","stealth","stealth-facebook"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hellostealth.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-11-08T01:13:44.000Z","updated_at":"2024-08-03T06:04:07.410Z","dependencies_parsed_at":"2024-08-03T06:14:07.766Z","dependency_job_id":null,"html_url":"https://github.com/hellostealth/stealth-facebook","commit_stats":{"total_commits":94,"total_committers":10,"mean_commits":9.4,"dds":"0.23404255319148937","last_synced_commit":"d87f5344cdebe31ddc3aa72f78395d4bc00bd9f4"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hellostealth%2Fstealth-facebook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hellostealth%2Fstealth-facebook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hellostealth%2Fstealth-facebook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hellostealth%2Fstealth-facebook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hellostealth","download_url":"https://codeload.github.com/hellostealth/stealth-facebook/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244536457,"owners_count":20468350,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chatbot","facebook-bot","facebook-messenger","facebook-messenger-bot","ruby","stealth","stealth-facebook"],"created_at":"2024-08-03T06:01:25.772Z","updated_at":"2025-03-20T02:13:17.704Z","avatar_url":"https://github.com/hellostealth.png","language":"Ruby","readme":"# Stealth Facebook\n\nThis integration adds support for Facebook bots within [Stealth](https://github.com/hellostealth/stealth).\n\n[![Gem Version](https://badge.fury.io/rb/stealth-facebook.svg)](https://badge.fury.io/rb/stealth-facebook)\n\n## Configure Your Facebook Page\n\nTo create your Facebook bot, visit the [Facebook Developers](https://developers.facebook.com) page. Full instructions are provided on the [Facebook Messenger Docs](https://developers.facebook.com/docs/messenger-platform/) page.\n\nWhen configuring your webhooks, you'll want to enable the `messages`, `messaging_referrals`, and `messaging_postbacks` web hooks like so:\n\n\u003cimg src='fb-config.png' width='875px' alt='Facebook Config Screenshot' /\u003e\n\n### message_reads\n\nBeginning with version `0.13.0` of this gem, `message_reads` webhooks are supported. When enabled in your Facebook configuration, they will appear as `current_message.read`. That will return a hash:\n\n```ruby\n{\n  watermark: 1458668856253,\n  seq: 38\n}\n```\n\nMore info about `message_reads` webhooks can be found in the [Facebook Developer docs](https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/message-reads).\n\n### messaging_referrals\n\nFacebook separates referral data for users with an existing thread versus those that have initiated a new thread. For the former case, the `messaging_referrals` webhook event is used to send the referral data. For the latter case, the referral payload is sent via the `postback` event.\n\nFor both scenarios above, this driver will include the referral payload as part of the `current_message`. It can be accessed via `current_message.referral`.\n\nMore info about `messaging_referrals` webhooks and the different referral payloads can be found in the [Facebook Developer docs](https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/messaging_referrals/)\n\n## Configure The Integration\n\n```yaml\ndefault: \u0026default\n  facebook:\n    verify_token: \u003c%= ENV['FACEBOOK_VERIFY_TOKEN'] %\u003e\n    page_access_token: \u003c%= ENV['FACEBOOK_ACCESS_TOKEN'] %\u003e\n    setup:\n      greeting: # Greetings are broken up by locale\n        - locale: default\n          text: \"Welcome to my Facebook Bot.\"\n      get_started:\n        payload: new_user\n      persistent_menu:\n        - locale: default\n          composer_input_disabled: false\n          call_to_actions:\n          - type: payload\n            text: Some Button\n            payload: some_button\n\nproduction:\n  \u003c\u003c: *default\n\ndevelopment:\n  facebook:\n  verify_token: \u003c%= ENV['FACEBOOK_VERIFY_TOKEN'] %\u003e\n  page_access_token: \u003c%= ENV['FACEBOOK_ACCESS_TOKEN'] %\u003e\n  setup:\n    greeting: # Greetings are broken up by locale\n      - locale: default\n        text: \"Welcome to my Facebook Bot.\"\n    get_started:\n      payload: new_user\n    persistent_menu:\n      - locale: default\n        composer_input_disabled: false\n        call_to_actions:\n        - type: payload\n          text: Some Button\n          payload: some_button\n        - type: nested\n          text: Developer\n          buttons:\n          - type: payload\n            text: Restart\n            payload: developer_restart\n\ntest:\n  \u003c\u003c: *default\n```\n\nAs 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.\n\nYou may also specify a Facebook Graph API version by setting the ENV var `FACEBOOK_API_VERSION` to API version your bot has been cofnigured to use. If none is specified, this driver will currently default to version `3.2`.\n\nThese are the supported setup options:\n\n### greeting\nThis is the message a user will see via Messenger before they have ever sent your bot a message.\n\n### get_started\nWhen the user presses the `Get Started` button in Messenger, the `payload` specified here is the payload that will be sent to your bot.\n\n### persistent_menu\nThese 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.\n\nThe `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.\n\nThe `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.\n\nIn 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.\n\nIn addition to the `payload` type, the persistent menu supports `url` and `call` type buttons.\n\n### Uploading the Persistent Menu\n\nEach 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:\n\n```\nstealth setup facebook\n```\n\n### Profile Data\n\nBy default, your Facebook bots may retrieve the `id`, `name`, `first_name`, `last_name`, and `profile_pic` fields for users that have made this information public and have opted-in to your bot. More info [here](https://developers.facebook.com/docs/messenger-platform/identity/user-profile).\n\nTo fetch a user's profile with `stealth-facebook` you can call the following:\n\n```ruby\nfb_profile = Stealth::Services::Facebook::Client.fetch_profile(\n  recipient_id: current_user_id\n)\n```\n\n`fb_profile` is a hash that contains the fields above:\n\n```ruby\n{\n  'id'            =\u003e 1464633220279330,\n  'name'          =\u003e \"Carol Robbins\",\n  'first_name'    =\u003e \"Carol\",\n  'last_name'     =\u003e \"Robbins\",\n  'profile_pic'   =\u003e \"https://platform-lookaside.fbsbx.com/platform/profilepic/?psid=1464633220279330\u0026width=1024\u0026ext=1537650777\u0026hash=AeQzWeTgFqlAyiye\"\n}\n```\n\nIf your bot has permission to retrieve additional fields, you can specify them as an array of symbols via the `fields` argument:\n\n```ruby\nfb_profile = Stealth::Services::Facebook::Client.fetch_profile(\n  recipient_id: current_user_id,\n  fields: [:id, :name, :first_name, :last_name, :profile_pic, :gender, :locale]\n)\n```\n\n### Analytics\n\nIf you'd like to track custom bot metrics in addition to the ones provided automatically by Facebook Analytics, you can do so starting with version `0.12.0` of this gem.\n\nIn order to send these metrics, you'll need to include the `app_id` of the bot as well as the `page_id` of the Facebook page (attached to the bot) to `services.yml`:\n\n```yaml\ndefault: \u0026default\n  facebook:\n    verify_token: \u003c%= ENV['FACEBOOK_VERIFY_TOKEN'] %\u003e\n    page_access_token: \u003c%= ENV['FACEBOOK_ACCESS_TOKEN'] %\u003e\n    app_id: \u003c%= ENV['FACEBOOK_APP_ID'] %\u003e\n    page_id: \u003c%= ENV['FACEBOOK_PAGE_ID'] %\u003e\n    ...\n```\n\nThen to collect a metric:\n\n```ruby\nStealth::Services::Facebook::Client.track(recipient_id: u.recipient_id, metric: 'name of your metric', value: 2)\n```\n\nYou can specify additional options:\n\n```ruby\nStealth::Services::Facebook::Client.track(recipient_id: u.recipient_id, metric: 'signup', value: 2, options: { 'fb_description' =\u003e 'A signup occured.' })\n```\n\nMore info about events, such as which options are available, can be found on [Facebook's Events API docs](https://developers.facebook.com/docs/marketing-api/app-event-api) page.\n\n## Replies\n\nHere are the supported replies for the Facebook integration:\n\n### text\n\nThese are standard text replies. It can sent like:\n\n```yaml\n- reply_type: text\n  text: \"Hello World!\"\n```\n\nText replies can also include suggestions, which will be rendered as quick replies:\n\n```yaml\n- reply_type: text\n  text: \"What is your favorite color?\"\n  suggestions:\n    - text: Blue\n    - text: Red\n```\n\nText replies can also include buttons:\n\n```yaml\n- reply_type: text\n  text: \"Would you like to give us a call?\"\n  buttons:\n    - type: call\n      phone_number: \"+15552991212\"\n      text: 'Yes'\n    - type: payload\n      text: 'No'\n      payload: 'No'\n```\n\n### suggestions\n\nThough 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, discussed below.\n\nPlease note that starting with version `0.17.0` of this gem, quick replies return their response via `current_message.message` as well as `current_message.payload`. Please make sure your `route` method in `BotController` handles that accordingly.\n\n#### Location\n\nYou can ask a user for their location:\n\n```yaml\n- reply_type: text\n  text: \"Where are you located?\"\n  suggestions:\n    - type: location\n```\n\nIf the user chooses to share their location, the `lat` and `lng` will be available via `current_message.location`:\n\n```ruby\ncurrent_message.location[:lat]\ncurrent_message.location[:lng]\n```\n\n#### Email\n\nAs of Facebook Messenger Platform 2.3, Facebook now supports a standard way to ask for a user's email:\n\n```yaml\n- reply_type: text\n  text: \"What is your email address?\"\n  suggestions:\n    - type: email\n```\n\nThe email address the user sends back will be available as the string in `current_message.payload`\n\n#### Phone\n\nAs of Facebook Messenger Platform 2.3, Facebook now supports a standard way to ask for a user's phone number:\n\n```yaml\n- reply_type: text\n  text: \"What is your phone number?\"\n  suggestions:\n    - type: phone\n```\n\nThe phone number the user sends back will be available as the string in `current_message.payload`\n\n#### Images\n\nWhile 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:\n\n```yaml\n- reply_type: text\n  text: \"What is your favorite color?\"\n  suggestions:\n    - text: Red\n      image_url: \"http://example.com/img/red.png\"\n    - text: Blue\n      image_url: \"http://example.com/img/blue.png\"\n```\n\nMore info [here](https://developers.facebook.com/docs/messenger-platform/send-messages/quick-replies).\n\n### buttons\n\nAs 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:\n\n#### payload\n\nThis 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:\n\n```yaml\n- reply_type: text\n  text: \"Please press the button below\"\n  buttons:\n    - type: payload\n      text: 'Press me!'\n      payload: 'button pressed'\n\n```\n\nWhen a user presses the button labeled \"Press me!\", the payload `button pressed` will be accessible in bot via `current_message.payload`.\n\n#### url\n\nThe `url` button is useful when sharing a link to a website. By default, it will open up within Facebook Messenger.\n\n```yaml\n- reply_type: text\n  text: \"Find out more via our website\"\n  buttons:\n    - type: url\n      text: 'Visit website'\n      url: 'https://example.org'\n      messenger_extensions: true\n\n```\n\nEnabling messenger_extensions allows your webview to access a selection of features from the Messenger platform. More info [here](https://developers.facebook.com/docs/messenger-platform/webview/extensions?source=post_page). Without this parameter set to true, the webview opens in a separate tab or window if a user is visiting from the 'messenger.com' domain.\n\nYou 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`.\n\nMore info [here](https://developers.facebook.com/docs/messenger-platform/webview).\n\n\n#### call\n\nThe `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:\n\n```yaml\n- reply_type: text\n  text: \"Give us a ring!\"\n  buttons:\n    - type: call\n      text: 'Call'\n      phone_number: \"+15552991212\"\n\n```\n\n### Delay\n\nDelays 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:\n\n```yaml\n- reply_type: delay\n  duration: 2\n```\n\nThis will add a `2` second delay (with typing indicator). The `duration` can be specified as any floating point value, in seconds.\n\n### Cards\n\nFacebook 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).\n\n```yaml\n- reply_type: cards\n  sharable: true\n  aspect_ratio: horizontal\n  elements:\n    - title: My App\n      subtitle: Download our app below or visit our website for more info.\n      image_url: \"https://my-app.com/app-image.png\"\n      buttons:\n        - type: url\n          url: \"https://my-app.com\"\n          text: 'View'\n          webview_height: 'tall'\n        - type: url\n          url: \"https://itunes.apple.com/us/app/my-app\"\n          text: 'Download iOS App'\n```\n\nThe 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.\n\nThe `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`.\n\nMore info about Facebook cards [here](https://developers.facebook.com/docs/messenger-platform/send-messages/template/generic).\n\n### List\n\nA 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).\n\nTo generate a list via Stealth Facebook:\n\n```yaml\n- reply_type: list\n  top_element_style: large\n  buttons:\n    - type: payload\n      text: View More\n      payload: view_more\n  elements:\n    - title: Your Daily News Update\n      subtitle: The following stories have been curated just for you.\n      image_url: \"https://loremflickr.com/320/240\"\n      buttons:\n        - type: url\n          url: \"https://news-articles.com/199\"\n          text: 'View'\n          webview_height: 'tall'\n    - title: Breakthrough in AI\n      subtitle: Major breakthrough in the AI space.\n      image_url: \"https://loremflickr.com/320/320\"\n      default_action:\n        - url: \"https://news-articles.com/232\"\n          webview_height: 'tall'\n```\n\nThe 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.\n\nIn 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.\n\nThe 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`.\n\n### Images\n\nTo send an image:\n\n```yaml\n- reply_type: image\n  image_url: 'https://example.org/image.png'\n```\n\nThe `image_url` should be set to URL where the image has been uploaded.\n\nImage replies support buttons and suggestions like text replies.\n\n### Files\n\nTo send a file:\n\n```yaml\n- reply_type: file\n  file_url: 'https://example.org/some.pdf'\n```\n\nThe `file_url` should be set to URL where the file has been uploaded.\n\nFile replies support buttons and suggestions like text replies.\n\n### Video\n\nTo send a video:\n\n```yaml\n- reply_type: video\n  video_url: 'https://example.org/cool_video.mp4'\n```\n\nThe `video_url` should be set to URL where the video has been uploaded.\n\nVideo replies support buttons and suggestions like text replies.\n\n### Audio\n\nTo send an audio clip:\n\n```yaml\n- reply_type: audio\n  audio_url: 'https://example.org/podcast.mp3'\n```\n\nThe `audio_url` should be set to URL where the video has been uploaded.\n\nAudio replies support buttons and suggestions like text replies.\n\n### Account Linking\n\nAccount Linking allows you to invite users to log-in using your own authentication flow, and to receive a Messenger page-scoped ID (PSID) upon completion. You can find more info about Facebook Account Linking [here](https://developers.facebook.com/docs/messenger-platform/identity/account-linking).\n\n#### Login\n\nThe `login` button type will prompt the user to log-in using your own authentication flow in the case he or she has an account with your business. You can find more info about Facebook Log In Button [here](https://developers.facebook.com/docs/messenger-platform/reference/buttons/login).\n\nTo create a `login` button:\n\n```yaml\n- reply_type: text\n  text: \"Log in to access your account information.\"\n  buttons:\n    - type: login\n      url: \"https://my-app.com/login\"\n```\n\n#### Logout\n\nThe `logout` button type is used in the account linking flow to unlink the message recipient's identity on Messenger with their account on your site. You can find more info about Facebook Log Out Button [here](https://developers.facebook.com/docs/messenger-platform/reference/buttons/logout).\n\nTo create a `logout` button:\n\n```yaml\n- reply_type: text\n  text: \"Log out\"\n  buttons:\n    - type: logout\n```\n\n","funding_links":[],"categories":["Ruby"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhellostealth%2Fstealth-facebook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhellostealth%2Fstealth-facebook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhellostealth%2Fstealth-facebook/lists"}