Facebook Messenger channel

Allows to create chatbots for Facebook Messenger Platform.

Built on top of messenger4j library.

How to use

1. Include Facebook Messenger dependency to your build.gradle

implementation("com.just-ai.jaicf:facebook:$jaicfVersion")

Replace $jaicfVersion with the latest version

2. Use Facebook Messenger request and reactions in your scenarios’ actions

action {
    // Facebook Messenger request
    val fbRequest = request.facebook

    // Fetch user's profile
    val user = reactions.facebook?.queryUserProfile()
    
    // Use Messenger-specified response builders
    reactions.facebook?.audio("https://address.com/audio.mp3")
    reactions.facebook?.video("https://address.com/video.mp4")
    reactions.facebook?.file("https://address.com/file.doc")
    reactions.facebook?.sendResponse(
        MessagePayload.create(fbRequest.event.senderId(), MessagingType.RESPONSE, message)
    )

    // Or use standard response builders
    reactions.say("Hello ${user?.firstName()}")
    reactions.image("https://address.com/image.jpg")
    reactions.buttons("What can you do?")
}

Each native Facebook Messenger request event is wrapped by FacebookBotRequest and can be accessed via request.facebook?.event. Event contains additional request details depending from the event type and can be used in your scenario.

Learn more about FacebookReactions and FacebookBotRequest.

Native response builder

You can also build a response directly via reactions.facebook?.sendResponse method.

Note that Facebook Messenger works as asynchronous webhook. This means that every reactions’ method actually sends a response to the user.

3. Create Facebook page and application

Create a new Facebook App as described here. Once the app is created, generate and copy the page access token of the linked page and application secret of created app.

You can obtain your app secret from Settings > Basic on the left side bar.

4. Create and run Messenger webhook

Facebook Messenger requires you to serve a webhook for receiving a users’ requests. As well this webhook must verify a token that will be sent by Facebook Messenger Platform via GET request during the webhook configuration process.

Using JAICP

For local development:

fun main() {
    JaicpPollingConnector(
        botApi = helloWorldBot,
        accessToken = "your JAICF project token",
        channels = listOf(
            FacebookChannel
        )
    ).runBlocking()
}

For cloud production:

fun main() {
    JaicpServer(
        botApi = helloWorldBot,
        accessToken = "your JAICF project token",
        channels = listOf(
            FacebookChannel
        )
    ).start(wait = true)
}

Using Ktor

fun main() {
    val channel = FacebookChannel(
        helloWorldBot,
        FacebookPageConfig(
            pageAccessToken = "page access token",
            appSecret = "application secret",
            verifyToken = "any arbitrary string"
        )
    )

    embeddedServer(Netty, 8000) {
        routing {

            httpBotRouting("/" to channel)

            get("/") {
                call.respondText(
                    channel.verifyToken(
                        call.parameters["hub.mode"],
                        call.parameters["hub.verify_token"],
                        call.parameters["hub.challenge"]
                    )
                )
            }
        }
    }.start(wait = true)
}

5. Setup Webhook

Obtain a public URL for your webhook (using ngrok for example) and return to the Facebook application configuration. Here you have to setup a Webhook of your application. Provide an obtained URL of your agent’s webhook and the same arbitrary string you’ve used as verifyToken.

6. Test it

Once a webhook is saved, you can go to the page linked to your app and start chatting with it via Messenger.

Please note that visitors of your page cannot use your chatbot before you’ve published it through the App Review process. To start the review go to the app Messenger settings, select a required options (like pages_messaging) and submit your request.