The Messages API is being integrated into the Client SDK. This will provide a straightforward method where your customers, via Facebook Messenger, WhatsApp, Viber, and more, can communicate with an application you create.
By the end of this blog post, you’ll have a web application capable of sending and receiving messages from your Facebook page and your page’s Messenger. Sample code will be provided and the relevant parts to the Messages API integration will be explained.
Create a Facebook page
Log into Facebook and create a Test Facebook page. You can also test with a page that already exists.
Set up the sample web application
Make your copy of the sample web application by remixing this Glitch. To get your application set up, follow the steps in the readme file. The sample application follows the scenario of an agent signing into a dashboard, with current conversations between Facebook page customers and the agent. On the left side is where all the conversations are happening, and the agent can join one.
When the agent clicks a conversation, a chat application with the Facebook User will open in a new window. The chat application is based on the one created in the Creating a chat app tutorial.
Link your Facebook page to your Vonage application
All that is left of the setup is to connect your Facebook page to the web application so they can communicate back and forth. Here are the steps:
- Log into the Vonage Dashboard
- Under “Messages and Dispatch” click “Social channels”
- On the “Social channels” page, click Facebook Messenger
- Follow the steps to connect your Facebook page to your Vonage Account
- Select the Facebook page(s) to connect to Vonage
- Verify you are using the correct Facebook account
- Review the permissions granted to Vonage
- Confirmation that Vonage was able to be successfully linked
- Select a Facebook page that was linked to Vonage and complete the setup
- Congratulations, your Facebook page was successfully connected
- Now that Vonage knows about your Facebook page, let’s connect to your Vonage application that was created when you set up the sample with Glitch. Either click “Link to an application” or go to the Applications section of the dashboard.
- Select the application you created when setting up the Glitch sample and then click “Link”.
Try it out
Place the web application in one browser window and open Facebook Messenger in another and login if necessary. If you haven’t already, enter a name in the web application to enter the dashboard. Think of this as your name or an agent’s name, it’s just a simple way to “log in”. Now, in Messenger, find the Facebook Page you linked to the application and send a message. In the window with your web application, a little card should appear in the “All Conversations” section. Click join, a chat application will open up, and you should see the message in the chat. Send a message from the chat application, and it should appear in your Facebook Messenger.
Let’s take a look at the code involved to make the above happen. When a user sends a message to your Facebook page, it gets sent by Vonage to your web application’s inbound webhook. The webhook returns an object that lets Vonage know how to handle the message. In this case, we are sending back information the Client SDK Messages API Integration needs to connect the Facebook User with your web application to have a conversation. This includes the Facebook User’s id and the conversation name (which we set as the Facebook User’s id so that it’s unique).
If this is the first time the Facebook User sends a message, a new conversation is created. This emits a
conversation:created event that we listen for on the events webhook. The web application's backend takes this event and repackages it as a custom event,
custom:new_conv, that can be used to notify the agent's dashboard to display the new conversation.
In the code for the chat application, there is a
message:received event listener that fires when a message is received from the Facebook User. It then takes the message and adds it to the chat display.
When the agent responds to the Facebook User, that is an outbound message. Full implementation of outbound messages into the Client SDK will be completed in a future release. Until then, just like listening for when a new conversation is created, we can listen for when a
custom:chat event is sent to the events webhook. The Vonage Node SDK is used to relay the agent's message to the Facebook User.
For those wondering,
FB_RECIPIENT_ID is also the Conversation Name that was set when the initial message was sent from the Facebook User. Getting the value for
FB_SENDER_ID, the Facebook Page Id, is a little more involved. When an agent opens a chat, a request is made to the server's
getChatAppAccounts endpoint which makes a call to Vonage's
chatapp-accounts API with an admin JWT. The Facebook Page Id is in the response, which we send back to the client. The good news is, when Outbound Messages gets integrated, you won't have to worry about any of this, and the Client SDK will take care of everything. This is an example of how the Client SDK can be very helpful when developing applications.
If your outbound messages stop working all of a sudden, check your server log for any errors. If you come across an error that has this:
That means your Facebook Page token has expired and will need to be refreshed. Log into the Vonage dashboard and go to Messages and Dispatch, then Social Channels. A button should be next to your Facebook Page to refresh your token.
That’s it! With the Messages API integrated into the Client SDK, it is a lot easier to communicate with a Facebook User from your own web application.
Please have a look at our Client SDK documentation. There’s more information on the methods used to create the Agent Dashboard, along with Tutorials, Guides, and more. Ran into any issues with the demo application? Looking to add new functionality? Any questions, comments, and/or feedback, please let us know in our Community Slack Channel