Chat Extensions appear in the composer drawer in Messenger once a user has interacted with the associated bot.
When the user taps the chat extension's icon, it opens a webview-based UI specified by the developer. The user can then create or select content to be shared into the thread. The message shared into the thread can contain images, links, and more.
When users in the group interact with any messages shared in this manner, the developer will have access to context info on the thread, ability to ask for permissions, and everything else provided in the Messenger Extensions JavaScript SDK.
We have open-sourced TaskBot, a bot that showcasing all of the features described here.
To allow your bot to appear in the drawer for people who have added it, you must set its home URL.
To display a webpage with the Messenger Extensions SDK enabled in the Messenger webview you must whitelist the domain, including sub-domain, in the whitelisted_domains property of your bot's Messenger Profile. This ensures that only trusted domains have access to user information available via SDK functions.
For more information on whitelisting domains, see the whitelisted_domains reference.
If your chat extension is not ready to launch, please take care to set in_test to true to prevent it from showing up for non-developers until it's ready.
Messenger Platform supports custom sharing from the webview, letting developers provide a custom message and destination for messages shared from their bot.
Several enhancements were added to these features to allow them to work with Chat Extensions. Here's what you should know:
The beginShareFlow() function has a mode parameter which now supports current_thread mode. This allows the user to share to the thread they invoked the Chat Extension from, rather than having to select another thread. Most developers should choose current_thread mode for inside the extension itself.
There may be situations where you wish to check whether this mode is supported by the user's version of Messenger. Use the getSupportedFeatures() method and check for the key "sharing_direct" to be sure.
The success callback for beginShareFlow() is called regardless of whether the user confirms the share or cancels, as long as no error was encountered.
Messenger now passes is_sent field in the response to the success callback telling you whether a message was actually sent.
After the user has shared, it's a good idea to close the window if you're done, or direct the user to the next part of the flow.
<script>
var messageToShare = { ... };
MessengerExtensions.beginShareFlow(function success(response) {
if(response.is_sent === true){
// User shared. We're done here!
MessengerExtensions.requestCloseBrowser();
}
else{
// User canceled their share!
}
},
function error(errorCode, errorMessage) {
// An error occurred trying to share!
},
messageToShare,
"current_thread");
</script>Refer to the documentation for beginShareFlow() for more specifics.
Call the getContext() function to get:
This function works for all users encountering the webview, regardless of whether they have a thread open with your bot.
You might use this information to build social, collaborative features (as in the above Todo example) using the webview features.
Note that getting the user ID in this way does not imply being able to get the user's profile. For that, you will need profile permission.
When a user begins a thread with your bot, you will automatically have permission to message that user as well as get their profile. These are revoked for users who block the bot or delete the thread.
For users who encounter your bot via the webview and have not begun a thread with it, you may wish to ask for these permissions. For this, you can use the permissions functions in the Messenger Extensions JavaScript SDK.
Learn More →Your bot is going to appear in drawer once user clicks get started button or opens a webview (in 1:1 thread or in a group thread) that has Messenger extension enabled and home_url is set for that bot.
If user deletes or blocks a bot then bot will be out from the drawer.
User will see a red dot (badge near composer + icon) when bot appears in drawer.
Messenger Platform has suggested best practices for how to make a great Chat Extension, including:
Ready to design your Chat Extension? Check out our handy Sketch file, containing all the components you need!
Get the Kit →A: Yes! Chat extensions are extensions of bots.
A: A chat extension appears in the composer drawer for a user after they have interacted with its associated bot.
A: No! Messenger Platform provides numerous other ways to let users share from your bot.
A: No! We just like that word. In fact, webviews can be invoked in many ways beyond Chat Extensions, and all of them allow the use of Messenger Extensions.
A: All of the features that were available to the sender are available to users opening the shared content. You can get the user ID, thread context, initiate your own shares, and much more. Note that in these situations, you will not have access to the user profile or to message those users until you ask for the requisite permission.
A: This feature is supported on iOS and Android only. Users on web-based clients may be able to click links shared by Chat Extensions users, but will not be able to use the functionality provided by the JavaScript SDK. For more info, see "Backwards Compatibility" in the Chat Extensions Best Practices Guide.
A: Chat Extensions builds on the webview sharing features launched earlier by adding a flow called "current_thread".
If a user has invoked your bot within a thread using the composer, it only makes sense that they would want to share there, rather than to someone else. So with the "current_thread" flow, the user can confirm sending a piece of content to the current thread, rather than broadcasting to multiple threads.
A: Check the following:
Unpublished page: If the page your bot is attached to is unpublished, the SDK will not load for the users who don't have any role (e.g. developer, admin) on your page. Add the user to the page or publish the page.
messenger_extension property not set: Make sure that, in any place the webview is opened from, that you are setting messenger_extensions to true. This includes:
beginShareFlow() and Share buttons. Domain is not on whitelist: Add the domain the page is hosted on to your bot's domain whitelist.
See more webview troubleshooting tips.
Check the following:
Verify that you've set the home_url for the specific page that you want to appear, using the proper Page Access Token for that page. Transferring a bot from one Facebook page to another will not transfer the home URL.
If you have set the in_test attribute to true while in development mode, verify that the person checking the drawer is a developer or tester of the bot in question, or a manager of its Facebook page. If you have released the bot publically, verify that you have submitted it and had it approved for the pages_messaging permission. If your extension is in in_test mode then it's not going to show up in non developer or non tester account.
Verify that the Facebook page the bot is attached to is published.
Verify that the bot itself is in public mode.
Verify that you have talked to the bot before.
The chat extensions shown in the composer drawer are cached. You may need to wait a short while for it to appear.