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 |  |
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.
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 |  |
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 DiagramHere are the platform features that this experience leverages. 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 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.
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
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
Grant Messenger access to your Facebook App
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 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=
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 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.
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
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
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.
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=
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à!
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=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.
Is this guide wrong?, let us know by filing an Issue