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 |  |
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. |  |
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 |  |
It is highly recommended to map out the intended experience in a Flow Diagram. Here is one for reference:
Original Coast Clothing Flow DiagramThis experience leverages the following platform features listed below. If you decide to deploy the experience on your Page, the code will use them all:
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.
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
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
Grant Messenger access to your Facebook app
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.
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
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.
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>
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 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.
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
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
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
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
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à!
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>
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.
Is this guide wrong?, let us know by filing an Issue