PHPFaceBot

PHPFaceBot is a framework that provides all the groundwork to create a Facebook Messenger Bot app in PHP.

To use this, you'll need to have a web server running Apache, with PHP 5.3+. See system requirements below for more details.

To set up a Facebook Messenger Bot now, see the instructions below.

Facebook Messenger Bot setup quick guide

Follow this documentation.

Brief steps: (after completing server setup with working Apache, see below)

1. Create app and page.
2. Go to the app's App Dashboard, Add Product -> Messenger.
3. Setup webhooks.
4. Check fields message_deliveries, messages, messaging_optins, and messaging_postbacks. Also use messaging_referrals for getting ref parameters.
5. Get Page Access token.
6. Subscribe App to Page.
7. Test.

Setting up with Apache

1. Git clone this repo in your home directory.
2. Use the example apache config file, edit accordingly, put in your Apache vhost or conf.d directory.
3. Run letsencrypt to get SSL certs - this is required, Facebook wants all webhooks to have SSL.
4. (Alternatively, use Cloudflare's free plan and get SSL that way, but you need to wait 24 hours for the cert)
5. Verify your setup by visiting your domain on browser.

Supported Messenger API features

• Webhook
  • Receiving messages
    • Text
    • Image
    • Sticker
    • Location
    • Quick Reply
  • Receiving postbacks
  • Receiving deliveries
  • Receiving optins
• Send API
  • Text
  • Image as url
  • Image as attachment
  • Quick replies
  • Templates
    • Button (text with buttons)
    • Generic (carousel display)
    • List (vertical list display)
  • Buttons
    • URL
    • Postback
    • Share
    • Buy
  • Sender actions
    • Mark as seen
    • Typing on
• Webview and Extensions
• Plugin
  • Send to messenger (opt-in)
  • Message Us
• Thread Settings (being deprecated by FB, use Messenger Profile instead)
  • Greeting text
  • Get Started button
  • Persistent menu
  • Domain whitelisting
• Messenger Profile
  • Greeting text
  • Get Started button
  • Persistent menu
    • Nested menu items
  • Domain whitelisting
• User profile API
  • first_name, last_name, profile_pic, locale, timezone, gender, is_payment_enabled

The framework also handles:

• Security
  • Properly validates a webhook request using the X-Hub-Signature that Facebook provides, to match against the hashed payload using Facebook app secret.
• Batching
  • High traffic volume bots can get messages in a batch. A request can contain multiple entrys, and each entry can contain multiple messagings. This framework handles both properly.
• Gracefully fail
  • PHP fatal errors normally return a 500 HTTP code. This causes Facebook to repeatedly try the request and eventually switching off your webhook endpoint. The framework handles this and gracefully fail the request without alarming Facebook's servers, even if some code paths lead to fatal errors.
• Acknowledging messages
  • Facebook expects the webhook endpoint to acknowledge and return a 200 HTTP response ASAP. If the request isn't returned within 15 seconds, it is considered a failure and will be repeated. The framework handles this and close the request with a 200 response properly before executing other code. This allows you to do sleep()s and send multiple messages as a response to a message.
• Wit.ai NLP
  • Contains a simple Wit API wrapper to allow you to send text messages to wit.ai's intent parsing service to parse a natural language text if needed.
• Analytics
  • Contains the Mixpanel API wrapper along with a queue and consumer setup, to allow for tracking any number of events to a Mixpanel account.

Unsupported Messenger API features

• Webhook
  • Receiving checkout updates
  • Receiving payments
  • Receiving account linkings
• Subscribe bot to page (can just use their web page UI for this)
• Send API
  • Audio as attachment
  • Video as attachment
  • File as attachment
  • Templates
    • Receipt
    • Airline boarding pass
    • Airline checkin
    • Airline itinerary
    • Airline flight update
  • Buttons
    • Call
    • Log in, log out
  • Sender actions
    • Typing off
• Plugin
  • Checkbox
• Thread Settings
  • Account linking
  • Payment settings

System requirements

Required:

1. PHP 5.3 or above
2. Apache web server
3. PHP module: curl - to make HTTP API requests
4. PHP module: json - to encode/decode data to and from API

Optional:

1. Redis - my choice of a data store (database). Optional because the demo bot can still run without it, just set REDIS_ENABLED to 0 in your config file. Some features will be disabled without it.
2. phpiredis - my choice of a PHP Redis client. You can use a different Redis client (and modify the Redis.php wrapper code), or you can even use a different database.
3. PHP module: POSIX - only if you want to use the built-in queue-consumer setup for sending analytics data to Mixpanel.
4. APC - my opcode cache of choice, which also provides user cache features. (If you use PHP 5.5+, you get OPcache, which accomplishes the same thing. Similar to PHP-FPM.)

Included PHP libraries in this framework

For documentation purposes, here is the list of PHP libraries that are included in this framework. I am including their code files in this framework directly so it's not necessary to install composer or run composer updates when using this.

1. ToroPHP - quick, simple and robust URL routing.
2. PHPWit.ai - very simple PHP bindings for wit.ai API, for only the NLP (text processing) method.
3. Mixpanel PHP - only needed if you want to send tracking data to Mixpanel analytics service.
4. phpJobDaemon - only needed if you want to use the queue consumer setup for Mixpanel