{"id":23658888,"url":"https://github.com/mustafaturan/messenger_bot","last_synced_at":"2025-09-01T12:31:40.402Z","repository":{"id":48306448,"uuid":"129685261","full_name":"mustafaturan/messenger_bot","owner":"mustafaturan","description":"Unofficial Facebook Messenger Platform *chatbot client* and *webhook handler*","archived":false,"fork":false,"pushed_at":"2021-08-02T13:15:17.000Z","size":194,"stargazers_count":17,"open_issues_count":11,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-15T20:18:33.042Z","etag":null,"topics":["chatbot","chatbot-framework","domain-driven-design","elixir","elixir-library","eventsourcing","messenger-bot","messenger-platform"],"latest_commit_sha":null,"homepage":null,"language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mustafaturan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-04-16T04:36:07.000Z","updated_at":"2023-12-25T13:51:42.000Z","dependencies_parsed_at":"2022-08-26T04:01:45.225Z","dependency_job_id":null,"html_url":"https://github.com/mustafaturan/messenger_bot","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/mustafaturan/messenger_bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mustafaturan%2Fmessenger_bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mustafaturan%2Fmessenger_bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mustafaturan%2Fmessenger_bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mustafaturan%2Fmessenger_bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mustafaturan","download_url":"https://codeload.github.com/mustafaturan/messenger_bot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mustafaturan%2Fmessenger_bot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273122203,"owners_count":25049540,"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-09-01T02:00:09.058Z","response_time":120,"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":["chatbot","chatbot-framework","domain-driven-design","elixir","elixir-library","eventsourcing","messenger-bot","messenger-platform"],"created_at":"2024-12-29T01:03:05.679Z","updated_at":"2025-09-01T12:31:40.029Z","avatar_url":"https://github.com/mustafaturan.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MessengerBot\n\n[![Build Status](https://travis-ci.org/mustafaturan/messenger_bot.svg?branch=master)](https://travis-ci.org/mustafaturan/messenger_bot)\n[![Hex.pm](https://img.shields.io/hexpm/v/messenger_bot.svg)](http://hex.pm/packages/messenger_bot)\n[![Hex.pm](https://img.shields.io/hexpm/dt/messenger_bot.svg)](https://hex.pm/packages/messenger_bot)\n[![Hex.pm](https://img.shields.io/hexpm/dw/messenger_bot.svg)](https://hex.pm/packages/messenger_bot)\n[![codecov](https://codecov.io/gh/musafaturan/messenger_bot/branch/master/graph/badge.svg)](https://codecov.io/gh/mustafaturan/messenger_bot)\n[![Inline docs](http://inch-ci.org/github/mustafaturan/messenger_bot.svg)](http://inch-ci.org/github/mustafaturan/messenger_bot)\n\nUnofficial Facebook Messenger Platform *chatbot client* and *webhook handler*\n\nMessengerBot covers majority of the functions to make calls to Facebook Messenger Platform endpoints.\n\nMessengerBot library is designed for processing webhook events coming from Facebook with an event driven approach. It allows any number of subscribers to process same data without blocking.\n\n## Installation\n\nThe package can be installed by adding `messenger_bot` to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [{:messenger_bot, \"~\u003e 1.3.0\"}]\nend\n```\n\n## Configuration\n\n### Facebook Messenger App and Page configurations\n\n`App` and `Page` configurations can be done via `config.exs` and `MessengerBot.Config` module. Basic idea is to store apps and pages are type of `MessengerBot.Model.{App, Page}` types.\n\nIf you are using the app for a single page, `config.exs` seems to be right place but if you need to load app info from an external source, then use module functions to save your apps.\n\n*Note:* `App` and `Page` keys must be atom() type like in the examples. For `config.exs` you can add apps and pages like below:\n\n```elixir\nconfig :messenger_bot,\n  fb_api_version: \"v2.12\",\n  pages: %{\n    \"1881\" =\u003e %{\n      \"1234\" =\u003e %{\n        id: \"1234\",\n        name: \"Demo Facebook Messenger Bot\",\n        access_token: \"accesstokenforpage\"\n      }\n    }\n  },\n  apps: %{\n    \"1881\" =\u003e %{\n      id: \"1881\",\n      secret: \"SECRET\",\n      setup_token: \"Setup Token\",\n      access_token: \"ATOKEN123\"\n    }\n  }\n```\n\nAny time after loading `messenger_bot`, you can add more pages for an app.\n\n```elixir\npages = %{\n  \"1234\" =\u003e %{\n    id: \"1234\",\n    name: \"Demo Facebook Messenger Bot\",\n    token: \"accesstokenforpage\"\n  },\n  \"1298\" =\u003e %{\n    id: \"1298\",\n    name: \"Demo Facebook Messenger Bot 1298\",\n    token: \"accesstokenforpagefor1298\"\n  }\n}\n\n# Update configurations\nMessengerBot.Config.save_pages(app_id, pages)\n```\n\nDetails: https://hexdocs.pm/messenger_bot/1.0.0-beta10/MessengerBot.Config.html#save_pages/2\n\nAny time after loading `messenger_bot`, you can save apps too.\n\n```elixir\napps = %{\n  \"1881\" =\u003e %{\n    id: \"1881\",\n    secret: \"SECRET\",\n    setup_token: \"Setup Token\",\n    access_token: \"ATOKEN123\"\n  }\n}\n\n# Update configurations\nMessengerBot.Config.save_apps(apps)\n```\n\nDetails: https://hexdocs.pm/messenger_bot/1.0.0-beta10/MessengerBot.Config.html#save_apps/1\n\n### Facebook App setup configuration\n\nAdd webhook endpoints to your router:\n\n```elixir\nforward \"/some-path-for-messenger_bot\", to: MessengerBot.Web.Router\n\n# The code above will add following routes\n# -\u003e GET   /some-path-for-messenger_bot/:app_id (Possible HTTP status codes: 200, 401, 404, 422, 500)\n# -\u003e POST  /some-path-for-messenger_bot/:app_id (Possible HTTP status codes: 200, 401, 404, 422, 500)\n# -\u003e MATCH /some-path-for-messenger_bot/:any (Possible HTTP status code: 404)\n```\n\n### EventBus Configuration\n\nUpdate your `config.exs` to add `messenger_bot` event topics and id generator for `event_bus`:\n\n```elixir\nconfig :event_bus,\n  ttl: 900_000_000,\n  time_unit: :microsecond,\n  id_generator: MessengerBot.Util.String,\n  topics: [\n    ##########################################################################\n    # Webserver Topics\n    ##########################################################################\n    :mb_webserv_succeeded,\n    :mb_webserv_payload_failed,\n    :mb_webserv_erred,\n    ##########################################################################\n    # Webhook Topics\n    ##########################################################################\n    :mb_delivery_received,\n    :mb_read_received,\n    :mb_message_echo_received,\n    :mb_message_attachments_received,\n    :mb_message_quick_reply_received,\n    :mb_message_received,\n    :mb_optin_received,\n    :mb_postback_received,\n    :mb_referral_received,\n    :mb_game_play_received,\n    :mb_payment_received,\n    :mb_checkout_update_received,\n    :mb_pre_checkout_received,\n    :mb_account_linking_received,\n    :mb_policy_enforcement_received,\n    :mb_app_roles_received,\n    :mb_standby_received,\n    :mb_pass_thread_control_received,\n    :mb_take_thread_control_received,\n    :mb_request_thread_control_received,\n    :mb_na_received,\n    :mb_app_setup_succeeded,\n    :mb_app_setup_failed,\n    ##########################################################################\n    # Client Request Topics\n    ##########################################################################\n    :mb_attachment_upload_succeeded,\n    :mb_create_message_creatives_succeeded,\n    :mb_broadcast_message_succeeded,\n    :mb_list_custom_labels_succeeded,\n    :mb_fetch_custom_label_succeeded,\n    :mb_delete_custom_label_succeeded,\n    :mb_label_user_succeeded,\n    :mb_unlabel_user_succeeded,\n    :mb_list_custom_labels_of_user_succeeded,\n    :mb_pass_thread_control_succeeded,\n    :mb_take_thread_control_succeeded,\n    :mb_request_thread_control_succeeded,\n    :mb_fetch_secondary_receivers_succeeded,\n    :mb_id_matching_succeeded,\n    :mb_create_messenger_code_succeeded,\n    :mb_fetch_messaging_feature_review_succeeded,\n    :mb_fetch_insights_succeeded,\n    :mb_set_messenger_profile_succeeded,\n    :mb_reset_messenger_profile_succeeded,\n    :mb_fetch_messenger_profile_succeeded,\n    :mb_send_message_succeeded,\n    :mb_unlink_account_succeeded,\n    :mb_fetch_user_profile_succeeded,\n    :mb_set_nlp_configs_succeeded,\n    :mb_subscribe_to_page_webhooks_succeeded,\n    :mb_unsubscribe_to_page_webhooks_succeeded,\n    ##########################################################################\n    :mb_attachment_upload_failed,\n    :mb_create_message_creatives_failed,\n    :mb_broadcast_message_failed,\n    :mb_list_custom_labels_failed,\n    :mb_fetch_custom_label_failed,\n    :mb_delete_custom_label_failed,\n    :mb_label_user_failed,\n    :mb_unlabel_user_failed,\n    :mb_list_custom_labels_of_user_failed,\n    :mb_pass_thread_control_failed,\n    :mb_take_thread_control_failed,\n    :mb_request_thread_control_failed,\n    :mb_fetch_secondary_receivers_failed,\n    :mb_id_matching_failed,\n    :mb_create_messenger_code_failed,\n    :mb_fetch_messaging_feature_review_failed,\n    :mb_fetch_insights_failed,\n    :mb_set_messenger_profile_failed,\n    :mb_reset_messenger_profile_failed,\n    :mb_fetch_messenger_profile_failed,\n    :mb_send_message_failed,\n    :mb_unlink_account_failed,\n    :mb_fetch_user_profile_failed,\n    :mb_set_nlp_configs_failed,\n    :mb_subscribe_to_page_webhooks_failed,\n    :mb_unsubscribe_to_page_webhooks_failed,\n    ##########################################################################\n    :mb_attachment_upload_erred,\n    :mb_create_message_creatives_erred,\n    :mb_broadcast_message_erred,\n    :mb_list_custom_labels_erred,\n    :mb_fetch_custom_label_erred,\n    :mb_delete_custom_label_erred,\n    :mb_label_user_erred,\n    :mb_unlabel_user_erred,\n    :mb_list_custom_labels_of_user_erred,\n    :mb_pass_thread_control_erred,\n    :mb_take_thread_control_erred,\n    :mb_request_thread_control_erred,\n    :mb_fetch_secondary_receivers_erred,\n    :mb_id_matching_erred,\n    :mb_create_messenger_code_erred,\n    :mb_fetch_messaging_feature_review_erred,\n    :mb_fetch_insights_erred,\n    :mb_set_messenger_profile_erred,\n    :mb_reset_messenger_profile_erred,\n    :mb_fetch_messenger_profile_erred,\n    :mb_send_message_erred,\n    :mb_unlink_account_erred,\n    :mb_fetch_user_profile_erred,\n    :mb_set_nlp_configs_erred,\n    :mb_subscribe_to_page_webhooks_erred,\n    :mb_unsubscribe_to_page_webhooks_erred]\n```\n\n## Usage\n\n### Webhook handling\n\nMessengerBot library handles allows you to handle all webhooks with subscription to the events.\n\n#### How to subscribe to event topics?\n\n`messenger_bot` package uses [event_bus library](https://github.com/otobus/event_bus) to sent/process Messenger events. Please refer to `event_bus` docs to learn more. You can subscribe registered events. To subscribe all events you can use `EventBus.subscribe({listener, [\".*\"]})` and to subscribe only specific topics then `EventBus.subscribe({listener, [\"mb_message_received$\", \"mb_postback_received$\"]})`. Please refer to `event_bus` library to documentation and Github wiki pages for more information.\n\nHere is a sample echo bot consumer:\n\n```elixir\nEventBus.subscribe({MessengerBot.Consumer.Echo, [\"mb_message_received$\"]})\n\ndefmodule MessengerBot.Consumer.Echo do\n  @moduledoc \"\"\"\n  Sample consumer implementation which echos for MessengerBot message events\n  \"\"\"\n\n  use GenServer\n\n  @listener __MODULE__\n\n  def process({:mb_message_received, _id} = event_shadow) do\n    GenServer.cast(__MODULE__, {:echo, event_shadow})\n  end\n\n  # This func is not necessary, but just for an example\n  def process({topic, id}) do\n    EventBus.mark_as_skipped({@listener, topic, id})\n  end\n\n  def start_link do\n    GenServer.start_link(__MODULE__, [], name: __MODULE__)\n  end\n\n  def init(_opts) do\n    {:ok, []}\n  end\n\n  def handle_cast({:echo, {topic, id}}, state) do\n    event = EventBus.fetch_event({topic, id})\n    echo_back(event.data)\n    EventBus.mark_as_completed({@listener, topic, id})\n\n    {:noreply, state}\n  end\n\n  defp echo_back(%{app_id: app_id, page_id: page_id, messaging: messaging}) do\n    message = prepare_payload(messaging)\n    MessengerBot.send_message({app_id, page_id}, message)\n  end\n\n  defp prepare_payload(messaging) do\n    %{\n      \"messaging_type\" =\u003e \"RESPONSE\",\n      \"recipient\" =\u003e %{\"id\" =\u003e messaging[\"sender\"][\"id\"]},\n      \"message\" =\u003e %{\n        \"text\" =\u003e messaging[\"message\"][\"text\"]\n      }\n    }\n  end\nend\n```\n\n### Using Client to make HTTP request to Facebook endpoints\n\nAll MessengerBot client functions can be found on [https://hexdocs.pm/messenger_bot/1.0.0-beta10/MessengerBot.html#content).\n\n## Contributing\n\n### Issues, Bugs, Documentation, Enhancements\n\nCreate an issue if there is a bug.\n\nFork the project.\n\nMake your improvements and write your tests(make sure you covered all the cases).\n\nMake a pull request.\n\n## License\n\nLGPLv3\n\nCopyright (c) 2018 Mustafa Turan\n\nMessengerBot is an Open Source project licensed under the terms of the LGPLv3 license. Please see \u003chttp://www.gnu.org/licenses/lgpl-3.0.html\u003e for license text.\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmustafaturan%2Fmessenger_bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmustafaturan%2Fmessenger_bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmustafaturan%2Fmessenger_bot/lists"}