Quick Start Tutorial

If you have not already, follow our app setup guide to set up your Facebook app for use with the Messenger Platform.

All requests to Messenger Platform APIs are authenticated by including a page-level access token in the access_token parameter of the query string.

If you did not already do so when you set up your Facebook app, generate a page access token, by doing the following:

It is recommended that you keep sensitive information like your page access token secure by not hardcoding it into your webhook.

To do this, add the following to your environment variables, where <PAGE_ACCESS_TOKEN> is the access token you have just generated and <VERIFY_TOKEN> is a random string that you set to verify your webhook:

PAGE_ACCESS_TOKEN="<PAGE_ACCESS_TOKEN>"
VERIFY_TOKEN="<VERIFY_TOKEN>"

Now all you have to do is add your page access token and verify token at the top of your app.js file, to use it in your webhook logic:

const PAGE_ACCESS_TOKEN = process.env.PAGE_ACCESS_TOKEN;
const VERIFY_TOKEN = process.env.VERIFY_TOKEN;

To start, we will stub out three functions that will handle the incoming webhook event types we want to support, as well as responding via the send API. To do this, append the following to your app.js file:

// Handles messages events
function handleMessage(sender_psid, received_message) {

}

// Handles messaging_postbacks events
function handlePostback(sender_psid, received_postback) {

}

// Sends response messages via the Send API
function callSendAPI(sender_psid, response) {
  
}

To respond to people on Messenger, the first thing we need is to know who they are. In Messenger this is accomplished by getting the message sender's page-scoped ID (PSID) from the incoming webhook event.

What is a PSID?

A person is assigned a unique page-scoped ID (PSID) for each Facebook Page they start a conversation with. The PSID is used to identify a person when sending messages.

If you completed one of the options in the Starter Project section above, you should have a basic /webhook endpoint that accepts POST requests and logs the body of received webhook events that looks like this:

app.post('/webhook', (req, res) => {  

  // Parse the request body from the POST
  let body = req.body;

  // Check the webhook event is from a Page subscription
  if (body.object === 'page') {

    // Iterate over each entry - there may be multiple if batched
    body.entry.forEach(function(entry) {

      // Get the webhook event. entry.messaging is an array, but 
      // will only ever contain one event, so we get index 0
      let webhook_event = entry.messaging[0];
      console.log(webhook_event);
      
    });

    // Return a '200 OK' response to all events
    res.status(200).send('EVENT_RECEIVED');

  } else {
    // Return a '404 Not Found' if event is not from a page subscription
    res.sendStatus(404);
  }

});

To get the sender's PSID, update the body.entry.forEach block with the following code to extract the PSID from the sender.id property of the event:

We want our experience to be able to handle two types of webhook events: messages and messaging_postback. The name of the event type is not included in the event body, but we can determine it by checking for certain object properties.

What are webhook events?

The Messenger Platform sends webhook events to notify you of actions that occur in Messenger. Events are sent in JSON format as POST requests to your webhook. For more information, see Webhook Events.

To do this, update the body.entry.forEach block of your webhook with a conditional that checks whether the received event contains a message or postback property. We will also add calls to the handleMessage() and handlePostback() functions that we stubbed out earlier:

body.entry.forEach(function(entry) {

  // Gets the body of the webhook event
  let webhook_event = entry.messaging[0];
  console.log(webhook_event);


  // Get the sender PSID
  let sender_psid = webhook_event.sender.id;
  console.log('Sender PSID: ' + sender_psid);

  // Check if the event is a message or postback and
  // pass the event to the appropriate handler function
  if (webhook_event.message) {
    handleMessage(sender_psid, webhook_event.message);        
  } else if (webhook_event.postback) {
    handlePostback(sender_psid, webhook_event.postback);
  }
  
});

Now that our incoming messages are being routed to the appropriate handler function, we will update handleMessage() to handle and respond to basic text messages. To do this, update the code to define the message payload of our response, then pass that payload to callSendAPI(). We want to respond with a basic text message, so we define a JSON object with a "text" property:

function handleMessage(sender_psid, received_message) {

  let response;

  // Check if the message contains text
  if (received_message.text) {    

    // Create the payload for a basic text message
    response = {
      "text": `You sent the message: "${received_message.text}". Now send me an image!`
    }
  }  
  
  // Sends the response message
  callSendAPI(sender_psid, response);    
}

