{"id":22130931,"url":"https://github.com/kahwee/ranka","last_synced_at":"2025-07-25T18:32:50.286Z","repository":{"id":13299429,"uuid":"74004069","full_name":"kahwee/ranka","owner":"kahwee","description":"Facebook Messaging bot with greater expressivity","archived":false,"fork":false,"pushed_at":"2022-04-24T23:01:24.000Z","size":1443,"stargazers_count":23,"open_issues_count":17,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-11-15T23:41:45.527Z","etag":null,"topics":["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":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kahwee.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}},"created_at":"2016-11-17T08:02:02.000Z","updated_at":"2022-08-20T10:56:49.000Z","dependencies_parsed_at":"2022-08-07T07:15:12.250Z","dependency_job_id":null,"html_url":"https://github.com/kahwee/ranka","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kahwee%2Franka","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kahwee%2Franka/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kahwee%2Franka/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kahwee%2Franka/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kahwee","download_url":"https://codeload.github.com/kahwee/ranka/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227609763,"owners_count":17793264,"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":["facebook","messenger"],"created_at":"2024-12-01T18:27:26.434Z","updated_at":"2025-07-25T18:32:50.276Z","avatar_url":"https://github.com/kahwee.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ranka\n\n\u003e **IMPORTANT: This project is no longer supported and has been archived. The Facebook Messenger API has undergone significant changes since this library was created, and it may not work with current API versions.**\n\nFacebook Messaging bot with greater expressivity to be used in conjunction with Express.\n\n![Demo](https://github.com/kahwee/ranka/raw/master/demo.gif \"Demo\")\n\n* [Setting up](#setting-up)\n* [Request Object](#request-object)\n* [Response Object](#response-object)\n\n## Setting up\n\nFirst, you will need to instantiate Ranka together with Express\n\n```js\nconst express = require('express')\nconst app = express()\nconst Ranka = require('ranka')\nconst ranka = new Ranka({\n  serverURL: '',\n  validationToken: '',\n  pageAccessToken: ''\n})\n```\n\nThen, use your webhook this way:\n\n```js\napp.use('/webhook', Ranka.router({\n  ranka: ranka\n}))\n\nranka.on('message', (req, res) =\u003e {\n  res\n    .sendText('mm...')\n    .typing()\n    .wait(3000)\n    .sendText(`Did you say \"${req.body.message.text}\"?`)\n    .sendImage('http://i.giphy.com/FdQj4yMGloVMI.gif')\n    .exec()\n})\n```\n\nBind your Express server port if you haven't already.\n\n```js\napp.listen(3000, function () {\n  console.log('Example app listening on port 3000!')\n})\n```\n\n## Request Object\n\n### Request Properties\n\nEvery [Facebook callback](https://developers.facebook.com/docs/messenger-platform/webhook-reference/message) is supported. This includes:\n\n* `sender`\n* `recipient`\n* `timestamp`\n* `message`\n\nFor example, when Facebook sends back the following:\n\n```json\n{\n  \"sender\":{\n    \"id\":\"USER_ID\"\n  },\n  \"recipient\":{\n    \"id\":\"PAGE_ID\"\n  },\n  \"timestamp\":1458692752478,\n  \"message\":{\n    \"mid\":\"mid.1457764197618:41d102a3e1ae206a38\",\n    \"seq\":73,\n    \"text\":\"hello, world!\",\n    \"quick_reply\": {\n      \"payload\": \"DEVELOPER_DEFINED_PAYLOAD\"\n    }\n  }\n}\n```\n\n`console.log(req.message)` returns you with:\n\n```json\n{\n  \"mid\":\"mid.1457764197618:41d102a3e1ae206a38\",\n  \"seq\":73,\n  \"text\":\"hello, world!\",\n  \"quick_reply\": {\n    \"payload\": \"DEVELOPER_DEFINED_PAYLOAD\"\n  }\n}\n```\n\n### Request Methods\n\n#### isThumbsUp()\n\nReturns true if it is Facebook thumbs up.\n\n```js\nreq.isThumbsUp()\n```\n\n#### hasAttachments()\n\nReturns True, if there are attachments\n\n#### getAttachmentsByType(type)\n\nReturns an array of all attachments with specified type.\n\nIf no attachments of type is found, return an empty array.\n\n```js\nreq.getAttachmentsByType('location')\n```\n\n## Response Object\n\n### Response chainable methods\n\nThe methods are chainable, you can use multiple methods and run `.exec()` at the end.\n\n#### senderAction(value)\n\nSet typing indicators or send read receipts using the Send API, to let users know you are processing their request.\n\n```js\nres\n  .senderAction('mark_seen')\n  .exec()\n```\n\n#### typing(isTyping)\n\n`isTyping` is defaulted to `true`.\n\nExample:\n\n```js\nres\n  .typing()\n  .wait(1000)\n  .sendText('Done!')\n  .exec()\n```\n\n#### send(message)\n\nThis is equivalent to sending this payload to Facebook Messenger API where `message` is the passed in as an object.\n\n```json\n{\n  \"recipient\": {\n    \"id\": \"AUTO_FILLED_USER_ID\"\n  },\n  \"message\": message\n}\n```\n\nIn this case, we can send a basic text:\n\n```js\nres\n  .send({ text: 'Hello there!' })\n  .exec()\n```\n\nCorrespondingly, `ranka` generates the data to send back to Facebook:\n\n```json\n{\n  \"recipient\": {\n    \"id\": \"AUTO_FILLED_USER_ID\"\n  },\n  \"message\": { \n    \"text\": \"Hello there!\" \n  }\n}\n```\n\nThe remaining commands are convenient helpers that wraps the `send()` method.\n\n#### sendText(text)\n\nSends a text as a reply to the sender.\n\n```js\nres\n  .sendText('Hello!')\n  .exec()\n```\n\n#### sendQuickReplies(text, quick_replies)\n\nYou can send some quick replies:\n\n```js\nres\n  .sendQuickReplies('Please share your location:', [\n    {\n      content_type: 'location'\n    }\n  ])\n  .exec()\n```\n\n#### sendAudio(url)\n\nYou can share a sound URL using the Send API.\n\nSee more in [Facebook Messenger documentation](https://developers.facebook.com/docs/messenger-platform/send-api-reference/audio-attachment).\n\n#### sendVideo(url)\n\nYou can share a video URL using the Send API.\n\nSee more in [Facebook Messenger documentation](https://developers.facebook.com/docs/messenger-platform/send-api-reference/video-attachment).\n\n#### sendTemplate(payload)\n\nYou can send a message template and provide a `payload` object:\n\n```\nreq\n  .sendTemplate({\n    \"template_type\":\"button\",\n    \"text\":\"What do you want to do next?\",\n    \"buttons\":[\n      {\n        \"type\":\"web_url\",\n        \"url\":\"https://petersapparel.parseapp.com\",\n        \"title\":\"Show Website\"\n      },\n      {\n        \"type\":\"postback\",\n        \"title\":\"Start Chatting\",\n        \"payload\":\"USER_DEFINED_PAYLOAD\"\n      }\n    ]\n  })\n  .exec()\n```\n\nUsing the above, you can send [Button Template](https://developers.facebook.com/docs/messenger-platform/send-api-reference/button-template), [Generic Template](https://developers.facebook.com/docs/messenger-platform/send-api-reference/generic-template), [List Template](https://developers.facebook.com/docs/messenger-platform/send-api-reference/list-template), [Reciept Template](https://developers.facebook.com/docs/messenger-platform/send-api-reference/receipt-template), [Airline Boarding Pass Template](https://developers.facebook.com/docs/messenger-platform/send-api-reference/airline-boardingpass-template) and more.\n\n## License\n\nApache 2.0 License\n\n## Project Status\n\nThis project is archived and no longer maintained. It was developed for an older version of the Facebook Messenger API and is not compatible with recent API changes. Please consider using a more up-to-date Facebook Messenger bot framework for new projects.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkahwee%2Franka","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkahwee%2Franka","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkahwee%2Franka/lists"}