Using Facebook with Enterprise Communications API

This tutorial will show you how to acquire opt-ins to Facebook and Facebook Messenger and send messages using Enterprise Communications API's and Ruby. Click the "Start" button below to start the tutorial.

Start Tutorial

Using Facebook with Enterprise Communications API and Ruby

This short tutorial will show you how to obtain a Facebook Messenger Id for a user using the Send to Messenger web plugin from Facebook, and then how to send the user a message using the Enterprise Communications API.

tutorial's navigation controls are located above this text. Use to move to the next step of the tutorial. Use to move to the previous step of the tutorial (if there is one). Use to see an overview of all the steps in the tutorial.

To begin with you will need the following prerequisites installed:

Setup and configure the example web site

In the tutorials folder you will find a simple web site created using Ruby on Rails that renders a single page which contains the Send to Messenger web plugin populated with the correct secure metadata to allow Enterprise Communications API to capture and associate the Facebook Messenger Id with a Enterprise Communications API profile. Once the Send to Messenger has been pressed some test buttons will be shown, these will demonstrate sending simple text and rich Facebook messages via Enterprise Communications API.

To setup this project do the following:

  • Clone the Github repo for the tutorial
  • Open a console / shell and change to the Github clone folder
  • Download the required dependencies from by running:
gem install rails

Once installed you can check all is working by requesting the version of Ruby on Rails by running:

rails --version

Next we will configure the web site for your Facebook page and Enterprise Communications API API Space

Setup your Facebook channel on Enterprise Communications API

The Facebook Send to Messenger control will only render if the the Facebook channel has been setup with your Facebook page in the Enterprise Communications API portal. Follow the these instructions to setup your Facebook channel in Enterprise Communications API if you haven't already done so.

Finding your Facebook Page Id

You need to know you Facebook page numeric id for the web plugin. If you don't know this, then the simpliest way of finding it is via https://findmyfbid.com/, simply open this site and paste in your Facebook pages URL to obtain the Facebook page id.

Configuring the Send to Messenger HTML

In the .\views\index.html.erb file (highlighted) the div the Send to Messenger control renders into needs the page_id setting to your Facebook pages numeric id; do this now.

The data-ref meta-data

The code merges some meta-data into the data-ref property of the Send to Messenger div. This meta-data is used to associate the Facebook Messenger Id with a Enterprise Communications API profile and is essential. The next steps will explain how to obtain this meta-data.

Retrieving the secure meta-data

Enterprise Communications API provides a web service to create secure encypted meta-data to be passed to the Facebook Send to Messenger web plugin in the data-ref property. This web service is called each time the web page is rendered and should be passed the profileId you want to associate the Facebook Messenger Id to as a minimum, but you can pass any other data you want adding to the profile.

In this case we have hardcoded the profileId to `joe.blogs@acme.com` but in reality you should pass the unique id you use to identify customers or visitors.

Configure your Enterprise Communications API API Space details

In order for the Facebook meta-data web service call to work your must add your Enterprise Communications API API Space details.

Enter you API Space Id

Enter your API Space Id, this is used to identify the partition Enterprise Communications API uses for data storage and configuration.

To find your API Space Id you can select which API Space you want to work with by selecting it from the API Space drop down at the top of the page in the Enterprise Communications API portal. (Highlighted in yellow below)

alt

Once selected open the API Space configuration section by clicking on the Hub -> API Space Details menu item on the left of the page and your API Space Id will be shown along with other details. (Highlighted in green below)

alt

Enter you access token

Enter your access token, this is used to authenticate and authorise your API calls to Enterprise Communications API. Ensure your token has permissions to send messages and use the SMS channel.

If you need to create an access token you can do so by clicking on the Access Tokens option in the Hub section of the left hand menu. Click the Add new access token button and fill in the Name and Profile fields. The Name field describes the access token or its intended purpose such as the system that will use it. The ProfileId field is for setting the identity for the token i.e. the Enterprise Communications API profile this token represents. This is particularly useful for App Messaging where you want to message users as a virtual system user.

alt

There are a many different sets of permissions to choose from, but for our purposes simply select all the One API Access - All Channels + Branch, as we want our system to send messages on any channel.

alt

Now scroll to the bottom of the page and hit Create

Your access token will be shown with a convenient copy button on the right hand side (highlighted in green below) Ensure you copy this now and store it somewhere safe as it cannot be retrieved once you have navigated away from this page for security reasons.

alt

Running the website

To run the website now it's configured simply open a console in the tutorials folder and run:

rails server

If all has worked you can now browse the website at http://localhost:3000/ which should look like:

alt

Click on the Send to Messenger button and if required login to Facebook. In the background Facebook will send the opt-in information to Enterprise Communications API, where we will decrypt and validate the metadata. If the metadata is valid Enterprise Communications API will either append the fbMessengerId to an existing profile or create a profile using the details provided.

Once you have opted in find your profile in the Enterprise Communications API portal and check to see if you have a fbMessengerId field with a long numeric id, if so you are now ready to send a Facebook message, otherwise please go back and check you have completed all the necessary steps.

Sending messages to Facebook

Sending messages to Facebook is very simple now that you have an opted in user with their Facebook Id (fbMessngerId) stored against their Enterprise Communications API profile. To send a simple text based message you simply make a REST call to the Enterprise Communications API referencing the recipients profileId in the to section, set a body message and target the fbMessenger channel. Some basic code to do this is highlighted.

Set the profileId to send to

Set the profileId to the user you opted in on the website in the example it was `joe.blogs@acme.com; Enterprise Communications API will then automatically access the **fbMessengerId** field from the profile to send the message via Facebook. You can target a user on Facebook explicitly if you have their Facebook Messenger Id already by adding it the thetoobject in the request asfbMessengerId`.

Set the message to be sent

Enterprise Communications API will automatically create a Facebook Messenger message from your body text, making text based messages very easy indeed, set your message text now.

Run the code

Run the website by opening a console in the tutorials folder and running:

rails server

If all has worked you can now browse the website at http://localhost:3000/

Now click the Send to Messenger button, and follow the instructions, including logging into Facebook if prompted.

Click on the Send Simple Test Message button, you should receive your Facebook message very shortly, check your Facebook account online or via Facebook Messenger.

Sending rich content

Facebook messenger can support various types of rich content including:

  • Quick reply buttons
  • Attachments
  • Templates
  • Etc...

You can send any of the Facebook message body types if you use the customBody property and define a fbMessenger object (highlighted) within it that complies with the Facebook Graph API's message object as defined in the Facebook docs.

Find out more about sending custom bodies with the Facebook channel here

Click on the Send Rich Test Message button, you should receive your rich Facebook message very shortly, check your Facebook account online or via Facebook Messenger.

All done

Thanks for taking the time to look through the tutorial, to find out more visit our full documentation.

    View Code on GitHub