Using Facebook with Dotdigital Omnichannel using C#

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 send the user a message using the Dotdigital Omnichannel API.

The 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:

• Visual Studio 2017 or higher

Setup and configure the example web site

This tutorial solution is a simple web site created using ASP.Net MVC that renders a single page which contains the Send to Messenger web plugin populated with the correct secure metadata to allow Dotdigital Omnichannel to capture and associate the Facebook Messenger Id with a Dotdigital Omnichannel profile. There is also a basic identity provider which allows you to register a user and login, this is used to demonstrate how to link Facebook Ids to your users.

To setup this project do the following:

• Clone the Github repo for the tutorial
• Change directory in the repo to ./OneAPI/cSharp/Facebook
• Open the facebook.sln solution file with Visual Studio
• Build the solution to download the Nuget packages and validate you can build the code

Note: The solution should build at this stage but will not work until configured in the next steps!

Next we will configure the web site for your Facebook page and Dotdigital Omnichannel API credentials

Setup your Facebook channel in Dotdigital

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

Finding your Facebook Page Id

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

Once you have your Facebook Page Id simply enter it into the source file as indicated replaced the YOUR FACEBOOK PAGE ID place holder.

Including Send to Messenger in your page

In the .\views\index.cshtml file (highlighted) the end to Messenger control is embedded by importing the Javascript from Facebook and then creating a DIV element with the class fb-send-to-messenger which the script will render the Send to Messenger control into. In addition to the class the DIV element needs some custom attributes in order to render:

• messenger_app_id - This must always equal 336037380081042
• page_id - The numeric Facebook page id for the page you want to message the customers
• data-ref - The secure metadata generated by Dotdigital in order to ensure the opt in is associated with the correct Omnichannel profile

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 Dotdigital Omnichannel profile and is essential. The next steps will explain how to obtain this meta-data.

Retrieving the secure meta-data

Dotdigital Omnichannel provides a web service to create secure encrypted 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 are passing in the logged in users user id.

Configure your Dotdigital Omnichannel details

In order for the Facebook meta-data web service call to work your must configure your Dotdigital Omnichannel API User credentials. Please enter your API user credentials in the source file as indicated to the right, or create an API user using the instructions below:

Creating an API User

To create an API User please see this tutorial

Running the website

Build and run the solution, and a web page similar to below should be shown.

Follow the page instructions to register a user or login with the built in user using:

• Username: test@acme.com
• Password: Passw0rd!

Once registered or logged in click on the Send to Messenger button and if required login to Facebook. In the background Facebook will send the opt-in information to Dotdigital, where we will decrypt and validate the metadata. If the metadata is valid Dotdigital Omnichannel will either append the fbMessengerId to an existing Omnichannel profile or create a new Omnichannel profile using the details provided. You will can now send Facebook messages to this Omnichannel profile using the profile id to specify the user.

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 Dotdigital Omnichannel profile. To send a simple text based message you simply make a REST call to the Omnichannel 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.

If you want to use this tutorials code in your own projects ensure you add a NuGet dependencies for JSON.Net and RestSharp libraries.

Note: In the tutorial we use serializable classes to create the required request JSON, but you could simply create the JSON as a string instead.

Set the profileId to send to

Set the profileId to the user you opted in on the website; in the example it was test@acme.com; Dotdigital Omnichannel will then automatically access the fbMessengerId field from the Omnichannel 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 the to object in the request as fbMessengerId.

Set the Messaging Type & Tag

You need to specify a message type if your message if not a direct response to a customers inbound message e.g. it is a notification message and you haven't specified a messageTag. You should set the Facebook (fbMessenger) channelOptions messageType to MESSAGE_TAG for these messages to be sent, along with an appropriate messageTag value.

More info on the message types you can select from can be found here. Please review the Messenger Platform Policy for more information on Facebook message types.

Full documentation on how to use the Facebook Messenger channel with API can be found here.

Set the message to be sent

Dotdigital Omnichannel 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

To run the website, and login or register, ensure you have opted in by clicking the Send to Messenger button.

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.