Sample Messenger App - Original Coast Clothing

Original Coast Clothing (OC) is a fictional clothing brand created to showcase the key features of the Messenger Platform. OC leverages key features to deliver a great customer experience. Using this demo as inspiration, you can create a delightful messaging experience that leverages both automation and live customer support. We are also providing the open source code of the app and a guide on how to deploy the experience on your local environment or remote server.

Access the Messenger experience

Overview

This Messenger experience is designed to inspire and accelerate your development. In this guide we share the design materials and the code for you to create your own.

In order to mimic the user Messenger experience, we have created a Facebook Page as well as an e-commerce website.

Experience highlights

The website uses the Customer Chat Plugin

QR Code with M.me link to trigger a promotion discount in the summer collection

Click to Messenger Ad displayed as a post on the Original Coast Facebook Page

Flow Diagram

As a developer, we highly recommend you map out your experience in a Flow Diagram. Here is the one we used:

Original Coast Clothing Flow Diagram

Platform Features

Here are the platform features that this experience leverages. If you decide to deploy the experience on your page, the code will use them all:

Deploy this experience on your Messenger

By the end of this guide, you'll have a full Messenger app running on your server, answering messages for your test page.

The code that powers this experience is open source so that you can easily get started with developing a great messaging experience for your business. Once done, you'll be able to contact your page via Messenger and get automated responses from your server.

The code is released under the BSD License, so after testing you can alter it to fit your business needs. The code is hosted on GitHub for further reference.

Requirements

  • Facebook Page: Make sure that you have a Facebook page, because we will be using the page as the identity for your messaging experience. To create a new Page, visit https://www.facebook.com/pages/create, you can also set up a test page to start.

  • Facebook Developer Account: Required to create new apps, which are the core of any Facebook integration. You can register as a developer by going to the Facebook Developers website and clicking the "Get Started" button.

  • Facebook App: Contains the settings for your Messenger automation, including access tokens. To create a new app, visit https://developers.facebook.com/ and click on Add New App

Set up your Page and app

The objective of this section is to gather all the access tokens and ids necessary for the Messenger App to successfully send and receive messages. Before you begin, make sure you have completed all of the requirements listed above. At this point you should have a Page and a registered Facebook App.

If you just created a new Facebook app, it is probably in development mode. Note that apps in this mode are only allowed to message people connected to the app (Admins, Developers and Testers). You can continue with this guide in this mode, but once your app is ready to be public, the app needs to go for app review of pages_messaging permission. For more info, see App Review

Additionally, this experience uses extended page features and app permissions that also need review, to allow the app to read the user gender and locale fields. Again, apps in development mode can see these fields only for the people connected to the app. For more information, see User Profile API

Now let's collect the following values for your installation

PAGE_ID=
APP_ID=
PAGE_ACCESS_TOKEN=
APP_SECRET=

Let's get the App id and App Secret

  1. Go to your app dashboard and then to Basic Settings, Find your app here
  2. Save the App ID number and the App Secret

Grant Messenger access to your Facebook App

  1. Go to your app Dashboard
  2. Under Add Product find Messenger and click Set Up
  3. Now you should be in the App Messenger Settings
  4. Under Access Tokens, click on Edit Permissions
  5. Select the desired page and allow Manage and access Page conversations in Messenger
  6. Select the desired page and an access token should appear
  7. Get the Page ID from the page access token by using the Access Token Debugger

Run it on your local machine

Now it's time to get the code and run it on your local machine. You'll need NodeJS 10.x or higher, check your current version with the following command

node -v

Clone this repository on your local machine:

git clone https://github.com/fbsamples/original-coast-clothing.git
cd original-coast-clothing

Install the code dependencies

yarn install

Using Local Tunnel to get incoming messages

In order to receive messages, we need to be able to get incoming webhooks from Facebook Servers. So we need an external address, a quick way to do this is to use Localtunnel since it will provide an external https address that will tunnel into your NodeJS running App.

To install Local Tunnel

npm install -g localtunnel

Open a new terminal tab and request a tunnel to your local server with your preferred port

lt --port 3000

You'll get a URL similar to https://grizzly.localtunnel.me, that you can use to set the APP_URL variable. While the lt command is running, any requests will be routed to your local port. Every time you run the command, a new address will be provided for you.

Set webhooks and Messenger Profile

Now we have all the elements needed to run our app. Back into our first terminal, let's use the provided template to fill all the environmental values.

mv .sample.env .env

Edit the .env file to add all the values for your app and page as collected in previous steps. Note that for VERIFY_TOKEN you can set any random string.

Run your app locally using the built-in web server

node app.js

You should now be able to access the application in your browser at http://localhost:3000

Configure your Facebook app webhook subscription and set the Messenger profile

The Messenger app is able to configure the webhooks on the Facebook app and well as configure the Messenger Profile on your Page using the API. Let's now trigger that configuration using our browser. Note that you need to edit the verify_token param with the value for VERIFY_TOKEN that you added in .env file. Call the /profile endpoint like so:

http://localhost:3000/profile?mode=all&verify_token=

Test that your app setup is successful

Send a message to your Page from Facebook or in Messenger, if your webhook receives an event, you have fully set up your app! Voilà!

Let's make a code change

Let's edit the file locale\en_US.json, replacing the message under get_started.welcome and change it from "Hi {{userFirstName}}! Welcome to Original Coast Clothing..." to something else.

Back on the first terminal, every time you change the code, you'll need to restart the NodeJS server. Let's stop the server with Ctrl-C and run it again, to reload the new code.

node app.js

Open your Messenger and message your page the word "Hi", you should get the new message.

Deploy the App on Heroku

As added bonus if you want to deploy this as a Heroku app, to have it always running with a permanent address, here are steps that will allow you to do just that. Assuming that you successfully did the steps to run the code on a test page and that you'll use the Heroku server for your production environment or your business page.

You'll need the Heroku CLI, check if you don't already have it, with the following command

heroku -v

Create a Heroku app from the CLI

git init
heroku apps:create
# Creating app... done, ⬢ mystic-wind-83
# Created http://mystic-wind-83.herokuapp.com/ | git@heroku.com:mystic-wind-83.git

Deploy the code

git add .
git commit -m "My first commit"
git push heroku master

Set your environment variables (Config Vars)

On Heroku the environment is not set up via a .env file but by setting your Heroku app Config Vars. You can find them in your Heroku App Dashboard, https://dashboard.heroku.com/apps/mystic-wind-83/settings.

Similar to the Set up step needed for development setup, you'll need to set the same variables described in the the .sample.env. If this is the production environment, the page id and corresponding page access token, will be for the business page instead of the test page used on the development environment.

Set webhooks and Messenger Profile

You should now be able to access the application. Use the VERIFY_TOKEN that you created as config vars and call the /profile endpoint like so:
http://mystic-wind-83.herokuapp.com/profile?mode=all&verify_token=

Test that your app setup is successful

Send a message to your Page from Facebook or in Messenger, if your webhook receives an event, you have fully set up your app! Voilà!

Troubleshooting

I closed all terminals, how do I run again the app locally

If you closed the localtunnel and run the lt --port 3000 again a new address will be provisioned to you. You need to update that address into the APP_URL variable on the .env file, load the code by running the NodeJS server.

node app.js

Run the profile endpoint in webhook mode to refresh the address on the Facebook App Settings.

http://localhost:3000/profile?mode=webhook&verify_token=

My page only replies to me, but not someone else

You Facebook App is most likely still in Development Mode, add the person as a tester of your app. Once ready go for review of pages_messaging to be able to reply to anyone.

Other Issues

Is this guide wrong?, let us know by filing an Issue