{"id":15034145,"url":"https://github.com/remixz/messenger-bot","last_synced_at":"2025-05-15T16:05:28.519Z","repository":{"id":57114205,"uuid":"56101708","full_name":"remixz/messenger-bot","owner":"remixz","description":"A Node client for the Facebook Messenger Platform","archived":false,"fork":false,"pushed_at":"2020-05-11T17:18:36.000Z","size":158,"stargazers_count":1091,"open_issues_count":17,"forks_count":214,"subscribers_count":40,"default_branch":"master","last_synced_at":"2025-05-12T16:08:13.908Z","etag":null,"topics":["bot","facebook","facebook-messenger-platform"],"latest_commit_sha":null,"homepage":null,"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/remixz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-04-12T22:17:22.000Z","updated_at":"2025-05-10T13:11:50.000Z","dependencies_parsed_at":"2022-08-22T10:40:21.388Z","dependency_job_id":null,"html_url":"https://github.com/remixz/messenger-bot","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/remixz%2Fmessenger-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/remixz%2Fmessenger-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/remixz%2Fmessenger-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/remixz%2Fmessenger-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/remixz","download_url":"https://codeload.github.com/remixz/messenger-bot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254374417,"owners_count":22060610,"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","facebook","facebook-messenger-platform"],"created_at":"2024-09-24T20:24:04.528Z","updated_at":"2025-05-15T16:05:28.465Z","avatar_url":"https://github.com/remixz.png","language":"JavaScript","funding_links":[],"categories":["Development"],"sub_categories":["Bot Development"],"readme":"# messenger-bot\n[![Build Status](https://travis-ci.org/remixz/messenger-bot.svg?branch=master)](https://travis-ci.org/remixz/messenger-bot)\n[![Coverage Status](https://coveralls.io/repos/github/remixz/messenger-bot/badge.svg?branch=master)](https://coveralls.io/github/remixz/messenger-bot?branch=master)\n[![npm version](https://img.shields.io/npm/v/messenger-bot.svg)](https://www.npmjs.com/package/messenger-bot)\n[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](http://standardjs.com/)\n\n\nA Node client for the [Facebook Messenger Platform](https://developers.facebook.com/docs/messenger-platform).\n\nRequires Node \u003e=4.0.0.\n\n## Installation\n\n```bash\nnpm install messenger-bot\n```\n\n## Example\n\nSee more examples in [the examples folder.](https://github.com/remixz/messenger-bot/tree/master/example)\n\nRun this example in the cloud: [![Nitrous Quickstart](https://nitrous-image-icons.s3.amazonaws.com/quickstart.svg)](https://www.nitrous.io/quickstart)\n* Setup `PAGE_TOKEN`, `VERIFY_TOKEN`, `APP_SECRET` and start the example by `Run \u003e Start Messenger Echo Bot`.\n* Your Webhook URL is available at `Preview \u003e 3000` in the IDE.\n\n```js\nconst http = require('http')\nconst Bot = require('messenger-bot')\n\nlet bot = new Bot({\n  token: 'PAGE_TOKEN',\n  verify: 'VERIFY_TOKEN',\n  app_secret: 'APP_SECRET'\n})\n\nbot.on('error', (err) =\u003e {\n  console.log(err.message)\n})\n\nbot.on('message', (payload, reply) =\u003e {\n  let text = payload.message.text\n\n  bot.getProfile(payload.sender.id, (err, profile) =\u003e {\n    if (err) throw err\n\n    reply({ text }, (err) =\u003e {\n      if (err) throw err\n\n      console.log(`Echoed back to ${profile.first_name} ${profile.last_name}: ${text}`)\n    })\n  })\n})\n\nhttp.createServer(bot.middleware()).listen(3000)\nconsole.log('Echo bot server running at port 3000.')\n```\n\n## Usage\n\n### Functions\n\n#### `let bot = new Bot(opts)`\n\nReturns a new Bot instance.\n\n`opts` - Object\n\n* `token` - String: Your Page Access Token, found in your App settings. Required.\n* `verify` - String: A verification token for the first-time setup of your webhook. Optional, but will be required by Facebook when you first set up your webhook.\n* `app_secret` - String: Your App Secret token used for message integrity check. If specified, every POST request  will be tested for spoofing. Optional.\n\n#### `bot.middleware()`\n\nThe main middleware for your bot's webhook. Returns a function. Usage:\n\n```js\nconst http = require('http')\nconst Bot = require('messenger-bot')\n\nlet bot = new Bot({\n  token: 'PAGE_TOKEN',\n  verify: 'VERIFY_TOKEN'\n})\n\nhttp.createServer(bot.middleware()).listen(3000)\n```\n\nAs well, it mounts `/_status`, which will return `{\"status\": \"ok\"}` if the middleware is running. If `verify` is specified in the bot options, it will mount a handler for `GET` requests that verifies the webhook.\n\n#### `bot.sendMessage(recipient, payload, [callback], [messagingType], [tag])`\n\nSends a message with the `payload` to the target `recipient`, and calls the callback if any. Returns a promise. See [Send API](https://developers.facebook.com/docs/messenger-platform/send-api-reference#request).\n\n* `recipient` - Number: The Facebook ID of the intended recipient.\n* `payload` - Object: The message payload. Should follow the [Send API format](https://developers.facebook.com/docs/messenger-platform/send-api-reference).\n* `callback` - (Optional) Function: Called with `(err, info)` once the request has completed. `err` contains an error, if any, and `info` contains the response from Facebook, usually with the new message's ID.\n* `messagingType` - (Optional) String: The message type. [Supported Messaging Type](https://developers.facebook.com/docs/messenger-platform/send-messages#messaging_types).\n* `tag` - (Optional) String: The tag's message. [Supported Tags](https://developers.facebook.com/docs/messenger-platform/send-messages/message-tags#supported_tags).\n\n#### `bot.getAttachmentUploadId(url, is_reusable, type, [callback])`\n\nSends the media to the Attachment Upload API and calls the callback if the upload is successful, including the `attachment_id`. See [Attachment Upload API](https://developers.facebook.com/docs/messenger-platform/reference/attachment-upload-api).\n\n* `url` - String: Link where can be fetched the media.\n* `is_reusable` - Boolean: Defined if the saved asset will be sendable to other message recipients.\n* `type` - String: The type of media. Can be one of: `image`, `video`, `audio`, `file`.\n* `callback` - (Optional) Function: Called with `(err, info)` once the request has completed. `err` contains an error, if any, and `info` contains the response from Facebook, usually with the media's ID.\n\n#### `bot.sendSenderAction(recipient, senderAction, [callback])`\n\nSends the sender action `senderAction` to the target `recipient`, and calls the callback if any. Returns a promise.\n\n* `recipient` - Number: The Facebook ID of the intended recipient.\n* `senderAction` - String: The sender action to execute. Can be one of: `typing_on`, 'typing_off', 'mark_seen'. See the [Sender Actions API reference](https://developers.facebook.com/docs/messenger-platform/send-api-reference/sender-actions) for more information.\n* `callback` - (Optional) Function: Called with `(err, info)` once the request has completed. `err` contains an error, if any, and `info` contains the response from Facebook, usually with the new message's ID.\n\n#### `bot.unlinkAccount(psid, [callback])`\n\nUnlinks the user with the corresponding `psid`, and calls the callback if any. Returns a promise. See [Account Unlink Endpoint].(https://developers.facebook.com/docs/messenger-platform/identity/account-linking?locale=en_US#unlink)\n\n* `psid` - Number: The Facebook ID of the user who has to be logged out.\n* `callback` - (Optional) Function: Called with `(err, info)` once the request has completed. `err` contains an error, if any, and `info` contains the response from Facebook.\n\n#### `bot.setGetStartedButton(payload, [callback])`\n#### `bot.setPersistentMenu(payload, [callback])`\n\nSets settings for the Get Started Button / Persistent Menu. See the [Messenger Profile Reference](https://developers.facebook.com/docs/messenger-platform/messenger-profile) for what to put in the `payload`.\n\n#### `bot.removeGetStartedButton([callback])`\n#### `bot.removePersistentMenu([callback])`\n\nRemoves the Get Started Button / Persistent Menu.\n\n#### `bot.getProfile(target, [callback])`\n\nReturns a promise of the profile information of the `target`, also called in the `callback` if any. See [User Profile API](https://developers.facebook.com/docs/messenger-platform/send-api-reference#user_profile_request).\n\n* `target` - Number: The Facebook ID of the intended target.\n* `callback` - (Optional) Function: Called with `(err, profile)` once the request has completed. `err` contains an error, if any, and `info` contains the response from Facebook, in this format:\n\n```json\n{\n  \"first_name\": \"Zach\",\n  \"last_name\": \"Bruggeman\",\n  \"profile_pic\": \"\u003curl to profile picture\u003e\",\n  \"locale\": \"en\",\n  \"timezone\": \"PST\",\n  \"gender\": \"M\"\n}\n```\n\n#### `bot._handleMessage(payload)`\n\nThe underlying method used by `bot.middleware()` to parse the message payload, and fire the appropriate events. Use this if you've already implemented your own middleware or route handlers to receive the webhook request, and just want to fire the events on the bot instance. See [the echo bot implemented in Express](https://github.com/remixz/messenger-bot/blob/master/example/echo-express.js) for an example.\n\n* `payload` - Object: The payload sent by Facebook to the webhook.\n\n#### `bot._verify(req, res)`\n\nThe underlying method used by `bot.middleware()` for the initial webhook verification. Use this if you've already implemented your own middleware or route handlers, and wish to handle the request without implementing `bot.middleware()`. See [the echo bot implemented in Express](https://github.com/remixz/messenger-bot/blob/master/example/echo-express.js) for an example.\n\n* `req` - Request: The `http` request object.\n* `res` - Response: The `http` response object.\n\n### Events\n\n#### bot.on('message', (payload, reply, actions))\n\nTriggered when a message is sent to the bot.\n\n* `payload` - Object: An object containing the message event's payload from Facebook. See [Facebook's documentation](https://developers.facebook.com/docs/messenger-platform/webhook-reference#received_message) for the format.\n* `reply` - Function: A convenience function that calls `bot.sendMessage`, with the recipient automatically set to the message sender's Facebook ID. Example usage:\n\n```js\nbot.on('message', (payload, reply, actions) =\u003e {\n  reply({ text: 'hey!'}, (err, info) =\u003e {})\n})\n```\n\n* `actions` - Object: An object with two functions: `setTyping(status: Boolean)`, and `markRead()`.\n\n#### bot.on('postback', (payload, reply, actions))\n\nTriggered when a postback is triggered by the sender in Messenger.\n\n* `payload` - Object: An object containing the postback event's payload from Facebook. See [Facebook's documentation](https://developers.facebook.com/docs/messenger-platform/webhook-reference#postback) for the format.\n* `reply` - Function: A convenience function that calls `bot.sendMessage`, with the recipient automatically set to the message sender's Facebook ID. Example usage:\n* `actions` - Object: An object with two functions: `setTyping(status: Boolean)`, and `markRead()`.\n\n```js\nbot.on('postback', (payload, reply, actions) =\u003e {\n  reply({ text: 'hey!'}, (err, info) =\u003e {})\n})\n```\n\n#### bot.on('delivery', (payload, reply, actions))\n\nTriggered when a message has been successfully delivered.\n\n* `payload` - Object: An object containing the delivery event's payload from Facebook. See [Facebook's documentation](https://developers.facebook.com/docs/messenger-platform/webhook-reference#message_delivery) for the format.\n* `reply` - Function: A convenience function that calls `bot.sendMessage`, with the recipient automatically set to the message sender's Facebook ID. Example usage:\n* `actions` - Object: An object with two functions: `setTyping(status: Boolean)`, and `markRead()`.\n\n```js\nbot.on('delivery', (payload, reply, actions) =\u003e {\n  reply({ text: 'hey!'}, (err, info) =\u003e {})\n})\n```\n\n#### bot.on('authentication', (payload, reply, actions))\n\nTriggered when a user authenticates with the \"Send to Messenger\" plugin.\n\n* `payload` - Object: An object containing the authentication event's payload from Facebook. See [Facebook's documentation](https://developers.facebook.com/docs/messenger-platform/webhook-reference#auth) for the format.\n* `reply` - Function: A convenience function that calls `bot.sendMessage`, with the recipient automatically set to the message sender's Facebook ID. Example usage:\n* `actions` - Object: An object with two functions: `setTyping(status: Boolean)`, and `markRead()`.\n\n```js\nbot.on('authentication', (payload, reply, actions) =\u003e {\n  reply({ text: 'thanks!'}, (err, info) =\u003e {})\n})\n```\n\n#### bot.on('referral', (payload, reply, actions))\n\nTriggered when an m.me link is used with a referral param and only in a case this user already has a thread with this bot (for new threads see 'postback' event)\n\n* `payload` - Object: An object containing the authentication event's payload from Facebook. See [Facebook's documentation](https://developers.facebook.com/docs/messenger-platform/webhook-reference/referral) for the format.\n* `reply` - Function: A convenience function that calls `bot.sendMessage`, with the recipient automatically set to the message sender's Facebook ID. Example usage:\n* `actions` - Object: An object with two functions: `setTyping(status: Boolean)`, and `markRead()`.\n\n```js\nbot.on('referral', (payload, reply, actions) =\u003e {\n  reply({ text: 'welcome!'}, (err, info) =\u003e {})\n})\n```\n\n#### bot.on('accountLinked', (payload, reply, actions))\n\nTriggered when an account is linked with the [Account Linking Process](https://developers.facebook.com/docs/messenger-platform/identity/account-linking?locale=en_US#linking_process).\n\n* `payload` - Object: An object containing the linking account event's payload from Facebook. See [Facebook's documentation](https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/messaging_account_linking) for the format.\n* `reply` - Function: A convenience function that calls `bot.sendMessage`, with the recipient automatically set to the message sender's Facebook ID. Example usage:\n* `actions` - Object: An object with two functions: `setTyping(status: Boolean)`, and `markRead()`.\n\n```js\nbot.on('accountLinked', (payload, reply, actions) =\u003e {\n  reply({ text: 'Logged in!'}, (err, info) =\u003e {})\n})\n```\n\n#### bot.on('accountUnlinked', (payload, reply, actions))\n\nTriggered when an account is unlinked with the [Account Unlink Endpoint](https://developers.facebook.com/docs/messenger-platform/identity/account-linking?locale=en_US#unlink) or with an [Log Out Button](https://developers.facebook.com/docs/messenger-platform/reference/buttons/logout).\n\n* `payload` - Object: An object containing the unlinking account event's payload from Facebook. See [Facebook's documentation](https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/messaging_account_linking) for the format.\n* `reply` - Function: A convenience function that calls `bot.sendMessage`, with the recipient automatically set to the message sender's Facebook ID. Example usage:\n* `actions` - Object: An object with two functions: `setTyping(status: Boolean)`, and `markRead()`.\n\n```js\nbot.on('accountLinked', (payload, reply, actions) =\u003e {\n  reply({ text: 'Logged out!'}, (err, info) =\u003e {})\n})\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fremixz%2Fmessenger-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fremixz%2Fmessenger-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fremixz%2Fmessenger-bot/lists"}