Messenger Platform
 
 
 

Chat Extension Home URL

This field allows your bot to enable a Chat Extension in the composer drawer in Messenger. It controls what the user sees when your bot's chat extension is invoked via the composer drawer in Messenger.

The URL specified here is for Chat Extensions only. The webapp at the URL you specify should use the APIs available in the webview to implement useful functionality for your bot's users.

This field is not a place to put your bot or company's homepage.

To set it, call the Messenger Profile API with the home_url field:

Contents

  1. Setting the Home URL
  2. Reading the Home URL
  3. Deleting the Home URL

Setting the Home URL

The domain of the URL you specify here should be whitelisted for it to work correctly.

curl -X POST -H "Content-Type: application/json" -d '{
  "home_url" : {
     "url": "http://petershats.com/send-a-hat",
     "webview_height_ratio": "tall",
     "in_test":true
  }
}' "https://graph.facebook.com/v2.6/me/messenger_profile?access_token=YOUR_ACCESS_TOKEN_HERE"

Parameters

Parameter Description Type Required

url

The URL to be invoked from drawer. Must be whitelisted. The URL must be on https. We don't support non-https protocol.

String

Yes

webview_height_ratio

Controls the height of webview. Only allowed value is tall.

String

Yes

webview_share_button

Controls whether the share button in the webview is enabled. Either show or hide, defaults to "hide".

String

No

in_test

Controls whether public users (not assigned to the bot or its Facebook page) can see the Chat Extension.

This should be set to true until the Chat Extension is ready to be used by others.

Boolean

Yes

Response

If your home URL was set successfully, you will get back the following response:

{
  "result":"success"
}

Reading the Home URL

In order to get the home URL you set previously, send a GET request:

curl -X GET "https://graph.facebook.com/v2.6/me/messenger_profile?fields=home_url&access_token=PAGE_ACCESS_TOKEN"

Deleting the Home URL

In order to remove the Home URL from your bot (and thus Chat Extension capabilities), send a DELETE request:

curl -X DELETE -H "Content-Type: application/json" -d '{
  "fields":[
    "home_url"
  ]
}' "https://graph.facebook.com/v2.6/me/messenger_profile?access_token=PAGE_ACCESS_TOKEN"

Once deleted, the bot will not be visible in the list shown to Messenger users in the composer.

Conditions to show your bot in composer drawer

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

  2. If user deletes or blocks a bot then bot will be out from the drawer.

  3. User will see a red dot (badge near composer + icon) when bot appears in drawer.

  4. We move good quality chat extension bots to featured list and it's going to appear in user's drawer (even though user has never interacted with the bot.) You don't need to worry about this we regularly update this list.