{"id":13527004,"url":"https://github.com/Charca/bootbot","last_synced_at":"2025-04-01T09:30:57.566Z","repository":{"id":9541892,"uuid":"62478811","full_name":"Charca/bootbot","owner":"Charca","description":"Facebook Messenger Bot Framework for Node.js","archived":false,"fork":false,"pushed_at":"2023-03-01T22:31:51.000Z","size":263,"stargazers_count":974,"open_issues_count":73,"forks_count":255,"subscribers_count":41,"default_branch":"master","last_synced_at":"2025-03-23T03:33:22.025Z","etag":null,"topics":["bot","chatbot-framework","facebook","messenger"],"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/Charca.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2016-07-03T02:55:03.000Z","updated_at":"2025-03-20T11:04:36.000Z","dependencies_parsed_at":"2024-01-13T22:31:00.036Z","dependency_job_id":"e71eb129-66c0-42e0-a152-92c319449aba","html_url":"https://github.com/Charca/bootbot","commit_stats":{"total_commits":122,"total_committers":18,"mean_commits":6.777777777777778,"dds":"0.29508196721311475","last_synced_commit":"b8aa7109d094e529d530ba526d039721a99db19d"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Charca%2Fbootbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Charca%2Fbootbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Charca%2Fbootbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Charca%2Fbootbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Charca","download_url":"https://codeload.github.com/Charca/bootbot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246615918,"owners_count":20806028,"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":["bot","chatbot-framework","facebook","messenger"],"created_at":"2024-08-01T06:01:39.091Z","updated_at":"2025-04-01T09:30:57.130Z","avatar_url":"https://github.com/Charca.png","language":"JavaScript","readme":"\u003cp align=\"center\"\u003e\n\t\u003cimg src=\"./assets/logo.png\" /\u003e\n\u003c/p\u003e\n\nBootBot is a simple but powerful JavaScript Framework to build Facebook Messenger's Chat bots.\n\n| [Features][] | [Usage][] | [Video Example][] | [Getting Started][] | [Documentation][] | [Examples][] | [Credits][] | [License][] |\n|---|---|---|---|---|---|---|---|\n\n\n**[ :speech_balloon: Questions / Comments? Join our Slack channel!](https://bootbot-slack-channel.herokuapp.com/)**\n\n## Features\n\n- Helper methods to **send** any type of message supported by Facebook.\n- **Subscribe** to a particular type of message, or to certain **keywords** sent by the user.\n- Start **conversations**, **ask** questions and save important information in the **context** of the conversation.\n- Organize your code in **modules**.\n- Send automatic or manual **typing indicators**.\n- Set your bot's properties, such as a **persistent menu**, a **greeting text** or a **get started CTA**.\n- Subscribe to **received** and **read** events.\n\n## Usage\n\n```\n$ npm install bootbot --save\n```\n\n```javascript\n'use strict';\nconst BootBot = require('bootbot');\n\nconst bot = new BootBot({\n  accessToken: 'FB_ACCESS_TOKEN',\n  verifyToken: 'FB_VERIFY_TOKEN',\n  appSecret: 'FB_APP_SECRET'\n});\n\nbot.on('message', (payload, chat) =\u003e {\n  const text = payload.message.text;\n  chat.say(`Echo: ${text}`);\n});\n\nbot.start();\n```\n\n## Video Example\n\nCreating a Giphy Chat Bot in 3 minutes:\n\n[![IMG](http://i.imgur.com/gDL7Tw2.gif)](https://www.youtube.com/watch?v=flYeg7Hdxzw\u0026feature=youtu.be)\n\n## Getting Started\n\n- Install BootBot via NPM, create a new `index.js`, require BootBot and create a new bot instance using your Facebook Page's / App's `accessToken`, `verifyToken` and `appSecret`:\n\n**Note:** If you don't know how to get these tokens, take a look at Facebook's [Quick Start Guide](https://developers.facebook.com/docs/messenger-platform/guides/quick-start) or check out [this issue](https://github.com/Charca/bootbot/issues/56).\n\n```javascript\n// index.js\n'use strict';\nconst BootBot = require('bootbot');\n\nconst bot = new BootBot({\n  accessToken: 'FB_ACCESS_TOKEN',\n  verifyToken: 'FB_VERIFY_TOKEN',\n  appSecret: 'FB_APP_SECRET'\n});\n```\n\n- Subscribe to messages sent by the user with the `bot.on()` and `bot.hear()` methods:\n\n```javascript\nbot.on('message', (payload, chat) =\u003e {\n\tconst text = payload.message.text;\n\tconsole.log(`The user said: ${text}`);\n});\n\nbot.hear(['hello', 'hi', /hey( there)?/i], (payload, chat) =\u003e {\n\tconsole.log('The user said \"hello\", \"hi\", \"hey\", or \"hey there\"');\n});\n```\n\n- Reply to user messages using the `chat` object:\n\n```javascript\nbot.hear(['hello', 'hi', /hey( there)?/i], (payload, chat) =\u003e {\n\t// Send a text message followed by another text message that contains a typing indicator\n\tchat.say('Hello, human friend!').then(() =\u003e {\n\t\tchat.say('How are you today?', { typing: true });\n\t});\n});\n\nbot.hear(['food', 'hungry'], (payload, chat) =\u003e {\n\t// Send a text message with quick replies\n\tchat.say({\n\t\ttext: 'What do you want to eat today?',\n\t\tquickReplies: ['Mexican', 'Italian', 'American', 'Argentine']\n\t});\n});\n\nbot.hear(['help'], (payload, chat) =\u003e {\n\t// Send a text message with buttons\n\tchat.say({\n\t\ttext: 'What do you need help with?',\n\t\tbuttons: [\n\t\t\t{ type: 'postback', title: 'Settings', payload: 'HELP_SETTINGS' },\n\t\t\t{ type: 'postback', title: 'FAQ', payload: 'HELP_FAQ' },\n\t\t\t{ type: 'postback', title: 'Talk to a human', payload: 'HELP_HUMAN' }\n\t\t]\n\t});\n});\n\nbot.hear('image', (payload, chat) =\u003e {\n\t// Send an attachment\n\tchat.say({\n\t\tattachment: 'image',\n\t\turl: 'http://example.com/image.png'\n\t});\n});\n```\n\n- Start a conversation and keep the user's answers in `context`:\n\n```javascript\nbot.hear('ask me something', (payload, chat) =\u003e {\n\n\tconst askName = (convo) =\u003e {\n\t\tconvo.ask(`What's your name?`, (payload, convo) =\u003e {\n\t\t\tconst text = payload.message.text;\n\t\t\tconvo.set('name', text);\n\t\t\tconvo.say(`Oh, your name is ${text}`).then(() =\u003e askFavoriteFood(convo));\n\t\t});\n\t};\n\n\tconst askFavoriteFood = (convo) =\u003e {\n\t\tconvo.ask(`What's your favorite food?`, (payload, convo) =\u003e {\n\t\t\tconst text = payload.message.text;\n\t\t\tconvo.set('food', text);\n\t\t\tconvo.say(`Got it, your favorite food is ${text}`).then(() =\u003e sendSummary(convo));\n\t\t});\n\t};\n\n\tconst sendSummary = (convo) =\u003e {\n\t\tconvo.say(`Ok, here's what you told me about you:\n\t      - Name: ${convo.get('name')}\n\t      - Favorite Food: ${convo.get('food')}`);\n      convo.end();\n\t};\n\n\tchat.conversation((convo) =\u003e {\n\t\taskName(convo);\n\t});\n});\n```\n\n- Set up webhooks and start the express server:\n\n```javascript\nbot.start();\n```\n\n- Start up your bot by running node:\n\n```\n$ node index.js\n\u003e BootBot running on port 3000\n\u003e Facebook Webhook running on localhost:3000/webhook\n```\n\n- If you want to test your bot locally, install a localhost tunnel like [ngrok](https://ngrok.com/) and run it on your bot's port:\n\n```\n$ ngrok http 3000\n```\n\nThen use the provided HTTPS URL to config your webhook on Facebook's Dashboard. For example if the URL provided by ngrok is `https://99b8d4c2.ngrok.io`, use `https://99b8d4c2.ngrok.io/webhook`.\n\n## Documentation\n\n### BootBot Class\n\n#### `new BootBot(options)`\n\n| `options` key | Type | Default | Required |\n|:--------------|:-----|:--------|:---------|\n| `accessToken` | string | | `Y` |\n| `verifyToken` | string | | `Y` |\n| `appSecret` | string | | `Y` |\n| `webhook` | string | `\"/webhook\"` | `N` |\n| `broadcastEchoes` | boolean | `false` | `N` |\n| `graphApiVersion` | string | `v2.12` | `N` |\n\nCreates a new `BootBot` instance. Instantiates the new express app and all required webhooks. `options` param must contain all tokens and app secret of your Facebook app. Optionally, set `broadcastEchoes` to `true` if you want the messages your bot send to be echoed back to it (you probably don't need this feature unless you have multiple bots running on the same Facebook page).\n\nIf you want to specify a custom endpoint name for your webhook, you can do it with the `webhook` option.\n\n#### `.start([ port ])`\n\n| Param | Type | Default | Required |\n|:------|:-----|:--------|:---------|\n| `port` | number | `3000` | `N` |\n\nStarts the express server on the specified port. Defaults port to 3000.\n\n#### `.close()`\n\nCloses the express server (calls `.close()` on the server instance).\n\n---\n\n### Receive API\n\nUse these methods to subscribe your bot to messages, attachments or anything the user might send.\n\n#### `.on(event, callback)`\n\n| Param | Type | Default | Required |\n|:------|:-----|:--------|:---------|\n| `event` | string | | `Y` |\n| `callback` | function | | `Y` |\n\nSubscribe to an event emitted by the bot, and execute a callback when those events are emitted. Available events are:\n\n| Event | Description |\n|:------|:-----|\n| `message` | The bot received a text message from the user |\n| `quick_reply` | The bot received a quick reply from the user (quick replies emit both `message` and `quick_reply` events) |\n| `attachment` | The bot received an attachment from the user |\n| `postback` | The bot received a postback call from the user (usually means the user clicked a button) |\n| `delivery` | The bot received a confirmation that your message was delivered to the user |\n| `read` | The bot received a confirmation that your message was read by the user |\n| `authentication` | A user has started a conversation with the bot using a \"Send to Messenger\" button |\n| `referral` | A user that already has a thread with the bot starts a conversation. [more](https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/messaging_referrals) |\n\nYou can also subscribe to specific postbacks and quick replies by using a namespace. For example `postback:ADD_TO_CART` subscribes only to the postback event containing the `ADD_TO_CART` payload.\n\nIf you want to subscribe to specific keywords on a `message` event, see the `.hear()` method below.\n\nWhen these events ocurr, the specified callback will be invoked with 3 params: `(payload, chat, data)`\n\n| Param | Description |\n|:------|:-----|\n| `payload` | The data sent by the user (contains the text of the message, the attachment, etc.) |\n| `chat` | A `Chat` instance that you can use to reply to the user. Contains all the methods defined in the [Send API](#send-api) |\n| `data` | Contains extra data provided by the framework, like a `captured` flag that signals if this message was already captured by a different callback |\n\n##### `.on()` examples:\n\n```javascript\nbot.on('message', (payload, chat) =\u003e {\n\tconsole.log('A text message was received!');\n});\n\nbot.on('attachment', (payload, chat) =\u003e {\n\tconsole.log('An attachment was received!');\n});\n\nbot.on('postback:HELP_ME', (payload, chat) =\u003e {\n\tconsole.log('The Help Me button was clicked!');\n});\n\nbot.on('message', (payload, chat) =\u003e {\n\t// Reply to the user\n\tchat.say('Hey, user. I got your message!');\n});\n```\n\n#### `.hear(keywords, callback)`\n\n| Param | Type | Default | Required |\n|:------|:-----|:--------|:---------|\n| `keywords` | string, regex or mixed array | | `Y` |\n| `callback` | function | | `Y` |\n\nA convinient method to subscribe to `message` events containing specific keywords. The `keyword` param can be a string, a regex or an array of both strings and regexs that will be tested against the received message. If the bot receives a message that matches any of the keywords, it will execute the specified `callback`. String keywords are case-insensitive, but regular expressions are not case-insensitive by default, if you want them to be, specify the `i` flag.\n\nThe callback's signature is identical to that of the `.on()` method above.\n\n##### `.hear()` examples:\n\n```javascript\nbot.hear('hello', (payload, chat) =\u003e {\n\tchat.say('Hello, human!');\n});\n\nbot.hear(['hello', 'hi', 'hey'], (payload, chat) =\u003e {\n\tchat.say('Hello, human!');\n});\n\nbot.hear([/(good)?bye/i, /see (ya|you)/i, 'adios'], (payload, chat) =\u003e {\n\t// Matches: goodbye, bye, see ya, see you, adios\n\tchat.say('Bye, human!');\n});\n```\n\n**Note** that if a bot is subscribed to both the `message` event using the `.on()` method and a specific keyword using the `.hear()` method, the event will be emitted to both of those subscriptions. If you want to know if a message event was already captured by a different subsciption, you can check for the `data.captured` flag on the callback.\n\n---\n\n### Send API\n\nBootBot provides helper methods for every type of message supported by Facebook's Messenger API. It also provides a generic `sendMessage` method that you can use to send a custom payload. All messages from the Send API return a Promise that you can use to apply actions after a message was successfully sent. You can use this to send consecutive messages and ensure that they're sent in the right order.\n\n#### Important Note:\nThe Send API methods are shared between the `BootBot`, `Chat` and `Conversation` instances, the only difference is that when you use any of these methods from the `Chat` or `Conversation` instances, you don't have to specify the `userId`.\n\nExample - These two methods are identical:\n\n```javascript\nbot.on('message', (payload, chat) =\u003e {\n  const text = payload.message.text;\n  const userId = payload.sender.id;\n  bot.say(userId, 'Hello World');\n});\n\n// is the same as...\n\nbot.on('message', (payload, chat) =\u003e {\n  const text = payload.message.text;\n  chat.say('Hello World');\n});\n```\n\nYou'll likely use the Send API methods from the `Chat` or `Conversation` instances (ex: `chat.say()` or `convo.say()`), but  you can use them from the `BootBot` instance if you're not in a chat or conversation context (for example, when you want to send a notification to a user).\n\n#### `.say()`\n\n| Method signature |\n|:-----------------|\n| `chat.say(message, [ options ])` |\n| `convo.say(message, [ options ])` |\n| `bot.say(userId, message, [ options ])` |\n\nSend a message to the user. The `.say()` method can be used to send text messages, button messages, messages with quick replies or attachments. If you want to send a different type of message (like a generic template), see the Send API method for that specific type of message.\n\nThe `message` param can be a string an array, or an object:\n\n- If `message` is a string, the bot will send a text message.\n- If `message` is an array, the `.say()` method will be called once for each element in the array.\n- If `message` is an object, the message type will depend on the object's format:\n\n```javascript\n// Send a text message\nchat.say('Hello world!');\n\n// Send a text message with quick replies\nchat.say({\n\ttext: 'Favorite color?',\n\tquickReplies: ['Red', 'Blue', 'Green']\n});\n\n// Send a button template\nchat.say({\n\ttext: 'Favorite color?',\n\tbuttons: [\n\t\t{ type: 'postback', title: 'Red', payload: 'FAVORITE_RED' },\n\t\t{ type: 'postback', title: 'Blue', payload: 'FAVORITE_BLUE' },\n\t\t{ type: 'postback', title: 'Green', payload: 'FAVORITE_GREEN' }\n\t]\n});\n\n// Send a list template\nchat.say({\n\telements: [\n\t\t{ title: 'Artile 1', image_url: '/path/to/image1.png', default_action: {} },\n\t\t{ title: 'Artile 2', image_url: '/path/to/image2.png', default_action: {} }\n\t],\n\tbuttons: [\n\t\t{ type: 'postback', title: 'View More', payload: 'VIEW_MORE' }\n\t]\n});\n\n// Send a generic template\nchat.say({\n\tcards: [\n\t\t{ title: 'Card 1', image_url: '/path/to/image1.png', default_action: {} },\n\t\t{ title: 'Card 2', image_url: '/path/to/image2.png', default_action: {} }\n\t]\n});\n\n// Send an attachment\nchat.say({\n\tattachment: 'video',\n\turl: 'http://example.com/video.mp4'\n});\n\n// Passing an array will make subsequent calls to the .say() method\n// For example, calling:\n\nchat.say(['Hello', 'How are you?']);\n\n// is the same as:\n\nchat.say('Hello').then(() =\u003e {\n  chat.say('How are you?')\n});\n```\n\nThe `options` param can contain:\n\n| `options` key | Type | Default | Description |\n|:--------------|:-----|:--------|:---------|\n| `typing` | boolean or number | `false` | Send a typing indicator before sending the message. If set to `true`, it will automatically calculate how long it lasts based on the message length. If it's a number, it will show the typing indicator for that amount of milliseconds (max. `20000` - 20 seconds) |\n| `messagingType` | string | `'RESPONSE'` | The messaging type of the message being sent. |\n| `notificationType` | string | | Push notification type: `'REGULAR'`: sound/vibration - `'SILENT_PUSH'`: on-screen notification only - `'NO_PUSH'`: no notification. |\n| `tag` | string | | The message tag string. Can only be used if `messagingType` is set to `'MESSAGE_TAG'` |\n| `onDelivery` | function | | Callback that will be executed when the message is received by the user. Receives params: `(payload, chat, data)` |\n| `onRead` | function | | Callback that will be executed when the message is read by the user. Receives params: `(payload, chat, data)` |\n\n#### `.sendTextMessage()`\n\n| Method signature |\n|:-----------------|\n| `chat.sendTextMessage(text, [ quickReplies, options ])` |\n| `convo.sendTextMessage(text, [ quickReplies, options ])` |\n| `bot.sendTextMessage(userId, text, [ quickReplies, options ])` |\n\nThe `text` param must be a string containing the message to be sent.\n\nThe `quickReplies` param can be an array of strings or [quick_reply objects](https://developers.facebook.com/docs/messenger-platform/send-api-reference/quick-replies).\n\nThe `options` param is identical to the `options` param of the [`.say()`](#say) method.\n\n#### `.sendButtonTemplate()`\n\n| Method signature |\n|:-----------------|\n| `chat.sendButtonTemplate(text, buttons, [ options ])` |\n| `convo.sendButtonTemplate(text, buttons, [ options ])` |\n| `bot.sendButtonTemplate(userId, text, buttons, [ options ])` |\n\nThe `text` param must be a string containing the message to be sent.\n\nThe `buttons` param can be an array of strings or [button objects](https://developers.facebook.com/docs/messenger-platform/send-api-reference/button-template).\n\nThe `options` param is identical to the `options` param of the [`.say()`](#say) method.\n\n#### `.sendGenericTemplate()`\n\n| Method signature |\n|:-----------------|\n| `chat.sendGenericTemplate(elements, [ options ])` |\n| `convo.sendGenericTemplate(elements, [ options ])` |\n| `bot.sendGenericTemplate(userId, elements, [ options ])` |\n\nThe `elements` param must be an array of [element objects](https://developers.facebook.com/docs/messenger-platform/send-api-reference/generic-template).\n\nThe `options` param extends `options` param of the [`.say()`](#say) method with `imageAspectRatio` property.\n\n#### `.sendListTemplate()`\n\n| Method signature |\n|:-----------------|\n| `chat.sendListTemplate(elements, buttons, [ options ])` |\n| `convo.sendListTemplate(elements, buttons, [ options ])` |\n| `bot.sendListTemplate(userId, elements, buttons, [ options ])` |\n\nThe `elements` param must be an array of [element objects](https://developers.facebook.com/docs/messenger-platform/send-api-reference/list-template).\n\nThe `buttons` param can be an array with one element: string or [button object](https://developers.facebook.com/docs/messenger-platform/send-api-reference/list-template).\n\nThe `options` param extends `options` param of the [`.say()`](#say) method with `topElementStyle` property.\n\n#### `.sendTemplate()`\n\n| Method signature |\n|:-----------------|\n| `chat.sendTemplate(payload, [ options ])` |\n| `convo.sendTemplate(payload, [ options ])` |\n| `bot.sendTemplate(userId, payload, [ options ])` |\n\nUse this method if you want to send a custom template `payload`, like a [receipt template](https://developers.facebook.com/docs/messenger-platform/send-api-reference/receipt-template) or an [airline itinerary template](https://developers.facebook.com/docs/messenger-platform/send-api-reference/airline-itinerary-template).\n\nThe `options` param is identical to the `options` param of the [`.say()`](#say) method.\n\n#### `.sendAttachment()`\n\n| Method signature |\n|:-----------------|\n| `chat.sendAttachment(type, url, [ quickReplies, options ])` |\n| `convo.sendAttachment(type, url, [ quickReplies, options ])` |\n| `bot.sendAttachment(userId, type, url, [ quickReplies, options ])` |\n\nThe `type` param must be `'image'`, `'audio'`, `'video'` or `'file'`.\n\nThe `url` param must be a string with the URL of the attachment.\n\nThe `quickReplies` param can be an array of strings or [quick_reply objects](https://developers.facebook.com/docs/messenger-platform/send-api-reference/quick-replies).\n\nThe `options` param is identical to the `options` param of the [`.say()`](#say) method.\n\n#### `.sendAction()`\n\n| Method signature |\n|:-----------------|\n| `chat.sendAction(action, [ options ])` |\n| `convo.sendAction(action, [ options ])` |\n| `bot.sendAction(userId, action, [ options ])` |\n\nThe `action` param must be `'mark_seen'`, `'typing_on'` or `'typing_off'`. To send a typing indicator in a more convenient way, see the [`.sendTypingIndicator`](#sendtypingindicator) method.\n\nThe `options` param is identical to the `options` param of the [`.say()`](#say) method.\n\n#### `.sendMessage()`\n\n| Method signature |\n|:-----------------|\n| `chat.sendMessage(message, [ options ])` |\n| `convo.sendMessage(message, [ options ])` |\n| `bot.sendMessage(userId, message, [ options ])` |\n\nUse this method if you want to send a custom `message` object.\n\nThe `options` param is identical to the `options` param of the [`.say()`](#say) method.\n\n#### `.sendTypingIndicator()`\n\n| Method signature |\n|:-----------------|\n| `chat.sendTypingIndicator(milliseconds)` |\n| `convo.sendTypingIndicator(milliseconds)` |\n| `bot.sendTypingIndicator(userId, milliseconds)` |\n\nConvinient method to send a `typing_on` action and then a `typing_off` action after `milliseconds` to simulate the bot is actually typing. Max value is 20000 (20 seconds).\n\nYou can also use this method via the `typing` option (see [`.say()`](#say) method).\n\n#### `.getUserProfile()`\n\n| Method signature |\n|:-----------------|\n| `chat.getUserProfile()` |\n| `convo.getUserProfile()` |\n| `bot.getUserProfile(userId)` |\n\nThis method is not technically part of the \"Send\" API, but it's listed here because it's also shared between the `bot`, `chat` and `convo` instances.\n\nReturns a Promise that contains the user's [profile information](https://developers.facebook.com/docs/messenger-platform/user-profile).\n\n```javascript\nbot.hear('hello', (payload, chat) =\u003e {\n  chat.getUserProfile().then((user) =\u003e {\n    chat.say(`Hello, ${user.first_name}!`);\n  });\n});\n```\n\n---\n\n### Conversations\n\nConversations provide a convinient method to ask questions and handle the user's answer. They're useful when you want to set a flow of different questions/answers, like an onboarding process or when taking an order for example. Conversations also provide a method to save the information that you need from the user's answers, so the interaction is always in context.\n\nMessages sent by the user won't trigger a global `message`, `postback`, `attachment` or `quick_reply` event if there's an active conversation with that user. Answers must be managed by the conversation.\n\n#### `bot.conversation()`\n\n| Method signature |\n|:-----------------|\n| `chat.conversation(factory)` |\n| `bot.conversation(userId, factory)` |\n\nStarts a new conversation with the user.\n\nThe `factory` param must be a function that is executed immediately receiving the `convo` instance as it's only param:\n\n```\nbot.on('hello', (payload, chat) =\u003e {\n\tchat.conversation((convo) =\u003e {\n\t\t// convo is available here...\n\t\tconvo.ask( ... );\n\t});\n});\n```\n\n#### `convo.ask(question, answer, [ callbacks, options ])`\n\n| Param | Type | Default | Required |\n|:------|:-----|:--------|:---------|\n| `question` | string, object or function | | `Y` |\n| `answer` | function | | `Y` |\n| `callbacks` | array | | `N` |\n| `options` | object | | `N` |\n\nIf `question` is a string or an object, the `.say()` method will be invoked immediately with that string or object, if it's a function it will also be invoked immedately with the `convo` instance as its only param.\n\nThe `answer` param must be a function that receives the `payload`, `convo` and `data` params (similar to the callback function of the `.on()` or `.hear()` methods, except it receives the `convo` instance instead of the `chat` instance). The `answer` function will be called whenever the user replies to the `question` with a text message or quick reply.\n\nThe `callbacks` array can be used to listen to specific types of answers to the `question`. You can listen for `postback`, `quick_reply` and `attachment` events, or you can match a specific text `pattern`. See example bellow:\n\nThe `options` param is identical to the `options` param of the [`.say()`](#say) method.\n\n##### `convo.ask()` example:\n\n```javascript\nconst question = {\n\ttext: `What's your favorite color?`,\n\tquickReplies: ['Red', 'Green', 'Blue']\n};\n\nconst answer = (payload, convo) =\u003e {\n\tconst text = payload.message.text;\n\tconvo.say(`Oh, you like ${text}!`);\n};\n\nconst callbacks = [\n\t{\n\t\tevent: 'quick_reply',\n\t\tcallback: () =\u003e { /* User replied using a quick reply */ }\n\t},\n\t{\n\t\tevent: 'attachment',\n\t\tcallback: () =\u003e { /* User replied with an attachment */ }\n\t},\n\t{\n\t\tpattern: ['black', 'white'],\n\t\tcallback: () =\u003e { /* User said \"black\" or \"white\" */ }\n\t}\n];\n\nconst options = {\n\ttyping: true // Send a typing indicator before asking the question\n};\n\nconvo.ask(question, answer, callbacks, options);\n```\n\n#### `convo.set(property, value)`\n\n| Param | Type | Default | Required |\n|:------|:-----|:--------|:---------|\n| `property` | string | | `Y` |\n| `value` | mixed | | `Y` |\n\nSave a value in the conversation's context. This value will be available in all subsequent questions and answers that are part of this conversation, but the values are lost once the conversation ends.\n\n```javascript\nconvo.question(`What's your favorite color?`, (payload, convo) =\u003e {\n\tconst text = payload.message.text;\n\n\t// Save the user's answer in the conversation's context.\n\t// You can then call convo.get('favoriteColor') in a future question or answer to retrieve the value.\n\tconvo.set('favoriteColor', text);\n\tconvo.say(`Oh, you like ${text}!`);\n});\n```\n\n#### `convo.get(property)`\n\n| Param | Type | Default | Required |\n|:------|:-----|:--------|:---------|\n| `property` | string | | `Y` |\n\nRetrieve a value from the conversation's context.\n\n#### `convo.end()`\n\nEnds a conversation, giving control back to the `bot` instance. All `.on()` and `.hear()` listeners are now back in action. After you end a conversation the values that you saved using the `convo.set()` method are now lost.\n\nYou must call `convo.end()` after you no longer wish to interpret user's messages as `answer`s to one of your `questions`. If you don't, and a message is received with no `answer` callback listening, the conversation will be ended automatically.\n\n---\n\n### Modules\n\nModules are simple functions that you can use to organize your code in different files and folders.\n\n#### `.module(factory)`\n\nThe `factory` param is a function that gets called immediatly and receives the `bot` instance as its only parameter. For example:\n\n```javascript\n// help-module.js\nmodule.exports = (bot) =\u003e {\n\tbot.hear('help', (payload, chat) =\u003e {\n\t\t// Send Help Menu to the user...\n\t});\n};\n\n// index.js\nconst helpModule = require('./help-module');\nbot.module(helpModule);\n```\n\nTake a look at the `examples/module-example.js` file for a complete example.\n\n---\n\n### Messenger Profile API\n\n#### `.setGreetingText(text)`\n\n[Facebook Docs](https://developers.facebook.com/docs/messenger-platform/messenger-profile/greeting-text)\n\n| Param | Type | Default | Required |\n|:------|:-----|:--------|:---------|\n| `text` | string or array | | `Y` |\n\nSet a greeting text for new conversations. The Greeting Text is only rendered the first time the user interacts with a the Page on Messenger.\n\n**Localization support:** `text` can be a string containing the greeting text, or an array of objects to support multiple locales. For more info on the format of these objects, see [the documentation](https://developers.facebook.com/docs/messenger-platform/messenger-profile/greeting-text).\n\n#### `.setGetStartedButton(action)`\n\n[Facebook Docs](https://developers.facebook.com/docs/messenger-platform/messenger-profile/get-started-button)\n\n| Param | Type | Default | Required |\n|:------|:-----|:--------|:---------|\n| `action` | string or function | | `Y` |\n\nReact to a user starting a conversation with the bot by clicking the Get Started button. If `action` is a string, the Get Started button postback will be set to that string. If it's a function, that callback will be executed when a user clicks the Get Started button.\n\n#### `.deleteGetStartedButton()`\n\nRemoves the Get Started button call to action.\n\n#### `.setPersistentMenu(buttons, [ disableInput ])`\n\n[Facebook Docs](https://developers.facebook.com/docs/messenger-platform/messenger-profile/persistent-menu)\n\n| Param | Type | Default | Required |\n|:------|:-----|:--------|:---------|\n| `buttons` | array of strings or objects | | `Y` |\n| `disableInput ` | boolean | `false` | `N` |\n\nCreates a Persistent Menu that is available at any time during the conversation. The `buttons` param can be an array of strings, button objects, or locale objects.\n\nIf `disableInput` is set to `true`, it will disable user input in the menu. The user will only be able to interact with the bot via the menu, postbacks, buttons and webviews.\n\n**Localization support:** if `buttons` is an array of objects containing a `locale` attribute, it will be used as-is, expecting it to be an array of localized menues. For more info on the format of these objects, see [the documentation](https://developers.facebook.com/docs/messenger-platform/messenger-profile/persistent-menu).\n\n#### `.deletePersistentMenu()`\n\nRemoves the Persistent Menu.\n\n----------------------\n\n### Bypassing Express\n\nYou may only want to use bootbot for the Facebook related config and the simple to use Send API features but handle routing from somewhere else. Or there may be times where you want to send a message out of band, like if you get a postback callback and need to end a conversation flow immediately.\n\nOr maybe you don't want to use express but a different HTTP server.\n\n#### `.handleFacebookData(data)`\n\nUse this to send a message from a parsed webhook message directly to your bot.\n\n```js\nconst linuxNewsBot   = new BootBot({argz});\nconst appleNewsBot   = new BootBot({argz});\nconst windowsNewsBot = new BootBot({argz});\n\nmyNonExpressRouter.post(\"/mywebhook\", (data) =\u003e {\n\tconst messages = data.entry[0].messaging;\n\tmessages.forEach(message =\u003e {\n\t\tswitch(data.entry.id) {\n\t\t\tcase LINUX_BOT_PAGE_ID:\n\t\t\t\tlinuxNewsBot.handleFacebookData(message);\n\t\t\t\tbreak;\n\t\t\tcase APPLE_BOT_PAGE_ID:\n\t\t\t\tappleNewsBot.handleFacebookData(message);\n\t\t\t\tbreak;\n\t\t\t// ...\n\t\t};\n\t});\n});\n```\n\n## Examples\n\nCheck the `examples` directory to see more demos of:\n\n- An echo bot\n- A bot that searches for random gifs\n- An example conversation with questions and answers\n- How to organize your code using modules\n- How to use the Messenger Profile API to set a Persistent Menu or a Get Started CTA\n- How to get the user's profile information\n\nTo run the examples, make sure to complete the `examples/config/default.json` file with your bot's tokens, and then cd into the `examples` folder and run the desired example with node. For example:\n\n```\n$ cd examples\n$ node echo-example.js\n```\n\n## Credits\n\nMade with :beer: by Maxi Ferreira - [@Charca](https://twitter.com/charca)\n\n## License\n\nMIT\n\n[Features]:#features\n[Usage]:#usage\n[Video Example]:#video-example\n[Getting Started]:#getting-started\n[Documentation]:#documentation\n[Examples]:#examples\n[Credits]:#credits\n[License]:#license\n","funding_links":[],"categories":["JavaScript","Development"],"sub_categories":["Bot Development"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCharca%2Fbootbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FCharca%2Fbootbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCharca%2Fbootbot/lists"}