Setting Up The Welcome Screen

The welcome screen of your Messenger experience is often the first thing people see. It displays the name, the profile picture and cover photo from your Facebook Page, how responsive your bot is, an optional greeting message, and the ‘get started’ button. It’s an opportunity to set expectations and help people have a positive experience with your bot.

This tutorial covers how to set up and use your welcome screen to effectively introduce people to your Messenger experience.


In this tutorial, we will:

  • Add an image to represent you Messenger experience.
  • Set the get started button postback.
  • Set the greeting text.
  • Set up a webhook using Node.js and express that parses incoming messaging_postbacks and responds appropriately.
  • Set up the welcome message viewed by the user after clicking ‘Get Started.’

What you need

Messenger Features

  • Webhook: The Messenger Platform sends events to your webhook to notify your bot when interactions or events happen.
  • Welcome Screen: Allows you to customize the first steps a user has with your bot.
  • Button Template:Sends a text message with up to three attached buttons.
  • Postback Button: Triggers arbitrary functions with a messaging_postbacks event when a user taps the button.
  • Call Button: Dials a phone number when tapped.


  • Completed the general set up:
  • Built a bot for Messenger. You can do so quickly using the Quick Start guide.
  • Have a server with Node.js installed.

Repository with working code

You can find the final code here.

How doees it work? Step-by-step

STEP 1: Download the starter project

We’ve created a starter project that has the project structure set up for you. If you want to skip ahead, you can find the completed project here.

STEP 2: Install dependencies

To begin, you need to install some Node module dependencies. This tutorial uses Express to set up a web server for the webhook, the body-parser module to parse the JSON body of the incoming POST requests, and the Request module to send HTTP requests to the Messenger Platform. Issue this command in your terminal:

cd node
npm install

Also, add your authentication information to the node/config/default.json file.

STEP 3: Set the icon for your welcome screen

Setting a recognizable icon on your welcome screen helps people know they are in the right place. As your bot is attached to your Facebook Page, Messenger pulls the profile picture and cover photo from there. To change your welcome screen icon, you need to change your Page profile picture.

Example of setting cover photo for Messenger bot Facebook Page

STEP 4: Edit Page Subscription FIelds

By default, your app only receives message events, but as this bot also needs to receive messaging_postbacks events, you need to enable that feature.

  • In your App settings, got to the Messenger > Settings.
  • Under Webhooks, click edit event’ and enable messaging_postbacks.
Example of enabling messaging_postbacks in Messenger settings

STEP 5: Set the Get Started button postback.

Requirement: to set the button, you must have the Administrator role for the Facebook Page associated with the bot.

When a user taps the get started button, your webhook receives a messaging_postbacks event that contains a string specified by you in the get_started property of your bot’s Messenger profile.

This postback should be used to trigger your initial welcome message, such as a set of quick replies, or a text message that welcomes the person. To set the postback payload, send a POST request to the Messenger Profile API:

curl -X POST -H "Content-Type: application/json" -d '{
  "get_started": {"payload": "<postback_payload>"}

If successful, the API endpoint will return a success response.

	"success": true

If unsuccessful, the endpoint returns an error message with more details.

STEP 6: Set the greeting text

The greeting message on the welcome screen is optional but is useful to let people know why they should start a conversation with your bot. To set the greeting text, send a POST request to the Messenger Profile API.

curl -X POST -H "Content-Type: application/json" -d '{
  "greeting": [
      "text":"Welcome to the Bot Hotel, I am here to help with all your questions."


If successful, the API endpoint will return a success response

	"success": true

If unsuccessful, a relevant error message will be returned.

STEP 7: personalize and internationalize the greeting text

You can personalize the greeting text using the person’s name and locale. To use a name, you can use these template strings:

  • {{user_first_name}}
  • {{user_last_name}}
  • {{user_full_name}}

All supported locales can be found here.

curl -X POST -H "Content-Type: application/json" -d '{
  "greeting": [
      "text":"Welcome to the Bot Hotel {{user_full_name}}, I am here to help with all your questions."
    }, {
      "text":"Bienvenue au Bot Hotel {{user_full_name}}, Je suis à votre disposition pour toute question."
    }, {
      "text":"Willkommen im Bot Hotel {{user_full_name}}, ich bin hier, um Ihnen bei all Ihren Fragen zu helfen."
Example of a Messenger bot Welcome Screen

STEP 8: tips for a good greeting text

  • Do consider your greeting an introduction and a summary of your experience. Greetings have a 160 character maximum, so keep it concise.
  • Do communicate your main functionality. Context helps people understand how to interact with you and sets expectations about your capabilities.
  • Don’t treat your greeting like an instructional manual. Because your greeting disappears, use your actual messages to introduce specific functionality and commands.
  • Don’t use excessive text formatting (ex: spacing, punctuation, returns) in your greeting so you can make the most of the character limit.

STEP 9: Handle The Get Started Button Postback

Once someone clicks the Get Started button, the postback payload is issued to you webhook, which needs to handle it.

In the starter code, the receivedPostback function handles messaging_postbacks and we’ll add the code to handle the get_started payload inside the switch (payload) {} statement:

switch (payload) {
    case 'get_started':

        sendTextMessage(senderID, "Postback called");

Policy: by clicking on the Get Started button, a person opts-in to receiving messages from you. As stated in the ’24 + 1 policy’, you have up to 24 hours to respond. You may also send one additional message after the 24-hour time limit has expired. Find more information here.

STEP 10: Respond to incoming message_postbacks

There are several message templates you can use to structure your response and communicate specific actions people can take. Here, the sendGetStarted function sends a response using the button message template.

function sendGetStarted(recipientId) {
  var messageData = {
    recipient: {
      id: recipientId
    message: {
      attachment: {
        type: "template",
        payload: {
          template_type: "button",
          text: "Welcome to the Bot Hotel, I can help with any of the three requests below.",
              type: "postback",
              title: "Check in",
              payload: "check_in"
          }, {
            type: "postback",
            title: "Room Service",
            payload: "room_service"
          }, {
            type: "phone_number",
            title: "Call Reception",
            payload: "+16505551234"


The message contains a short text and three buttons:

You can find all the button types you can use to invoke different actions here.

Example of button types to interact with Messenger bot

STEP 11: Polish your welcome message

TThe first message people receive from your bot is an opportunity to teach people how to navigate the experience. It should set expectations and communicate basic commands people can take. To do so effectively:

  • Use keyword or terms people can use to ask for help, get updates, etc., so they find what they want more quickly.
  • Embrace structure to disambiguate tasks people can take using message templates, the persistent menu or quick replies.
  • Don’t be too generic. Try addressing people by name to make the message feel personal. You can also use the User Profile API to retrieve profile information to personalize the experience further.


And with that, you have a ‘getting started’ experience that welcomes people to your bot and sets some initial expectations for what they can achieve with it. Planning these initial steps helps make a lasting first impression for your bot of your bot and ensures they return and re-engage.