# MessengerBot

Unofficial Facebook Messenger Platform *chatbot client* and *webhook handler*

MessengerBot covers majority of the functions to make calls to Facebook Messenger Platform endpoints.

MessengerBot 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.

## Installation

The package can be installed by adding `messenger_bot` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [{:messenger_bot, "~> 1.0"}]
end
```

## Configuration

### Facebook Messenger App and Page configurations

`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 `Map.t()` type.

If 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.

*Note:* `App` and `Page` keys must be atom() type like in the examples. For `config.exs` you can add apps and pages like below:

```elixir
config :messenger_bot,
  apps: %{
    "1881" => %{
      id: "1881",
      secret: "SECRET",
      setup_token: "Setup Token",
      access_token: "ATOKEN123"
    }
  },
  pages: %{
    "1881" => %{
      "1234" => %{
        id: "1234",
        name: "Demo Facebook Messenger Bot",
        token: "accesstokenforpage"
      }
    }
  }

Any time after loading `messenger_bot`, you can add more pages for an app.

```elixir
pages = %{
  "1234" => %{
    id: "1234",
    name: "Demo Facebook Messenger Bot",
    token: "accesstokenforpage"
  },
  "1298" => %{
    id: "1298",
    name: "Demo Facebook Messenger Bot 1298",
    token: "accesstokenforpagefor1298"
  }
}

# Update configurations
MessengerBot.Config.save_pages(app_id, pages)
```

Any time after loading `messenger_bot`, you can save apps too.

```elixir
apps = %{
  "1881" => %{
    id: "1881",
    secret: "SECRET",
    setup_token: "Setup Token",
    access_token: "ATOKEN123"
  }
}

# Update configurations
MessengerBot.Config.save_apps(apps)
```

### Facebook App setup configuration

Add webhook endpoints to your router:

```elixir
# The code below will add following routes
# -> GET   /some-path-for-messenger_bot/:app_id (200)
# -> POST  /some-path-for-messenger_bot/:app_id (200)
# -> MATCH /some-path-for-messenger_bot/:any (404)

forward "/some-path-for-messenger_bot", to: MessengerBot.Web.Router
```

### Event Topics Configuration

Update your `config.exs` to add `messenger_bot` event topics for `event_bus`:

```elixir
config :event_bus,
  topics: [:mb_webhook_received,
    :mb_delivery_received,
    :mb_read_received,
    :mb_message_echo_received,
    :mb_message_attachments_received,
    :mb_message_quick_reply_received,
    :mb_message_received,
    :mb_optin_received,
    :mb_postback_received,
    :mb_referral_received,
    :mb_game_play_received,
    :mb_payment_received,
    :mb_checkout_update_received,
    :mb_pre_checkout_received,
    :mb_account_linking_received,
    :mb_policy_enforcement_received,
    :mb_app_roles_received,
    :mb_standby_received,
    :mb_pass_thread_control_received,
    :mb_take_thread_control_received,
    :mb_request_thread_control_received,
    :mb_na_received,
    :mb_app_setup_received,
    :mb_attachment_upload_succeeded,
    :mb_create_message_creatives_succeeded,
    :mb_broadcast_message_succeeded,
    :mb_pass_thread_control_succeeded,
    :mb_take_thread_control_succeeded,
    :mb_request_thread_control_succeeded,
    :mb_fetch_secondary_receivers_succeeded,
    :mb_id_matching_succeeded,
    :mb_create_messenger_code_succeeded,
    :mb_fetch_messaging_feature_review_succeeded,
    :mb_fetch_insights_succeeded,
    :mb_set_messenger_profile_succeeded,
    :mb_reset_messenger_profile_succeeded,
    :mb_fetch_messenger_profile_succeeded,
    :mb_send_message_succeeded,
    :mb_unlink_account_succeeded,
    :mb_fetch_user_profile_succeeded,
    :mb_attachment_upload_failed,
    :mb_create_message_creatives_failed,
    :mb_broadcast_message_failed,
    :mb_pass_thread_control_failed,
    :mb_take_thread_control_failed,
    :mb_request_thread_control_failed,
    :mb_fetch_secondary_receivers_failed,
    :mb_id_matching_failed,
    :mb_create_messenger_code_failed,
    :mb_fetch_messaging_feature_review_failed,
    :mb_fetch_insights_failed,
    :mb_set_messenger_profile_failed,
    :mb_reset_messenger_profile_failed,
    :mb_fetch_messenger_profile_failed,
    :mb_send_message_failed,
    :mb_unlink_account_failed,
    :mb_fetch_user_profile_failed,
    :mb_attachment_upload_erred,
    :mb_create_message_creatives_erred,
    :mb_broadcast_message_erred,
    :mb_pass_thread_control_erred,
    :mb_take_thread_control_erred,
    :mb_request_thread_control_erred,
    :mb_fetch_secondary_receivers_erred,
    :mb_id_matching_erred,
    :mb_create_messenger_code_erred,
    :mb_fetch_messaging_feature_review_erred,
    :mb_fetch_insights_erred,
    :mb_set_messenger_profile_erred,
    :mb_reset_messenger_profile_erred,
    :mb_fetch_messenger_profile_erred,
    :mb_send_message_erred,
    :mb_unlink_account_erred,
    :mb_fetch_user_profile_erred]
```

## Usage

### Webhook handling

MessengerBot library handles allows you to handle all webhooks with subscription to the events.

#### How to subscribe to event topics?

`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 and log all events you can use `EventBus.subscribe({MessengerBot.Processor.Log, [".*"]})`.

```elixir
# Sample listener implementation for `MessengerBot` events
defmodule MessengerBot.Processor.Log do
  @listener __MODULE__

  def process({topic, event_id}) do
    event = EventBus.fetch_event({topic, event_id})
    Logger.info(fn -> inspect(event) end)
    EventBus.mark_as_completed({@listener, topic, event_id})
  end
end
```

### Using Client to make HTTP request to Facebook endpoints

All MessengerBot client functions can be found on [https://hexdocs.pm/messenger_bot](https://hexdocs.pm/messenger_bot).

## Contributing

### Issues, Bugs, Documentation, Enhancements

Create an issue if there is a bug.

Fork the project.

Make your improvements and write your tests(make sure you covered all the cases).

Make a pull request.

## License

LGPLv3

Copyright (c) 2018 Mustafa Turan

MessengerBot is an Open Source project licensed under the terms of the LGPLv3 license.  Please see <http://www.gnu.org/licenses/lgpl-3.0.html>
for license text.

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE 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.