Conversation

To create rich experiences on Messenger we provide different ways to start and engage people in conversations.

When a person first finds your bot you can set the Greeting Text and an initial message to send once someone taps the Get Started button.

Thread Setup

The Messenger platform gives you a number of different tools to help configure the experience people have with your bot.

View the Thread settings reference guide

Welcome Screen

The Welcome Screen is the first thing people see when they start a new conversation with your bot. The name, description, profile pic and cover photo are pulled from your Page.

Greeting Text can be used as introductory text to help explain what your bot does. If you set the Greeting Text, it will be used instead of the page description.

The Get Started button enables you to start a conversation with messages. Your first messages should help people start their user journey.

The Welcome Screen and Get Started button only appear for new conversations.

Persistent Menu

The persistent menu can be set by your bot, to help people discover and more easily access your functionality throughout the conversation.

The Persistent Menu is always available to the user. This menu should contain top-level actions that users can enact at any point. Having a persistent menu easily communicates the basic capabilities of your bot for first-time and returning users. The menu will automatically appear in a thread if the person has been away for a certain period of time and returns.

Read about the Persistent Menu

Send a Message

The Messenger Platform supports sending several different types of messages. You can send text, images, video, audio and files. We've also created Structured Messages which have several templates including buttons and horizontal lists.

Text Messages

You can send text messages in your conversation.

Rich Media Messages

We also support sending Image, Video, Audio and Files. These message attachments can either be uploaded directly or you can send us a url link to them.

If you're repeatedly sending the same media files, you can optimize your calls by reusing attachments with the Send API.

Send a Image Message

You can send images by uploading them or by providing a URL. Supported formats are jpg, png and gif.

Please see the Send - Image reference for more details.

Send a Video Message

You can send videos by uploading them or by providing a URL.

Please see the Video reference for more details.

Send a Audio Message

You can send sounds by uploading them or by providing a URL.

Please see the Audio reference for more details.

Send a File Message

You can send files by uploading them or sharing a URL.

Please see the File reference for more details.

Structured Messages

Structured Messages are templates that support different kinds of use cases. The Button Template allows you to send text and buttons. The Generic Template allows you to define an image, title, subtitle and buttons.

The Generic Template supports multiple bubbles in one message and renders them as a carousel.

Buttons

These templates can have different kinds of buttons:

Share Button

The Share Button opens a native share dialog in Messenger and allows people to share a message bubble with their friends.

Buy Button

The Buy Button opens a native checkout dialog and allows people to share their credentials with merchants to make purchases.

Webview and Messenger Extensions

With the Webview, you can control the display height of the in-app browser window, enabling you to create experiences that look and feel like part of the Messenger Thread.

You can also use the Messenger Extensions Javascript SDK to tightly integrate a thread with the page rendered in a Webview. Extensions allow you to get the user ID so that you can create a personalized experience. You can close the webview.

With Extensions, you can also support a payments experience by opening a native checkout dialog and obtaining payment credentials from people.

Quick Replies

Quick Replies provide a different way to present buttons to the user. Quick Replies appear prominently above the composer, with the keyboard less prominent. When a button is tapped, the message is sent in the conversation.

Once a Quick Reply is tapped, the buttons are dismissed preventing the issue where users could tap on buttons attached to old messages in a conversation.

Please consider using Quick Replies when you're asking someone to choose from up-to five choices. You may also add an image to a Quick Reply. We've also created a special Quick Reply that will prompt a person for their location.

Please see the Quick Replies reference for more details.

Receipt Template

For commerce experiences, we've created a Receipt Template. This template allows you to send a richly-formatted receipt in Messenger.

Airline Templates

For the airline industry we have developed specialized templates for sending people their itinerary, Checkin reminders, their boarding pass and flight status updates.

Please refer to the reference docs for more details:

Receive Messages

Whenever someone interacts with your bot or sends you a message we will send you an update via your Webhook integration.

The response will always contain a recipient_id and a message_id. In most cases the recipient_id will be a unique user identifier representing the user. You should store this information for each user. This ID can be used with the Send API to send messages to this user.

When representing a user, these IDs are page-scoped IDs (PSID). This means that the IDs of users are unique for a given page.

If you have an existing Facebook Login integration, user IDs are app-scoped and will not work with the Messenger platform.

Read the Webhook Reference to get more details on the response types.

Message Received callback

The Message received callback is sent when a person sends your bot a message. You must have subscribed to the messages event when you setup your webhook.

Please read the Message Received reference for more details.

Postback Received callback

The Postback Received callback is sent when a person clicks on a button that has been configured to send you a postback. In order to get a callback from a postback, you have to have subscribed to the messaging_postbacks event when you setup your webhook

Please read the Postback Received reference for more details.

Message Delivered callback

This callback will occur when a message a page has sent has been delivered. You must have subscribed to the message_deliveries event when you setup your webhook.

Please read the Message Delivered reference for more details.

Authentication callback

This callback will occur when the Send-to-Messenger plugin has been tapped. You must have subscribed to the messaging_optins event when you setup your webhook.

Please read the Opt-in Callback reference for more details.

Message Read callback

This callback will occur when a message a page has sent has been read by the user. You must have subscribed to the message_reads event when you setup your webhook.

Please read the Message Read reference for more details.

Message Echo callback

This callback will occur when a message has been sent by your page. You may receive text messsages or messages with attachments (image, video, audio, template or fallback). You must have subscribed to the message_echoes event when you setup your webhook.

Please read the Message Echo reference for more details.

Checkout Update callback (BETA)

This callback will occur when using the Buy Button with a flexible-amount transaction. This allows you to update pricing based on a person's shipping address. You must have subscribed to the messaging_checkout_updates event when you setup your webhook.

Please read the Checkout Update reference for more details.

Payment callback (BETA)

This callback will occur when a person taps the pay button from the checkout dialog rendered by the Buy Button. You must have subscribed to the messaging_payments event when you setup your webhook.

Please read the Payment reference for more details.

Sender Actions

If you are processing a request and can't send an immediate response to a user, you can set the typing indicator or send a read receipt, keeping the conversations lively and the user engaged.

Please see the Sender Actions reference for more details.

Personalize the experience

You can personalize your bot experience for each person by calling the User Profile api. Consider using their name to tailor messages to each person, their locale to pick the right language or their timezone to suggest a time of day when they would like to receive updates from your bot.