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.
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
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.
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.
You can send text messages in your conversation.
- Please refer to the Send - Text Message reference for more details.
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 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.
These templates can have different kinds of buttons:
- URL button: Open a URL in the in-app browser
- Postback button: Send a postback to your webhook when you want to send an action to your bot
- Call button: Call a phone number
- Share button: Open a share dialog so that messages can be shared with friends
- Buy button: Open a checkout dialog for purchases
The Share Button opens a native share dialog in Messenger and allows people to share a message bubble with their friends.
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.
With Extensions, you can also support a payments experience by opening a native checkout dialog and obtaining payment credentials from people.
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.
For commerce experiences, we've created a Receipt Template. This template allows you to send a richly-formatted receipt in Messenger.
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:
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.
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.
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.