Best Practices for Chat Extensions
- Enabling social or collaborative experiences.
- Allowing people to share your content with their friends.
General Guidelines
Center your Chat Extension around an intent that users are likely to have mid-conversation. For instance, a user is less likely to reach for the chat extension to browse through recent or trending content to share than they are to have independently encountered that content elsewhere and decided to share. They might, however, open a chat extension to search for something that just came up in the conversation, or to see recently viewed content. Other examples of intent might be making a reservation or purchase, letting users express themselves, or collaborate in-thread on plans or lists.
Personalize the content and options shown to the sharer. Allow them to log in.
Use your bot's 1:1 experience to educate users on your Chat Extension.
Don't expect all participants to be familiar with your bot already.
Don't use the Chat Extension's home URL to link to an existing mobile website. Design something that belongs in Messenger, and make full use of the features available in the webview.
A Typical Flow
- A person (the "creator") opens Messenger's composer and selects your bot's Chat Extension.
- Messenger's webview appears, with your UI in it.
- In your webview UI the creator goes through some sort of flow that determines what they'll ultimately share into the thread.
- The creator clicks a Messenger "Send to Conversation" button in your UI:
- The chat extension closes, and the sent content appears as a template in the thread.
- Both creator and recipients can open the shared content. If appropriate, you can provide different views and capabilities for creator vs. recipients.
Best Practices for Sharing
Sharing: When To Use current_thread vs broadcast mode
When the bot's page is opened via the composer, it is almost always best to use current_thread mode. The user invoked your bot in the thread with the intent of sharing there, not somewhere else.
However, when participants in the thread open a piece of content shared, they may wish to share using broadcast mode, rather than back to the same thread they found it in.
Consistent Iconography
The Messenger Platform team has provided the following iconography for use on buttons that share content into a thread to make these actions clearer and more standardized across Chat Extensions experiences.
Note that the paper airplane icon is meant for sending to a thread via the composer (via "current_thread" mode); the other is meant for sharing from any other context (via "broadcast" mode).
They are available in a variety of formats and treatments that can be adjusted to match your design and branding.
Download
- Assets (PNG + SVG)- Sketch (requires Beta)
Sharing: Close After Sharing
If sharing a piece of content is intended as the final end of your flow (when the bot is invoked from the composer), it is best to close the webview via requestCloseBrowser() in the success callback for beginShareFlow(). You may wish to check whether the user actually shared or canceled.
Interaction Design
Page Title
Choose a clean page title that makes sense in Messenger. Avoid any SEO keywords or other clutter. If in doubt, the name of your bot should work fine.
If the user has navigated into a sub-page and is displaying a specific object (e.g. a video, a restaurant), consider showing just the name of that object in the <title>. But if you do this, adjust the design of the page to avoid redundancy with any other place the object's name may be desplayed.
Navigation & Redirects
Avoid re-directing the user immediately when they open the bot from the composer or by clicking a link. This will cause the bot's icon to disappear from the webview header bar and be replaced with a back button.
As Messenger's webview shows the back button in the upper-left, users will expect it to work as it does in mobile apps. That is to say, it reflects hierarchy rather than history.
For instance, if you have a multi-step order process spanning multiple pages, the "back" button should not go to the previous step in the process. Rather, users may expect it to back out of the order.
Backwards-Compatibility
Specify a fallback_url for any links in shared content for users on old versions of Messenger or desktop clients.
If you share content from your bot with a link or CTA that depends on the recipient using Messenger Extensions, specify a fallback_url with an error message. Messenger will open this URL in cases where the client is not able to use Messenger Extensions.
Use getSupportedFeatures() to check for functionality before you use it.
The getSupportedFeatures() function lets you see which features the client supports. This may be particularly important for the recipients of the content, who may not have upgraded to the latest version.
Test on Desktop
As of Messenger Platform v2.1, content shared from Chat Extensions can open for desktop users. This means the JS APIs will also work here. Be sure to test in both environments to ensure a consistent experience for your users.
Other Considerations
Network Usage
The initial page displayed when the user invokes your bot from the composer should load quickly on a variety of network conditions.
For this reason, the Messenger Platform team recommends a total size (including all resources) of below 250KB for the initial page.
There are many browser plugins and services that can help you measure and optimize your Chat Extensions' network usage.
Hide the Native Share Button When Your Bot Is Opened From the Composer
The Messenger webview allows developers to specify whether they want a share button displayed in the header. It is shown by default. In many places, it provides a clean, consistent way to let users share your content without any extra work on your part.
This behavior is controlled via the webview_share_button attribute, which is settable in buttons, menu items, and in the settings that control what is seen when a user taps your bot in the composer drawer.
In the context of the composer drawer, for most bots, it is preferable in most cases to set webview_share_button to "hide".
This is because messages that are produced via this share button cannot be directly controlled via the developer, will not include any CTA, and may not open with Messenger Extensions enabled for the recipient. If you are already directing the user towards other sharing functionality, having two ways to share may be redundant and confusing.