{"id":19928390,"url":"https://github.com/rudemex/fb-messenger-bot","last_synced_at":"2025-10-26T13:34:00.303Z","repository":{"id":146596748,"uuid":"291386497","full_name":"rudemex/fb-messenger-bot","owner":"rudemex","description":"This application is a starter for the creation of bots for Facebook Messenger and WorkChat (Workplace) for demonstration and education purposes. Its configuration is robust and scalable and can be used in a productive environment. Use this application to learn, experiment, retouch and practice the different options offered by the Facebook API.","archived":false,"fork":false,"pushed_at":"2021-07-30T23:33:50.000Z","size":20081,"stargazers_count":4,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-09-19T05:49:53.966Z","etag":null,"topics":["api","bot","bot-framework","bot-server","express","facebook","facebook-api","facebook-messenger","facebook-server","heroku","javascript","messenger","messenger-bot","messenger-platform","node","nodejs","rudemex","starter","starter-kit","workplace"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/rudemex.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"license.md","code_of_conduct":"CODE_OF_CONDUCT.md","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},"funding":{"custom":["https://www.linkedin.com/in/rudemex","https://www.instagram.com/rudemex/","https://twitter.com/rudemex/","https://paypal.me/rudemex"]}},"created_at":"2020-08-30T02:39:23.000Z","updated_at":"2023-06-01T19:05:00.000Z","dependencies_parsed_at":null,"dependency_job_id":"050ec00b-1e91-4269-ad90-6d238c8099b0","html_url":"https://github.com/rudemex/fb-messenger-bot","commit_stats":null,"previous_names":[],"tags_count":7,"template":true,"template_full_name":null,"purl":"pkg:github/rudemex/fb-messenger-bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rudemex%2Ffb-messenger-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rudemex%2Ffb-messenger-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rudemex%2Ffb-messenger-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rudemex%2Ffb-messenger-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rudemex","download_url":"https://codeload.github.com/rudemex/fb-messenger-bot/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rudemex%2Ffb-messenger-bot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281114816,"owners_count":26446038,"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","status":"online","status_checked_at":"2025-10-26T02:00:06.575Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["api","bot","bot-framework","bot-server","express","facebook","facebook-api","facebook-messenger","facebook-server","heroku","javascript","messenger","messenger-bot","messenger-platform","node","nodejs","rudemex","starter","starter-kit","workplace"],"created_at":"2024-11-12T22:37:05.453Z","updated_at":"2025-10-26T13:34:00.278Z","avatar_url":"https://github.com/rudemex.png","language":"JavaScript","funding_links":["https://www.linkedin.com/in/rudemex","https://www.instagram.com/rudemex/","https://twitter.com/rudemex/","https://paypal.me/rudemex"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg style='width: 100%' alt=\"Guidelines to create your bot - Facebook Workplace\" src=\"./.readme-static/header.png\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://nodejs.org/es/\"\u003e\n    \u003cimg src=\"https://img.shields.io/static/v1.svg?style=flat-square\u0026label=Node\u0026message=v10.15.3\u0026labelColor=339933\u0026color=757575\u0026logoColor=FFFFFF\u0026logo=node.js\" alt=\"Node.js website\"/\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/\"\u003e\n    \u003cimg src=\"https://img.shields.io/static/v1.svg?style=flat-square\u0026label=Npm\u0026message=v6.4.1\u0026labelColor=CB3837\u0026logoColor=FFFFFF\u0026color=757575\u0026logo=npm\" alt=\"Npm website\"/\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://expressjs.com/\"\u003e\n    \u003cimg src=\"https://img.shields.io/static/v1.svg?style=flat-square\u0026label=Express\u0026message=v4.16.4\u0026labelColor=444\u0026logoColor=FFFFFF\u0026color=757575\u0026logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAMAAABEpIrGAAAAMFBMVEX////q6uqgoaEZGhtzc3SSk5Ourq5hYmLHx8f09PVOTk+7u7vf39+DhITT09M3ODgiPZ4kAAAAuUlEQVR42u2RyxbDIAhE0fEVjfL/fxu0YNJFF123d0E4iEMY6c83OA/BO0kDohYTstupUoiOikaTEzjv8+5EpgODaKAeJGQk02ekLbpikBglKh7d0o6x7jZqU0epe5aU05LkUTH2BqhknAivPsA/ik8yTYJ8PzSw/jYGGc66bzLeJJhvNZ90z4hIRkeyNKCZU2aoUMBuG7W8LqRtSgT8oVbra+kgI9gKxey2xzBKn8dTprDOW4YW+hUuT8sFbvZNU3wAAAAASUVORK5CYII=\" alt=\"ExpressJS website\"/\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://developers.facebook.com/docs/graph-api/overview\"\u003e\n    \u003cimg src=\"https://img.shields.io/static/v1.svg?style=flat-square\u0026label=API%20Messenger\u0026message=v8.0\u0026labelColor=00B2FF\u0026logoColor=FFFFFF\u0026color=757575\u0026logo=messenger\" alt=\"Facebook Messenger\"/\u003e\n  \u003c/a\u003e\n  \u003cbr/\u003e\n  \u003ca href=\"https://github.com/rudemex/fb-messenger-bot/releases/latest\"\u003e\n    \u003cimg alt=\"GitHub release (latest by date)\" src=\"https://img.shields.io/github/v/release/rudemex/fb-messenger-bot?style=flat-square\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://travis-ci.org/github/rudemex/fb-messenger-bot\"\u003e\n    \u003cimg alt=\"Travis (.org)\" src=\"https://img.shields.io/travis/rudemex/fb-messenger-bot?style=flat-square\"\u003e\n  \u003c/a\u003e        \n  \u003ca href=\"https://github.com/rudemex/fb-messenger-bot/blob/master/license.md\"\u003e\n      \u003cimg alt=\"GitHub\" src=\"https://img.shields.io/github/license/rudemex/fb-messenger-bot?style=flat-square\"\u003e\n    \u003c/a\u003e \n  \u003cbr /\u003e\n\u003c/p\u003e\n\n\u003e 💬 **Note from developer**\n\u003e\n\u003e This application is a starter for the creation of bots for Facebook Messenger and WorkChat (Workplace) for demonstration and education purposes. Its configuration is robust and scalable and can be used in a productive environment. Use this application to learn, experiment, retouch and practice the different options offered by the Facebook API.\n\u003e\n\u003e For more information about the Facebook API you can read the [documentation](https://developers.facebook.com/docs/messenger-platform) that the Messenger team prepared.\n\n---\n\n## Glossary\n\n- [🤔 How does the Messenger platform work?](#how-does-the-messenger-platform-work)\n- [🤖 Live Demo](#live-demo)\n- [🙌 Let's start](#lets-start)\n  - [📝 Basic requirements](#basic-requirements)\n  - [🛠 Install dependencies](#install-dependencies)\n  - [⚙ Configurations](#configurations)\n  - [💻 Run server](#run-server)\n    - [📚 Swagger](#swagger-info)\n  - [🖥️ Deploy server in heroku (free)](#deploy-in-heroku)\n  - [📱 Setup the Facebook App](#setup-the-facebook-app)\n    - [📡 How to share your bot](#how-to-share-your-bot)\n    - [🔗 Create a shortlink](#create-a-shortlink)\n  - [📱 Setup the Workplace App](#setup-the-workplace-app)\n  - [🔐 Security configuration](#security-configuration)\n- [🤦‍♂️Troubleshooting](#troubleshooting)\n- [💡 Contributing](#contributing)\n- [👨‍💻 Author](#author)\n- [📜 License](#license)\n\n\u003ca name=\"how-does-the-messenger-platform-work\"\u003e\u003c/a\u003e\n\n## 🤔 How does the Messenger platform work?\n\nMessaging bots use a web server to process the messages they receive or to find out which messages to send. It is also necessary for the bot to be authenticated to talk to the web server and for the bot to be approved by Facebook to talk to the public.\n\nWhen a person sends a message to a company in Messenger, the following happens, as long as the page uses an app to partially or completely automate the conversations. The Facebook server sends webhooks to the URL of the company's server where the message app is hosted. That app can then reply to the person in Messenger using the Send API. This allows developers to create guided conversations for people to perform an automated process or develop an app that serves as a link between your agents and your company's Messenger presence.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg style='width: 100%' alt=\"Workflow API Messenger\" src=\"./.readme-static/api-messenger-workflow.png\" /\u003e\n\u003c/p\u003e\n\n\u003ca name=\"live-demo\"\u003e\u003c/a\u003e\n\n## 🤖 Live Demo\nYou can try some functions of the bot by entering here.\n\n[Live Demo](https://m.me/staterFbMessengerBot)\n\nAnd you can try other kind of messages from the [server documentation](https://rudemex-fb-messenger-bot.herokuapp.com/api-docs), don't forget to get your ID from the chat bot persistent menu.\n\n\n\u003ca name=\"lets-start\"\u003e\u003c/a\u003e\n\n## 🙌 Let's start\n\nBefore starting to work on our bot, we must have installed some tools in our computer that will facilitate us to work locally and be able to test some functionalities that the starter has available, and I will take for granted some basic concepts so as not to go into detail and extend the documentation.\n\n\u003ca name=\"basic-requirements\"\u003e\u003c/a\u003e\n\n#### 📝 Basic requirements\n\n- Node.js v10.15.3 or higher ([Download](https://nodejs.org/es/download/))\n- NPM v6.4.1 or higher\n- [Ngrok](https://ngrok.com/download) will allow us to create a connection tunnel between our local server and the facebook server.\n- [Account on Facebook developers](https://developers.facebook.com/)\n- [A test page on facebook ](https://www.facebook.com/pages/creation/?ref_type=comet_home)\n\n\u003ca name=\"install-dependencies\"\u003e\u003c/a\u003e\n\n#### 🛠 Install dependencies\n\nWhen we have the basic requirements, we clone the repository, go to the project folder and install its dependencies.\n\n```\n npm install\n```\n\nWe download the latest version of [Ngrok](https://ngrok.com/download) compatible with our operating system, and decompress it in the server root.\n\n\u003ca name=\"configurations\"\u003e\u003c/a\u003e\n\n## ⚙ Configurations\n\nThis application uses the [config](https://www.npmjs.com/package/config) dependency to facilitate the configuration of environment variables, which makes it scalable and robust when deploying the application in different environments.\n\nIn the path `./config` you will find a file called `development.json` which contains the settings for a local environment, while the file `custom-environment-variables.json` gets the key values of the environment variables displayed on the server.\n\nBasically the file works as an object that is exported and can be consumed by invoking it in the file that requires consuming the loaded information.\nIf you need to add another type of data to consume, like the connection to a database, the url of some microservice, etc. you just have to add it to both files keeping the scheme.\n\n\u003e You may find that you can't configure some values for now, but that's not a problem, when using the `nodemon` dependency, the server is in a watching state that at the slightest change of code, the server will run again.\n\n```json5\n{\n  server: {\n    url: '',\n    port: 8080,\n    context: '/api',\n    origins: 'http://localhost:3000,http://localhost:3001,http://localhost:8080',\n    originsReadOnly: 'http://localhost:3001',\n    corsEnabled: 'false',\n    tz: 'America/Argentina/Buenos_Aires',\n    showLogInterceptor: 'false',\n  },\n  params: {\n    fbApiVersion: 'v8.0',\n    verifyToken: 'my_awesome_bot_verify_token',\n    appSecret: '',\n    accessToken: '',\n    subscribedFields: 'messages,messaging_postbacks',\n    userFields: 'id,name,first_name,last_name,email',\n    secrets: '',\n    requireProof: false\n  },\n  services: {\n    fbApiUrl: 'https://graph.facebook.com',\n  },\n  swagger: {\n    enabled: 'true',\n  },\n}\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eSee all available configuration properties in detail.\u003c/summary\u003e\n\n#### Server\n\n`url`: It is the url of the server deployed in some environment, in the case of running it locally, you enter the url with `ssl` provided by **ngrok**.\n\n- Type: `String`\n- Default:\n\n`port`: Is the port in which the application is deployed.\n\n- Type: `Number`\n- Default: `8080`\n\n`context`: It is the context from which the server's api can be accessed, this way the routes in the main path of the application are not exposed.\n\n- Type: `String`\n- Default: `/api`\n\n`origins`: The origins serve so that the application can only be consumed by reliable urls and avoid any kind of unwanted and malicious requests. You should write the urls separated with comma.\n\n- Type: `String`\n- Default: `http://localhost:3000,http://localhost:3001,http://localhost:8080`\n\n`originsReadOnly`: It is the configuration of the urls for CORS, which allows you to validate who can consume the server.\n\n- Type: `String`\n- Default: `http://localhost:3001`\n\n`corsEnabled`: Enables or disables the use of CORS on the bot's server.\n\n- Type: `Boolean`\n- Default: `false`\n\n`tz`: It is the configuration of the time zone. [List of time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List)\n\n- Type: `String`\n- Default: `America/Argentina/Buenos_Aires`\n\n`showLogInterceptor`: Enables the display of the request interceptors in the logs.\n\n- Type: `Boolean`\n- Default: `false`\n\n#### Params\n\n`fbApiVersion`: Is the api version of facebook\n\n- Type: `String`\n- Default: `v8.0`\n\n`verifyToken`: It is the verification token required by the application when invoked by facebook, this token is private and should not be exposed.\n\n- Type: `String`\n- Default: `my_awesome_bot_verify_token`\n\n`appSecret`: It is the secret key to the app, it is required if you are going to use the security settings for the requests.\n- Type: `String`\n- Default: \n\n`accessToken`: The access token is the alphanumeric hash that is generated when you create the application on **Fecebook** or **Workplace**.\n\n- Type: `String`\n- Default:\n\n`subscribedFields`: Are the permissions required to subscribe to the application in order to interact with the user. These permissions are only required for Facebook bots and must be typed separately by comma.\n\n- Type: `String`\n- Default: `messages,messaging_postbacks,messaging_optins`\n\n`userFields`: It is a comma-separated list to obtain the user's information.[Documentation](https://developers.facebook.com/docs/graph-api/reference/user/)\n\n- Type: `String`\n- Default: `id,name,first_name,last_name,email`\n\n`secrets`: Here you can enter any value you want to hide in the server logs of the bot, for example the id of the sender or the id of the sender. The values to hide must be written separated by comma.\n\n- Type: `String`\n- Default:\n\n`requireProof`: Enables or disables the use of `appsecret_proof` and `appsecret_time` for security requests, it is required to have configured the secret key of the app to work.\n- Type: `Boolean`\n- Default: `false`\n\n#### services\n\n`fbApiUrl`: It is the url of the Graph API of Feacebook\n\n- Type: `String`\n- Default: `https://graph.facebook.com`\n\n#### swagger\n\n`enabled`: Enable or disable the documentation of the bot's server endpoints with [swagger](#swagger-info).\n\n- Type: `Boolean`\n- Default: `true`\n\n\u003c/details\u003e\n\n\u003ca name=\"run-server\"\u003e\u003c/a\u003e\n\n## 💻 Run server\n\nWe start the bot's server.\n\n```\nnpm run start\n```\n\n\u003cp align=\"center\"\u003e\n  \u003cimg style='width: 100%' alt=\"Server Bot running in terminal\" src=\"./.readme-static/server-bot-run-terminal.png\" /\u003e\n\u003c/p\u003e\n\nOnce the server is started, we must start **ngrok** to create the connection tunnel between the bot's local server and the Facebook server.\n\n```\n./ngrok http 8080\n```\n\n###### Windows\n\n```\n./ngrok.exe http 8080\n```\n\n\u003cp align=\"center\"\u003e\n  \u003cimg style='width: 100%' alt=\"Server ngrok in terminal\" src=\"./.readme-static/run-ngrok-terminal.png\" /\u003e\n\u003c/p\u003e\n\nTo see other tunnel configurations, you can check the [documentation](https://ngrok.com/docs)\n\n\u003ca name=\"swagger-info\"\u003e\u003c/a\u003e\n\n## 📚 Swagger\n\nThe project has a **Swagger** that has documented the most important endpoints of the project, and facilitates the configuration of the fields for the bot, such as the **get started** button, **persistent menu** and the **greeting**.\n\nThis documentation can be enabled or disabled from the [configuration](#configurations) files.\n\n- Default: `http://localhost:8080/api-docs`\n\n#### URL Scheme\n\n```\n\u003chttp|https\u003e://\u003cserver_url\u003e\u003c:port\u003e/api-docs\n```\n\n\u003ca name=\"deploy-in-heroku\"\u003e\u003c/a\u003e\n\n## 🖥️ Deploy server in heroku (free)\n\nYou can run the bot server in a productive environment on any node server, in this case I will explain the steps to raise the server on the platform [Heroku](https://heroku.com/), which has a free version to deploy node servers, you can also hire a paid service which gives you more features.\n\n\u003e 💬 If you don't have a Heroku account, you can create one by going to [https://signup.heroku.com/](https://signup.heroku.com/).\n\nWe will need a file called `Procfile`, which is the one Heroku will use to initialize the server once deployed.\n\nIts content is:\n\n```\nweb: npm start\n```\n\n1. After logging into Heroku, click on Create new app\n\n\u003cp align=\"center\"\u003e\n   \u003cimg style='width: 100%' alt=\"Create a new app in heroku 1\" src=\"./.readme-static/create-a-new-app-in-heroku-1.png\" /\u003e\n\u003c/p\u003e\n\n2. We write the name of our app, and select a region, and then click on Create App.\n   \u003e 💬 note: Remember to save the name of the app, as you will need it later to replace the value of \u003capp_name\u003e with the name of the app.\n\n\u003cp align=\"center\"\u003e\n   \u003cimg style='width: 100%' alt=\"Create a new app in heroku 2\" src=\"./.readme-static/create-a-new-app-in-heroku-2.png\" /\u003e\n\u003c/p\u003e\n\n3. Heroku gives you several options to deploy your server. You can do it with [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli) by following the steps in the documentation, or you can deploy it directly from Github, which is much easier.\n\n\u003cp align=\"center\"\u003e\n   \u003cimg style='width: 100%' alt=\"Create a new app in heroku 3\" src=\"./.readme-static/create-a-new-app-in-heroku-3.png\" /\u003e\n\u003c/p\u003e\n\n#### Deployment method: Heroku CLI\n\nDownload and install the [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli).\n\nIf you haven't already, log in to your Heroku account and follow the prompts to create a new SSH public key.\n\n```\nheroku login\n```\n\n##### Create a new Git repository\n\nInitialize a git repository in a new or existing directory\n\n```\ncd my-project/\ngit init\nheroku git:remote -a \u003capp_name\u003e\n```\n\n##### Deploy your application\n\nCommit your code to the repository and deploy it to Heroku using Git.\n\n```\ngit add .\ngit commit -am \"make it better\"\ngit push heroku master\n```\n\n##### Deploy your application\n\nFor existing repositories, simply add the heroku remote\n\n```\nheroku git:remote -a \u003capp_name\u003e\n```\n\n#### Deployment method: GitHub\n\nWe click on the connect to GitHub button, if you've never connected Heroku to Github, a window will open to authorize the connection so you can continue with the step of entering the name of the repository and searching it in your GitHub account, and once you find it, we click on the Connect button.\n\n\u003cp align=\"center\"\u003e\n   \u003cimg style='width: 100%' alt=\"Create a new app in heroku 4\" src=\"./.readme-static/create-a-new-app-in-heroku-4.png\" /\u003e\n\u003c/p\u003e\n\nThen we select the branch we want to deploy, and click on Deploy Branch, and it will start running the deployment, downloading the code from the repository, installing the dependencies, etc.\n\n\u003cp align=\"center\"\u003e\n   \u003cimg style='width: 100%' alt=\"Create a new app in heroku 5\" src=\"./.readme-static/create-a-new-app-in-heroku-5.png\" /\u003e\n\u003c/p\u003e\n\n4. Now we have to configure the environment variables of the server, although we can do it manually from **Settings \u003e Config Vars**, there is a bash script prepared that will raise the environment variables of our `.env` file that is located in the `./variables` folder.\n\n```\nnpm run heroku:envs\n```\n\nor\n\n```\nbash heroku-envs.sh\n```\n\n\u003cp align=\"center\"\u003e\n   \u003cimg style='width: 100%' alt=\"Create a new app in heroku 6\" src=\"./.readme-static/create-a-new-app-in-heroku-6.png\" /\u003e\n\u003c/p\u003e\n\n\u003ca name=\"setup-the-facebook-app\"\u003e\u003c/a\u003e\n\n## 📱 Setup the Facebook App\n\nThe time has come to create and configure our app on Facebook.\n\nWith the local server and the connection tunnel initialized, we will configure the app, and with the information that it will give us we will finish configuring the data that we are missing in the bot's server.\n\n\u003e 💬 Remember that the bot's server is in watch mode, and any changes made will be re-initialized and take the changes made.\n\n1. Enter [Facebook Developers](https://developers.facebook.com/apps/) and click on create app, it will open a modal to select the type of application, in our case we will create an application type \"**Manage business integrations**\".\n\u003cp align=\"center\"\u003e\n  \u003cimg style='width: 100%' alt=\"Create a new app on facebook\" src=\"./.readme-static/create-a-new-app-on-facebook.png\" /\u003e\n\u003c/p\u003e\n\n2. Now we will have to make some basic settings for the application.\n\n   We assign a name of the app to identify it, we put a contact email, we select the purpose of the app, in this case is for us, and if we have a commercial administrator account, we select one from the list, if you do not have such an account, you can create it later.\n\n   Once the information is completed, we click on **Create App identifier**\n    \u003cp align=\"center\"\u003e\n      \u003cimg style='width: 100%' alt=\"Basic settings new app on facebook\" src=\"./.readme-static/basic-settings-new-app-on-facebook.png\" /\u003e\n    \u003c/p\u003e\n\n3. Then we look for **Messenger** in the app's product list, and hit the configure button.\n\u003cp align=\"center\"\u003e\n  \u003cimg style='width: 100%' alt=\"Settings new app on facebook 1\" src=\"./.readme-static/settings-new-app-on-facebook-1.png\" /\u003e\n\u003c/p\u003e\n\n4. Now we are going to make the two necessary and essential configurations to be able to connect Facebook with our bot server.\n\n    \u003cp align=\"center\"\u003e\n      \u003cimg style='width: 100%' alt=\"Settings new app on facebook 2\" src=\"./.readme-static/settings-new-app-on-facebook-2.png\" /\u003e\n    \u003c/p\u003e\n    \n   #### Access tokens\n   In this part of the configuration, we will be able to manage which page or pages of facebook will have the bot available.\n   We click on **Add or Remove pages**, and select the page.\n\n    \u003cp align=\"center\"\u003e\n      \u003cimg style='width: 100%' alt=\"Settings new app on facebook 3\" src=\"./.readme-static/settings-new-app-on-facebook-3.png\" /\u003e\n    \u003c/p\u003e\n    \n    Once the page is linked to the app, we have to generate the token by clicking on the button **Generate Token**, and a window will open where you give us some instructions about the token. \n    \n    We must check accept in order to view the full hash, then copy it and place it in the configuration of our server, if it is for development it is put in the json of `./config/development.json` in the key of `accessToken`, and if it is for a productive environment, we must put it in the envs file in `./variables`.\n    \n    \u003cp align=\"center\"\u003e\n        \u003cimg style='width: 100%' alt=\"Settings new app on facebook 4\" src=\"./.readme-static/settings-new-app-on-facebook-4.png\" /\u003e\n    \u003c/p\u003e\n    \n    ```json5\n    {\n      ...\n      params: {\n        ...\n        accessToken: '\u003caccess_token\u003e',\n        ...\n      },\n     ...\n    }\n    ```\n    \n    #### Webhooks\n    Now we have to configure the connection between Facebook and our server through **Webhook**, for this, you must have at hand the `verifyToken` that you configured and the bot's server url, in this case, we will use the one provided by **ngrok** with ssl.\n    ```\n   https://\u003cid_tunnel\u003e.ngrok.io/api/webhook/\n   ```\n    \u003cp align=\"center\"\u003e\n        \u003cimg style='width: 100%' alt=\"Settings new app on facebook 5\" src=\"./.readme-static/settings-new-app-on-facebook-5.png\" /\u003e\n    \u003c/p\u003e\n    \n    Then click on **Verify and Save**, and if everything goes well, in the server terminal you should see the successful subscription message.\n    \n    \u003cp align=\"center\"\u003e\n        \u003cimg style='width: 100%' alt=\"Config webhook subscription response terminal\" src=\"./.readme-static/config-webhook-subscription-response-terminal.png\" /\u003e\n    \u003c/p\u003e\n    \n    If the url of the webhook by ngrok changes, or you want to configure the url of the productive server, you can do it by clicking on the button **Edit Callback URL** and perform again the previous steps.\n    \n    #### Add subscriptions\n    Now we have to add the subscriptions that will allow the bot to have certain permissions to perform the actions we need.\n    \n    For that we click on the button **Add subscriptions**\n    \n    \u003cp align=\"center\"\u003e\n        \u003cimg style='width: 100%' alt=\"Settings new app on facebook 6\" src=\"./.readme-static/settings-new-app-on-facebook-6.png\" /\u003e\n    \u003c/p\u003e\n    \n    Select from the list the basic permissions and click on **Save** \n    \n    Then we add each permission to the configuration files separated by a comma.\n    \n    \u003cp align=\"center\"\u003e\n        \u003cimg style='width: 100%' alt=\"Settings new app on facebook 7\" src=\"./.readme-static/settings-new-app-on-facebook-7.png\" /\u003e\n    \u003c/p\u003e\n    \n    ```json5\n    {\n      ...\n      params: {\n        ...\n        subscribedFields: 'messages,messaging_postbacks,messaging_optins',\n        ...\n      },\n      ...\n    }\n    ```\n\n5. These are the last settings to be made and are optional.\n   It consists in executing a curl script in the terminal to implement some options, don't forget to put the access token to make it work.\n\n   \u003e 💬 Note: You can run these scripts from Swagger, but you must adjust the files that are inside the `./templates/configs` folder\n\n   #### Add button Get Started\n\n   ```bash\n   curl -X POST -H \"Content-Type: application/json\" -d '{\n        \"get_started\": {\n            \"payload\": \"GET_STARTED_PAYLOAD\"\n        }\n   }' \"https://graph.facebook.com/v8.0/me/messenger_profile?access_token=\u003caccess_token\u003e\"\n   ```\n\n   #### Add greeting\n\n   ```bash\n   curl -X POST -H \"Content-Type: application/json\" -d '{\n   \"greeting\": [\n        {\n            \"locale\": \"default\",\n            \"text\": \"Hi {{user_first_name}}, i'm a bot!\"\n        }\n   ]\n   }' \"https://graph.facebook.com/v8.0/me/messenger_profile?access_token=\u003caccess_token\u003e\"\n   ```\n\n   #### Add persistent menu\n\n   ```bash\n   curl -X POST -H \"Content-Type: application/json\" -d '{\n      \"persistent_menu\":[\n         {\n            \"locale\":\"default\",\n            \"composer_input_disabled\":false,\n            \"call_to_actions\":[\n               {\n                  \"title\":\"About us\",\n                  \"type\":\"postback\",\n                  \"payload\":\"ABOUT_US_PAYLOAD\"\n               },\n               {\n                  \"title\":\"Contact\",\n                  \"type\":\"postback\",\n                  \"payload\":\"CONTACT_PAYLOAD\"\n               },\n               {\n                  \"type\":\"web_url\",\n                  \"title\":\"💻 Visit my Website\",\n                  \"url\":\"http://misite.com/\",\n                  \"webview_height_ratio\":\"full\"\n               }\n            ]\n         }\n      ]\n   }' \"https://graph.facebook.com/v8.0/me/messenger_profile?access_token=\u003caccess_token\u003e\"\n   ```\n\n   #### Remove persistent menu\n\n   ```bash\n   curl -X DELETE -H \"Content-Type: application/json\" -d '{\n       \"fields\":[\n            \"persistent_menu\"\n       ]\n   }' \"https://graph.facebook.com/v8.0/me/messenger_profile?access_token=\u003caccess_token\u003e\"\n   ```\n\n### 🙌 End of configuration\n\nWe have finished configuring the app so that Facebook connects to the bot's server, now we have to test it, to do this we can enter the chat page and perform a test to verify that everything is working properly.\n\n\u003ca name=\"how-to-share-your-bot\"\u003e\u003c/a\u003e\n\n## 📡 How to share your bot\n\nAdd a chat button to your webpage, go [here](https://developers.facebook.com/docs/messenger-platform/plugin-reference) to learn how to add a chat button your page.\n\n\u003ca name=\"create-a-shortlink\"\u003e\u003c/a\u003e\n\n#### 🔗 Create a shortlink\n\nYou can use page username to have someone start a chat.\n\n```\nhttps://m.me/\u003cPAGE_USERNAME\u003e\n```\n\n\u003ca name=\"setup-the-workplace-app\"\u003e\u003c/a\u003e\n\n## 📱 Setup the Workplace App\n\nThe configuration of the app for Workplace is quite similar to that of Facebook, it is required to have the Workplace paid account in order to enable custom integrations.\n\n1. Go to the **Administrator Panel**, and click on the **Integrations** button, and in the Custom integrations section click on the **Create custom integration** button.\n\n   It will open a modal where we must write the name of the application and a description, then click on **Create**.\n\n   \u003cp align=\"center\"\u003e\n       \u003cimg style='width: 100%' alt=\"Settings new app on workplace 1\" src=\"./.readme-static/settings-new-app-on-workplace-1.png\" /\u003e\n   \u003c/p\u003e\n\n2. Once the application is created, it takes us to the configuration page of the application.\n\n   \u003cp align=\"center\"\u003e\n       \u003cimg style='width: 100%' alt=\"Settings new app on workplace 2\" src=\"./.readme-static/settings-new-app-on-workplace-2.png\" /\u003e\n   \u003c/p\u003e\n    \n    #### Access token\n\n   Now we are going to generate an access token and then configure it in our config, as mentioned in the configuration of the Facebook app.\n\n   \u003cp align=\"center\"\u003e\n       \u003cimg style='width: 100%' alt=\"Settings new app on workplace 3\" src=\"./.readme-static/settings-new-app-on-workplace-3.png\" /\u003e\n   \u003c/p\u003e\n\n3. Now let's select the permissions for our bot.\n\n   #### Permissions\n\n   In our case we are interested in the option of **Sending a message to any member**.\n\n   \u003cp align=\"center\"\u003e\n       \u003cimg style='width: 100%' alt=\"Settings new app on workplace 4\" src=\"./.readme-static/settings-new-app-on-workplace-4.png\" /\u003e\n   \u003c/p\u003e\n\n4. Now we are going to **grant the integration access to groups**, in this case it is going to be to a specific group.\n\n\u003cp align=\"center\"\u003e\n    \u003cimg style='width: 100%' alt=\"Settings new app on workplace 5\" src=\"./.readme-static/settings-new-app-on-workplace-5.png\" /\u003e\n\u003c/p\u003e\n\n5. And finally, we have to configure the **Webhook** and the **verify token** and select the **subscriptions** we need, as we did with the Facebook app.\n\n   \u003cp align=\"center\"\u003e\n       \u003cimg style='width: 100%' alt=\"Settings new app on workplace 6\" src=\"./.readme-static/settings-new-app-on-workplace-6.png\" /\u003e\n   \u003c/p\u003e\n\n   \u003e 💬 Note: depending on the webhook configuration you select in the tabs, the subscriptions will change.\n\n6. 🙌 Finally we click on the save button.\n\n   \u003e 💬 Note: there is an optional configuration which is the security one, where it is required to enter the ip of the bot's server, the domain, etc.\n\n   \u003cp align=\"center\"\u003e\n       \u003cimg style='width: 100%' alt=\"Settings new app on workplace 7\" src=\"./.readme-static/settings-new-app-on-workplace-7.png\" /\u003e\n   \u003c/p\u003e\n\n\u003ca name=\"security-configuration\"\u003e\u003c/a\u003e\n## 🔐 Security Configuration\n\nTo give more security to the application, both for **Facebook** and **Workplace**, it is important to have completed the environment variable `appSecret` and have set `true` the `requireProof` for the bot to work properly with these new settings.\n\n```json5\n{\n  ...\n  \"params\": {\n    \"appSecret\": \"\u003capp_secret_key\u003e\",\n    ...    \n    \"requireProof\": true\n  }\n  ...\n}\n```\n\nFor both cases, it is required to have the **public IP** of the server, since that way, it will only be limited to receive and send requests from a single authorized server. \n\nIf you have more than one **public IP**, or another server to balance the bot's requests, you can add it to the list.\n\n#### Facebook App\n\nIn the configuration of the app, we go to the left side menu and go to **Settings \u003e Advanced**, and then down to the **Security** section, where we will enter our **public IP**, and then we will activate the option **Require secret key of the app**.\n\n\u003cp align=\"center\"\u003e\n    \u003cimg style='width: 100%' alt=\"Settings new app on facebook 8\" src=\"./.readme-static/settings-new-app-on-facebook-8.png\" /\u003e\n\u003c/p\u003e\n\n#### Workplace App\n\nIn the configuration of the app, we go down to the **Security Settings** section, where we will activate the option to **require a secret key test of the app**, and then we will enter our **public IP**.\n\n\n\u003cp align=\"center\"\u003e\n    \u003cimg style='width: 100%' alt=\"Settings new app on workplace 8\" src=\"./.readme-static/settings-new-app-on-workplace-8.png\" /\u003e\n\u003c/p\u003e\n\n\u003ca name=\"troubleshooting\"\u003e\u003c/a\u003e\n\n## 🤦‍♂️Troubleshooting\n\n#### Workplace App\n\n##### ❌ (#200) To subscribe to the messages field\n\n\u003e (#200) To subscribe to the messages field, one of these permissions is needed: pages_messaging. To subscribe to the messaging_postbacks field, one of these permissions is needed: pages_messaging\n\nYou can solve this problem by configuring the webhook without selecting the subscriptions, then saving the configuration, then re-entering the app configuration and re-validating the webhook with the selected subscriptions.\n\n\u003ca name=\"contributing\"\u003e\u003c/a\u003e\n\n## 💡 Contributing\n\nRequests are welcome. For important changes, please open a topic first to discuss what you would like to change.\n\nPlease be sure to update the tests and documentation as appropriate.\n\n\u003ca name=\"author\"\u003e\u003c/a\u003e\n\n## 👨‍💻 Author\n\n[![badge](https://img.shields.io/static/v1.svg?style=flat-square\u0026label=Mex%20Delgado\u0026message=Sr.%20Fullstack%20Developer\u0026labelColor=1A1A1A\u0026color=999999\u0026logo=hackaday)](mailto:mdelgado@tresdoce.com.ar 'Send email to Mex')\n\n\u003ca name=\"license\"\u003e\u003c/a\u003e\n📜 [License MIT](license.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frudemex%2Ffb-messenger-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frudemex%2Ffb-messenger-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frudemex%2Ffb-messenger-bot/lists"}