CONTENTS

1. Overview
2. Configuring the Drawer Entry Point
3. Sharing
4. Getting the User ID & Thread Context
5. Permissions Management
6. Tips & Best Practices
7. FAQ & Troubleshooting

Overview

Interaction Model

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.

Potential Usecases

• Expression: Create stickers or memes right inside Messenger. Share songs, videos, or other content.
• Media: Send stories on topics you follow to the group as they happen.
• Commerce: Group ordering and planning
• Productivity: Send updates from task trackers, collaboratively edit a document.
• Entertainment: Create games or group challenges.

Configuring the Drawer Entry Point

To allow your bot to appear in the drawer for people who have added it, you must set its home URL.

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.

Learn More →

Sharing

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:

Sharing to the Current Thread

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.

Reacting to Shares

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 thesuccess 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.

Learn More →

Getting the User ID & Thread Context

Call the getContext() function to get:

• The user's ID (PSID)
• The thread ID
• The thread type

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.

Learn More →

Permissions Management

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 →

Tips + Best Practices

Messenger Platform has suggested best practices for how to make a great Chat Extension, including:

• General approach
• How to use different sharing modes
• How to control the webview chrome to maximum effect
• How to ensure backwards-compatibility

Learn More →

Design Kit

Ready to design your Chat Extension? Check out our handy Sketch file, containing all the components you need!

Get the Kit →

FAQ & Troubleshooting

Q: Do I have to have a bot to develop a Chat Extension?

A: Yes! Chat extensions are extensions of bots.

Q: What makes a Chat Extension appear in the composer drawer?

A: A chat extension appears in the composer drawer for a user after they have interacted with its associated bot.

Q: Do I have to have a Chat Extension to let users share from my bot?

A: No! Messenger Platform provides numerous other ways to let users share from your bot.

Q: Do I have to have a Chat Extension to use the webview and Messenger Extensions Javascript SDK in my bot? What is the connection?

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.

Q: When a recipient of a Chat Extension taps a link, which features are available via the the Messenger Extensions JavaScript SDK?

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.

Q: Does Chat Extensions work on Messenger.com and Facebook.com?

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.

Q: What's the difference between sharing to the current thread and sharing with broadcast?

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.

Q: I'm on the latest version of Messenger and the SDK is not working in the webview. What's wrong here?

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:

  • In your bot's menus.
  • In buttons in messages your bots send
  • In any messages shared via 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.

Q: I created a Chat Extension and I can't get it to show up in the composer drawer. How do I fix this?

Check the following:

1. 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.

2. 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.

3. Verify that the Facebook page the bot is attached to is published.

4. Verify that the bot itself is in public mode.

5. Verify that you have talked to the bot before.

6. The chat extensions shown in the composer drawer are cached. You may need to wait a short while for it to appear.