Time to send your first message with the Messenger Platform's Send API!

In handleMessage(), we are calling callSendAPI() so now we need to update it to construct the full request body and send it to the Messenger Platform. A request to the Send API has two properties:

• recipient: Sets the intended message recipient. In this case, we identify the person by their PSID.
• message: Sets the details of the message to be sent. Here, we will set it to the message object we passed in from our handleMessage() function.

To construct the request body, update the stub for callSendAPI() to the following:

function callSendAPI(sender_psid, response) {
  // Construct the message body
  let request_body = {
    "recipient": {
      "id": sender_psid
    },
    "message": response
  }
}

Now all we have to do is send our message by submitting a POST request to the Send API at https://graph.facebook.com/v2.6/me/messages.

Note that you must append your PAGE_ACCESS_TOKEN in the access_token parameter of the URL query string.

const request = require('request');

function callSendAPI(sender_psid, response) {
  // Construct the message body
  let request_body = {
    "recipient": {
      "id": sender_psid
    },
    "message": response
  }

  // Send the HTTP request to the Messenger Platform
  request({
    "uri": "https://graph.facebook.com/v2.6/me/messages",
    "qs": { "access_token": process.env.PAGE_ACCESS_TOKEN },
    "method": "POST",
    "json": request_body
  }, (err, res, body) => {
    if (!err) {
      console.log('message sent!')
    } else {
      console.error("Unable to send message:" + err);
    }
  }); 
}

Test It!

In Messenger, send another text message to your Facebook Page. You should receive an automated response from your Messenger experience that echoes back your message and prompts you to send an image.

Since our response prompts the message recipient to send an image, our next step is to update our code to handle an attachment. Sent attachments are automatically saved by the Messenger Platform and made available via a URL in the payload.url property of each index in the attachments array, so we will also extract this from the event.

What attachment types are supported?

Your Messenger experience can send and receive most asset types, including images, audio, video, and files. Media is displayed and is even playable in the conversation, allowing you to create media-rich experiences.

To determine if the message is an attachment, update the conditional in your handleMessage() function to check the received_message for an attachments property, then extract the URL for it. In a real-world bot we would iterate the array to check for multiple attachments, but for the purpose of this quick start, we will just get the first attachment.

function handleMessage(sender_psid, received_message) {

  let response;

  // Checks if the message contains text
  if (received_message.text) {
    
    // Creates the payload for a basic text message, which
    // will be added to the body of our request to the Send API
    response = {
      "text": `You sent the message: "${received_message.text}". Now send me an attachment!`
    }

  } else if (received_message.attachments) {
  
    // Gets the URL of the message attachment
    let attachment_url = received_message.attachments[0].payload.url;
  
  } 
  
  // Sends the response message
  callSendAPI(sender_psid, response);    
}

Next, we will respond to the image with a generic template message. The generic template is the most commonly used structured message type, and allows you to send an image, text, and buttons in one message.

Are other message templates available?

Yes! The Messenger Platform provides a set of useful message templates, each designed to support a different, common message structure, including lists, receipts, buttons, and more. For complete details, see Templates.

Message templates are defined in the attachment property of the message, which contains type and payload properties. The payload is where we set the details of our generic template in the following properties:

• template_type: Sets the type of template used for the message. We are using the generic template, so the value is 'generic'.
• elements: Sets the custom properties of our template. For the generic template we will specify a title, subtitle, image, and two postback buttons.

For our structured message, we will use the attachment_url that was sent to us as the image_url to display in our template, and include a couple postback buttons to allow the message recipient to respond. To construct the message payload and send the generic template, update handleMessage() to the following:

Our last step is to handle the messaging_postbacks webhook event that will be sent when the message recipient taps one of the postback buttons in our generic template.

What can I do with postbacks?

The postback button sends a messaging_postbacks webhook event to your webhook that includes a custom string of up to 1,000 character in the payload property. This allows you to easily implement different postback payloads that you can parse and respond to with specific behaviors.

Since our generic template allows the message recipient to choose from two postback buttons, we will respond based on the value of the payload property of the postback event. To do this, update your handlePostback() stub to the following: