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 delivering a great customer experience. Using this demo as inspiration, anyone can create a delightful messaging experience that leverages both automation and live customer support. Open-source code for the app and a guide on how to deploy the experience on your local environment or remote server are provided. Access the Messenger experience

Contents

• Overview
  • Experience highlights
  • Flow diagram
  • Platform features
• Deploy this experience on Messenger
  • Requirements
    • Setup Page and app
  • Run it on a local environment
    • Using Local Tunnel to get incoming messages
    • Set webhooks and Messenger profile
    • Test app setup
    • Let's make a code change
  • Running on Heroku
    • Create a Heroku app from the CLI
    • Set environment variables
    • Set webhooks and Messenger profile
    • Test app setup
  • Troubleshooting
    • Rerun app locally
    • My Page only replies to me, but not someone else
    • Other Issues

Overview

This Messenger experience is designed to inspire and accelerate development. The guide shares design materials and source code to help with development. Original Coast Clothing has a demo Messenger automated experience as well as a Facebook Page and an eCommerce website to show entry points.

Experience highlights

The website uses the Customer Chat Plugin
QR Code with M.me link to trigger a promotional discount for the summer collection
Click to Messenger Ad displayed as a post on the Original Coast Clothing Page

Flow diagram

It is highly recommended to map out the intended experience in a Flow Diagram. Here is one for reference:

Original Coast Clothing Flow Diagram

Platform features

This experience leverages the following platform features listed below. If you decide to deploy the experience on your Page, the code will use them all:

• Send API
• Webhooks
• Quick Replies
• Templates
• Buttons
• Messenger Profile API
  • Persistent Menu
  • Get Started Button
  • Welcome Page
• Built-in NLP
• Persona API
• User Profile API
• Messenger Analytics

Deploy this experience on Messenger

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

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

The code is released under the BSD License, allowing you to use it freely for your business needs. The code is hosted on GitHub for further reference.

Requirements to deploy a Messenger app

• Facebook Page: Make sure that you have a Facebook Page since it represents your business identity when connecting with people on Messenger. 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 app, including access tokens. To create a new app, visit https://developers.facebook.com/ and click on Add New App

Setup 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 through app review for the 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 configuration

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

At this point you now have all the environmental variables and assets needed to run the app. You can run it on your local machine or hosted on Heroku. It's recommended to have a Development, Staging, and Production Environment, each of them will need their own Page and app pair.

Run it on a local environment

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 the app. Back into the 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 should set a random string, the app will use it to validate API calls.

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

The app is able to configure webhooks subscription settings on the Facebook app and configure the Page Messenger Profile all via the API.

Trigger the code that sets the configuration. Note that you need to use the value for VERIFY_TOKEN added in .env file. Call the /profile endpoint like so:

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

Test app setup

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 locales/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 an added bonus if you want to deploy this as a Heroku app, here are the steps that will allow you to do just that. A Heroku instance can be used to host the production or staging environment for 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 to Heroku

heroku git:remote -a mystic-wind-83
git push heroku master

Set 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 Setup 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.

Alternative to the Heroku app dashboard. you can set the values for each of the required vars directly on the terminal.

heroku config:set APP_ID=<VALUE> -a mystic-wind-83
heroku config:set APP_SECRET=<VALUE> -a mystic-wind-83
heroku config:set APP_URL=<VALUE> -a mystic-wind-83
heroku config:set PAGE_ID=<VALUE> -a mystic-wind-83
heroku config:set PAGE_ACCESS_TOKEN=<VALUE> -a mystic-wind-83
heroku config:set VERIFY_TOKEN=<RANDOM-STRING> -a mystic-wind-83
## Default value example
heroku config:set SHOP_URL=https://originalcoastclothing.com -a mystic-wind-83

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:

https://mystic-wind-83.herokuapp.com/profile?mode=all&verify_token=<VERIFY_TOKEN>

Optional The above URL will return the ids of personas uploaded. Since they are held in memory, you need to add those returned ids as Config Vars, so they can persist after a reload.

heroku config:set PERSONA_BILLING=<PERSONA_ID> -a mystic-wind-83
heroku config:set PERSONA_ORDER=<PERSONA_ID> -a mystic-wind-83
heroku config:set PERSONA_SALES=<PERSONA_ID> -a mystic-wind-83

Test app setup

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

Rerun app locally

After running localtunnel, via lt --port 3000, a new external address will be provided. Update the APP_URL address on the .env file, then run the NodeJS server.

node app.js

Update the webhook address on the Facebook App Settings by visiting http://localhost:3000/profile?mode=webhook&verify_token=<VERIFY_TOKEN>

My Page only replies to me, but not someone else

The Facebook app is likely still in Development Mode. You can add someone as a tester of the app, if they accept, the app will be able to message them. Once ready, you may request the pages_messaging permission to be able to reply to anyone.

Other Issues

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