FB-Messenger Scala Models

Serializable scala models for the Webhook and Send API of the Facebook Messenger Platform. This repo follows the SemVer Specification.

• Current version: 1.0.0

Usage

The original objective was to provide the models for the webhook and send APIs to facilitate the development of chatbots in the facebook messenger platform.

A chatbot project written in Scala might look something like this:

• A server validated by facebook to receive webhook events (e.g. Akka HTTP).
• Usage of io.circe.decode and the webhook models to interpret the webhook events.
• Pattern matching to identify message types (text, attachments, fallback, etc).
• Process the messages (e.g. ML, expert model, business logic).
• Build the response using the Send models.
• Send the response using io.circe.syntax for json encoding and a client http to send the post request.

A more advanced implementation involves streaming technologies, natural language processing, reinforced learning and complex business logic.

Webhook API

The webhook API is needed when a message is send to a facebook page. You may receive text messages, attachments or fallback. For a precise definition of these elements see the messenger platform official documentation for webhook events.

Usage example:

import io.circe.parser.decode

import com.rhdzmota.fbmessenger.webhook.model.Event
import com.rhdzmota.fbmessenger.webhook.model.implicits.Decoders._

// This is a facebook callback (payload a post request from fb representing an event)
val eventJsonString: String = ??? 

// We can use our implicit decoders with circe to get the event object. 
val result = decode[Event](eventJsonString)

result match {
  case Left(error)  => println("There was an error decoding the eventJsonString: " + error.toString)
  case Right(event) => println("We have an event.")
}

Event json example:

{
  "object":"page",
  "entry":[
    {
      "id":"<PAGE_ID>",
      "time":0,
      "messaging":[
        {
          "sender":{
            "id":"<PSID>"
          },
          "recipient":{
            "id":"<PAGE_ID>"
          },
          "timestamp":0,
          "message":{
            "mid":"<MID>",
            "seq":0,
            "attachments":[
              {
                "title":"<TITLE>",
                "url":"<URL>",
                "type":"location",
                "payload":{
                  "coordinates":{
                    "lat":0,
                    "long":0
                  }
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Send API

The send API is needed in order to send a message from a facebook page to a user. For a complete decription of the API see the messenger platform official documentation to send requests.

Usage example:

import io.circe.syntax._

import com.rhdzmota.fbmessenger.send.model.reply._
import com.rhdzmota.fbmessenger.send.model.message._
import com.rhdzmota.fbmessenger.send.model.message.quickreply._
import com.rhdzmota.fbmessenger.send.model.implicits.Encoders._

val recipient = Recipient("<PSID>") // Message recipient (user)
val quickReply = Text("text", "<TITLE>", "<PAYLOAD>", None) // Quick reply buttons (create none or many)
val withText = WithText("<TEXT-1>", Some(List(quickReply))) // Create text message with quick reply list (a message can be withText or withAttachment)
val withMessage = Reply.withDefaultConfigMessage(recipient, withText) // Define reply element (a reply can be done with a message or with an action)

// You can use the implicit encoders and circe syntax to serialize to json
withMessage.asJson

Send request message example:

{
  "messaging_type": "RESPONSE",
  "recipient": {
    "id": "<PSID>"
  },
  "message": {
    "text": "<TEXT-1>",
    "quick_replies": [
      {
        "content_type": "text",
        "title": "<TITLE>",
        "payload": "<PAYLOAD>"
      }
    ]
  },
  "notification_type": "REGULAR"
} 

Post request to fb-messenger

This repository only contains the models to interact with the facebook messenger API. If you are using the Send API models, you will need to figure out a way of sending the request to fb messenger. In this section we present a suggestion for sending the requests using akka http async client library.

Dependencies

• Akka HTTP

Create the required implicit variables for the Actor Model.

import akka.actor.ActorSystem
import akka.stream.{ActorMaterializer, Materializer}

import scala.concurrent.ExecutionContext

trait Context {
  implicit val actorSystem: ActorSystem = ActorSystem()
  implicit val executionContext = actorSystem.dispatcher
  implicit val materializer: Materializer = ActorMaterializer()
}

Create a Client Http object or trait with the post method.

object ClientHttp extends Context{
  def postRequest(targetUrl: String)(data: String): Future[HttpResponse] =
    Http(actorSystem).singleRequest(
      HttpRequest(
        HttpMethods.POST,
        targetUrl,
        entity = HttpEntity(ContentTypes.`application/json`, data)
      ))
}

Now we can send a request to the Facebook Messenger.

def send(data: String, apiKey: String): Unit =
  ClientHttp.postRequest(Settings.Facebook.sendUri + apiKey)(data).onComplete {
    case Failure(e)        => println(s"- Failed to post:\n$data\n- Reason:\n$e")
    case Success(response) => println(s"- Server responded with:\n$response")
  }

Contributions and authors

Feel free to create a PR or raise an issue. For more information, contact the developers of this repo:

• Rodrigo Hernández Mota

License

To be defined.