Integration Components

The Messenger Platform is comprised of a set of features intended to give you everything you need to create awesome, interactive experiences in Messenger, including APIs, web plug-ins, and a full webview. This is intended to be an overview of the core platform components that are available to help you better understand the Platform.

Available Platform Components

Page-scoped ID (PSID)

Every time a person starts a conversation with your Messenger bot, the Messenger Platform will assign them a page-scoped ID, commonly referred to as a PSID. This ID is unique to your Facebook Page, and cannot be used with any other Facebook Page. In other words, a person will have different PSIDs for each Messenger bot they are in conversation with. This ensures that a person can only be sent messages by bots they have chosen to start conversations with.

Whenever you send a message to a person, you will include their PSID in the recipient.id property of the request to identify who should receive the message. Likewise, any time a person takes an action in a conversation, such as tapping a button or sending a message, their PSID will be included in the sender.id property of the webhook event, so that your bot can identify who took the action.

APIs

The Messenger Platform provides a set of REST APIs that give you the tools you need to create awesome Messenger experiences. From sending rich messages, to finding your existing customers on Messenger, to customizing your bot and more, our APIs are the primary way you will work with the Messenger Platform.

Send API

The Send API is your primary integration point with the Messenger Platform. This API allows you to send simple text and structured template messages, as well assets like images, videos, audio, and files. The Send API also supports additional message types and features that give you flexibility in building your Messenger experience, including quick replies and sender actions.

Learn More →Send API Reference →

Attachment Upload API

The Attachment Upload API gives you the ability to upload your assets to the Messenger Platform. Any type of asset can be uploaded from a URL or your local file system, including images, audio, videos, and files.

Using this API makes your assets reusable, removing the overhead of repeatedly uploading an asset each time it is sent. This makes message sends faster, less bandwidth intensive, and more efficient. Once an asset is uploaded, the Attachment Upload API will return an attachment_id that can be used for future requests.

Learn More →Attachment Upload API Reference →

ID Matching API

It is a common case that a person will interact with multiple Facebook Pages and apps that you own. This can create a problem, however, since they will have a different ID for each Page and app they interact with. To give you the ability to create a unified experience, the ID Matching API lets your retrieve a person's page-scoped and app-scoped IDs across all your apps and Pages, using a single PSID or ASID for that person.

Learn More →ID Matching API Reference →

Handover Protocol API

The handover protocol lets you pass control of a conversation between multiple Facebook apps, as well as the Page inbox. This gives you the ability to componentize how your Messenger experience is built, by allowing you to build multiple specialized bots to handle separate aspects of a conversation, rather than a single monolithic app, which can quickly become complicated and difficult to manage. This also makes it much easier to reuse apps to support conversations across multiple Pages. In addition, the ability to pass control to the Page inbox allows you to switch the conversation to live chat at any time.

Learn More →Handover Protocol API Reference →

Messenger Code API

Messenger Codes are a great way to advertise your Messenger bot, and an easy way for people to start a new conversation with you. Plus they look pretty cool, too!

Every Facebook Page comes with a Messenger Code that can be generated programmatically via the Messenger Code API. In addition, the API lets you generate parametric Messenger codes that contain a custom ref property that is sent to your webhook in a webhook event when the Code is scanned. This is useful for many purposes, such as tying new conversations to ad campaigns and events.

Learn More →Messenger Code API Reference →

Messaging Insights API

The Messaging Insights API lets you programatically retrieve the same information that appears in the Page Insights tab of your Facebook Page. This includes metrics related to conversations, such as number of conversations, responsiveness, block rate, and more. Other analytics data and tooling, such as custom events is also available thanks to Facebook Analytics.

Learn More →Messaging Insights API Reference →

Customer Matching API

Chances are you already have customers, but how do you find them on Messenger? With the Customer Matching API, you provide a phone number and optionally a name, and the Messenger Platform returns whether a matching person is using Messenger. If we find a match, you will be able to use the person's phone number to start a new conversation with them. Once they respond, you will receive a PSID that you can use to continue the conversation.

Learn More →Customer Matching API Reference →

Messenger Profile API

The Messenger Profile API is used to set, update, and delete a number of settings for your Messenger bot, including settings for payments, whitelisted domains, the persistent menu, the welcome screen, and more.

Messenger Profile API Reference →

Webhook

The Messenger Platform sends an event to your webhook whenever an action occurs in a conversation with your bot. Your webhook is a single HTTPS endpoint (usually /webhook) exposed by you that accepts POST requests. This is where your bot processes and responds to all incoming webhook events.

The Messenger Platform supports a standard set of webhook events that you may subscribe your webhook to during the setup process. At a minimum, you should subscribe to the messages and messaging_postbacks webhook events to be able to implement basic Platform features in your bot.

Webhook →Webhook Events Reference →

Messenger Webview

The Messenger webview is a standard webview that can be opened inside the Messenger app on mobile and web clients. The webview allows you to offer experiences and features that require a more complex user interface that might be difficult to create in-conversation, such as picking seats to book, or browsing available dates. Since this is a normal webview that loads pages from the web, you have the full flexibility to create rich experiences that extend your Messenger bot with all of your favorite web development frameworks, tools, and libraries.

Learn More →

Messenger Extensions JS SDK

The Messenger Extensions SDK provides access to core Messenger information and features inside the Messenger webview. For example, the getContext() provides information about the conversation, such as the PSID and profile of the person who opened the webview, beginShareFlow() allows you to share content from the webview back into the thread, and PaymentRequest allows you to accept payments.

Learn More →Messenger Extensions SDK Reference →

Chat Extensions

Chat Extensions are a powerful feature of the Messenger Platform that allow you to create shared and collaborative Messenger experiences that people can bring right into conversations with their friends, family, and coworkers. Unlike most Messenger interactions, which take place directly between a person and your bot as a conversation, Chat Extensions allow you to use the Messenger webview to create experiences that can be invoked in any conversation. For example, a shopping list Chat Extension might allow multiple people in a conversation to update a shared list.

Anytime a person starts a conversation with your Messenger bot, your Chat Extension will automatically appear in Messenger's composer drawer, and can then be invoked by them in any conversation.

Learn More →

Built-in Natural Language Processing

The Messenger Platform's built-in natural language processing (NLP) feature brings the powerful Wit.ai natural language platform directly to your Messenger bots, allowing you to detect intent and meaning in messages sent to your bot. With built-in NLP, you can enable Wit's many pre-existing entity types, which have been trained to parse common conversational elements, like datetime, search queries, distance, greetings and more, or you can create your own entities and train Wit by example to recognize natural language structures specific to your bot. With built-in NLP enabled, the Messenger Platform automatically returns Wit's analysis to your webhook with every message.

Learn More →Wit.ai Docs →

Web Plug-ins

The Messenger Platform supports a set of plug-ins that make it simple for a person to start a conversation with your Messenger bot from the web. Web plug-ins work by integrating standardized elements into your site, such as buttons, that automatically open a conversation with your bot in messenger.com or the Messenger app. Your bot will receive a webhook event anytime a new conversation is started from a plug-in. You may also pass custom data to the plug-in, such as user information and where they were referred from.

Send to Messenger Plug-in →Checkbox Plug-in →Message Us Plug-in →