README_TEMPLATE.adoc

messenger4j

A Java library for building Chatbots on the Facebook Messenger Platform.

Using messenger4j is easy. Its modern object-oriented API is fully Java 8 compatible, expresses optionality, and is designed with immutability in mind. It is fast, powerful, and at roughly 180KB, the library is very light.

For more information on the Facebook Messenger Platform refer to the official documentation.

Please note that messenger4j 1.0.0 is a complete rewrite and has a lot of breaking changes.
Thanks for all your valuable feedback and effort to make this library even better.

Table of Contents

• Download
  • Maven
  • Gradle
• Echo Example
• Reference
  • Instantiation
  • Webhook / Receive Events
  • Send API
  • User Profile API
  • Messenger Profile API
• Requirements
• Contributing
• License

Download

Maven

<dependency>
  <groupId>com.github.messenger4j</groupId>
  <artifactId>messenger4j</artifactId>
  <version>::m4j-version-placeholder::</version>
</dependency>

Gradle

dependencies {
  compile 'com.github.messenger4j:messenger4j:::m4j-version-placeholder::'
}

Echo Example

link:src/test/java/com/github/messenger4j/test/integration/DocumentationTest.java[role=include]

Reference

Instantiation

with default HTTP-Client (okHttp)

link:src/test/java/com/github/messenger4j/test/integration/DocumentationTest.java[role=include]

with custom HTTP-Client

link:src/test/java/com/github/messenger4j/test/integration/DocumentationTest.java[role=include]

Webhook / Receive Events

helper for initial webhook verification request issued by Facebook

link:src/test/java/com/github/messenger4j/test/integration/WebhookTest.java[role=include]

handle incoming text message

link:src/test/java/com/github/messenger4j/test/integration/DocumentationTest.java[role=include]

handle incoming attachment message

link:src/test/java/com/github/messenger4j/test/integration/DocumentationTest.java[role=include]

more event types

In addition to the event types described above the following events are also supported:

• PostbackEvent

• QuickReplyMessageEvent

• ReferralEvent

• OptInEvent

• AccountLinkingEvent

• MessageDeliveredEvent

• MessageReadEvent

• MessageEchoEvent

Send API

send sender action

link:src/test/java/com/github/messenger4j/test/integration/SendTest.java[role=include]

send text message

link:src/test/java/com/github/messenger4j/test/integration/SendTest.java[role=include]

send text message with notification type and message tag

link:src/test/java/com/github/messenger4j/test/integration/SendTest.java[role=include]

send text message with quick replies

link:src/test/java/com/github/messenger4j/test/integration/SendTest.java[role=include]

send text message with metadata

link:src/test/java/com/github/messenger4j/test/integration/SendTest.java[role=include]

send image attachment message using a URL

link:src/test/java/com/github/messenger4j/test/integration/SendTest.java[role=include]

send reusable image attachment message using a URL

link:src/test/java/com/github/messenger4j/test/integration/SendTest.java[role=include]

send image attachment message using an attachment ID

link:src/test/java/com/github/messenger4j/test/integration/SendTest.java[role=include]

send button template

link:src/test/java/com/github/messenger4j/test/integration/SendTest.java[role=include]

send generic template with buttons

link:src/test/java/com/github/messenger4j/test/integration/SendTest.java[role=include]

send receipt template

link:src/test/java/com/github/messenger4j/test/integration/SendTest.java[role=include]

send list template

link:src/test/java/com/github/messenger4j/test/integration/SendTest.java[role=include]

send open graph template

link:src/test/java/com/github/messenger4j/test/integration/SendTest.java[role=include]

handle successful response

link:src/test/java/com/github/messenger4j/test/integration/SendTest.java[role=include]

User Profile API

query user information by user ID

link:src/test/java/com/github/messenger4j/test/integration/UserProfileTest.java[role=include]

Messenger Profile API

set / update Get Started button

link:src/test/java/com/github/messenger4j/test/integration/MessengerProfileTest.java[role=include]

delete Get Started button

link:src/test/java/com/github/messenger4j/test/integration/MessengerProfileTest.java[role=include]

set / update greeting text

link:src/test/java/com/github/messenger4j/test/integration/MessengerProfileTest.java[role=include]

delete greeting text

link:src/test/java/com/github/messenger4j/test/integration/MessengerProfileTest.java[role=include]

set / update persistent menu

link:src/test/java/com/github/messenger4j/test/integration/MessengerProfileTest.java[role=include]

delete persistent menu

link:src/test/java/com/github/messenger4j/test/integration/MessengerProfileTest.java[role=include]

set / update whitelisted domains

link:src/test/java/com/github/messenger4j/test/integration/MessengerProfileTest.java[role=include]

delete whitelisted domains

link:src/test/java/com/github/messenger4j/test/integration/MessengerProfileTest.java[role=include]

set / update account linking url

link:src/test/java/com/github/messenger4j/test/integration/MessengerProfileTest.java[role=include]

delete account linking url

link:src/test/java/com/github/messenger4j/test/integration/MessengerProfileTest.java[role=include]

set / update home url

link:src/test/java/com/github/messenger4j/test/integration/MessengerProfileTest.java[role=include]

delete home url

link:src/test/java/com/github/messenger4j/test/integration/MessengerProfileTest.java[role=include]

set / update target audience (open to all)

link:src/test/java/com/github/messenger4j/test/integration/MessengerProfileTest.java[role=include]

set / update target audience (closed to all)

link:src/test/java/com/github/messenger4j/test/integration/MessengerProfileTest.java[role=include]

set / update target audience (custom whitelist)

link:src/test/java/com/github/messenger4j/test/integration/MessengerProfileTest.java[role=include]

set / update target audience (custom blacklist)

link:src/test/java/com/github/messenger4j/test/integration/MessengerProfileTest.java[role=include]

delete target audience

link:src/test/java/com/github/messenger4j/test/integration/MessengerProfileTest.java[role=include]

Requirements

• Java 8+

• slf4j

• Gson

• okHttp (optional ⇒ HTTP-Client is pluggable)

Contributing

Contributions are very welcome! Please perform changes and submit pull requests from the develop branch instead of master, and open an issue before start working. When submitting code, please make every effort to follow existing conventions and style in order to keep the code as readable as possible. Please also make sure your code compiles by running mvn clean verify.

License

This project is licensed under the terms of the MIT license.