Post has been updated to use JavaScript Client SDK version 8.3.0 that can now handle outgoing messages.
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.
Log into Facebook and create a Test Facebook page. You can also test with a page that already exists.
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.
Sample application's agent dashboard
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.
Chat application demo
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”
Vonage Dashboard Messages and Dispatch menu
On the “Social channels” page, click Facebook Messenger
Vonage Dashboard Social channels section
Follow the steps to connect your Facebook page to your Vonage Account
Connect Facebook Page
Select the Facebook page(s) to connect to Vonage
Select a Facebook Page
Verify you are using the correct Facebook account
Continue as user
Review the permissions granted to Vonage
Ask for permissions
Confirmation that Vonage was able to be successfully linked
Confirmation of Facebook Page being successfully linked
Select a Facebook page that was linked to Vonage and complete the setup
Select your Facebook Business Page
Congratulations, your Facebook page was successfully connected
Confirmation that Facebook Business 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.
Your applications
Select the application you created when setting up the Glitch sample and then click “Link”.
Application details
Application details with Facebook page linked
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).
// server.js
app.post("/webhooks/inbound", (request, response) => {
// By responding to the inbound message callback with this action you add -
// the message to a conversation so the agent client side will be notified about it
response.status(200).send([
{
action: "message",
// Creating a new conversation for every NEW incoming user.
// Messages from the same user will be tagged to the same conversation
conversation_name: request.body.from,
user: request.body.from,
geo: "region-code",
},
]);
});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.
// server.js
app.post("/webhooks/rtcevent", (request, response) => {
...
// If Facebook user is new, a new conversation should be created, so listen for it here
// and then send the custom event to the Agents Conversation
if (request.body.type === "conversation:created"){
vonage.conversations.events.create(process.env.AGENTS_CONV_ID, {
"type": "custom:new_conv",
"from": "system",
"body": request.body
},
(error, result) => {
if (error) {
console.error(error);
} else {
console.log(result);
}
});
}
response.status(200).send({code:200, status: 'got rtcevent request'});
});In the code for the chat application, there is a message 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.
// public/chat.js
// Adding conversation.id here in the on. means that we're filtering events to only the ones regarding this conversation. (it's called grouping)
conversation.on('message', conversation.id, (from, event) => {
console.log('message-received sender: ', from);
console.log('message-reveived event: ', event);
const formattedMessage = formatMessage(from, event, conversation.me);
// Update UI
messageFeed.innerHTML = messageFeed.innerHTML + formattedMessage;
messagesCountSpan.textContent = messagesCount;
});When the agent responds to the Facebook User, that is an outbound message. The Client SDK has a sendMessage method with a "message_type": "text" to send the agent's message. With that, Vonage takes care of everything required to get the message to the Facebook User.
// public/chat.js
// Listen for clicks on the submit button and send the existing text value
sendButton.addEventListener('click', async () => {
conversation.sendMessage({
"message_type": "text",
"text": messageTextarea.value
}).then((event) => {
console.log("message was sent", event);
}).catch((error)=>{
console.error("error sending the message ", error);
});
messageTextarea.value = '';
});To add a little more personalization, we display the Facebook Page's name at the top of the chat. To get this, 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's name is in the response, which we send back to the client.
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:
status: 'rejected',
error: { reason: 'Expired access Token', code: 1370 }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.
){kind=small}
