Skip to content

A helper tool for creating facebook messenger bots with vapor

License

Notifications You must be signed in to change notification settings

Boilertalk/VaporFacebookBot

Repository files navigation

Join the chat at https://gitter.im/VaporFacebookBot/Lobby Build Status license swift vapor

⚗️ VaporFacebookBot

This library provides helpers for Vapor 2 to interact with the facebook bot api. It simplifies the interaction with the Send API as well as parses incoming webhooks for you.

✨ Supported features

The following is a list with all features of the facebook Send API and webhooks as of May 2017 together with a note whether it is supported or not. If you find something that's not listed there please open an issue.

Webhooks

Feature Supported Note
Parse and validate webhooks Yes
Message Received Callback Yes
Postback Received Webhook Yes
Other webhooks No If you need more webhooks open an issue

Send API

Feature Supported Note
Interact with Send API Yes
Send to page scoped id Yes
Send to phone number Yes
Send sender_action Yes e.g.: typing_on, typing_off, mark_seen
Add notification_type Yes e.g.: REGULAR, SILENT_PUSH, or NO_PUSH
Send text messages Yes
Send quick_replies Yes
Add metadata to send request Yes
Send multimedia attachments Yes (url) e.g.: image, audio, video, file
Send with attachment reuse Yes
Binary multimedia upload No If you need it open an issue
Send template attachments Partially See below...
Generic Template Yes
Button Template Yes
Receipt Template No In development...
List Template No In development...
Airline Templates No If you need it open an issue
Buttons Partially See below...
URL Button Yes
Postback Button Yes
Call Button Yes
Share Button Yes
Buy Button No If you need it open an issue
Log In Button No In development...
Log Out Button No In development...
Message Tags No If you need it open an issue
Auto parsing response No In development...

📦 Installation

This Swift package is intended to be used together with Vapor 2.0.
Add the following line to your dependencies in the Package.swift file:

.Package(url: "https://github.com/Boilertalk/VaporFacebookBot.git", majorVersion: 0)

Your Package.swift file should now look a little bit like the following:

import PackageDescription

let package = Package(
    name: "MyAwesomeBot",
    targets: [
        Target(name: "App"),
        Target(name: "Run", dependencies: ["App"]),
    ],
    dependencies: [
        .Package(url: "https://github.com/vapor/vapor.git", majorVersion: 2),
        .Package(url: "https://github.com/vapor/fluent-provider.git", majorVersion: 1),
        .Package(url: "https://github.com/Boilertalk/VaporFacebookBot.git", majorVersion: 0)
    ],
    exclude: [
        "Config",
        "Database",
        "Localization",
        "Public",
        "Resources",
    ]
)

📖 Documentation

Webhooks

First of all import VaporFacebookBot:

import VaporFacebookBot

Then you can parse facebook webhooks in your route:

// builder is your RouteBuilder
builder.post("facebook") { request in

  // Parse json body onto a callback object
  if let j = request.json {
      let callback = try FacebookCallback(json: j)
      // Loop through all entries and messaging objects as described in the facebook documentation
      for e in callback.entry {
          for m in e.messaging {
              if let mR = m.messageReceived {
                  // We have a message received callback
                  if let text = mR.message.text {
                      // We have a text
                      print(text)
                  } else if let att = mR.message.attachments {
                      // We have some attachments
                      print(att.debugDescription)
                  }
              } else if let pR = m.postbackReceived {
                  // We have a postback received callback
                  // Do something with that...
              }
          }
      }
  }

  // Return 200 OK
  var json = JSON()
  try json.set("success", true)
  return json
}

You can basically access all non optional and optional values through these objects. For a complete list of available values refer to the facebook bot documentation.

Send API

TODO: Add documentation for Send API...

🚀 Contributing

TODO: Add information for contributors...