AR for Messenger Platform (beta)

Closed Beta

AR camera effects for Messenger is currently in closed beta, and not available for general use.

Join the Waitlist →

Augmented Reality (AR) camera effects can be added to a bot to engage users in new and interactive ways. This feature is currently in closed beta.

A bot can use this feature by using templates and quick replies that can open the camera. When people tap on it, the camera will open with AR effects specific to the brand. Depending on the experience, people can take a photo or record a video that incorporates AR camera effects into the photo/video. From there they can save the photo/video, share it in a group or 1:1 conversation, or add it to their Story.

There are a variety of ways that camera effects can help you accomplish your business outcome by enhancing your current Messenger experience; such as virtual try-on, customizing products, or simply as a way to give your biggest fans a way to express themselves.

Contents

Best Practices for Creating Camera Effects Assets

Your partner manager and partner engineer will provide you with a best practices document. You may also view the AR Studio documentation.

Delivering Camera Effects Assets

Once an effect is arranged and provides the desired look, you must ensure all camera effects assets meet the following requirements:

  • Downloadable file size: The maximum downloadable file size for effects is 2MB
  • Uncompressed file size: The maximum file size once an effect is uncompressed it 20MB

To view how large your effect will be, go to View > Show Asset Summary in AR Studio.

This window will give you a breakdown of the size of each asset RAW, the download size, and the size of the effect on device. If your file size is over one of the above limits, this information will allow you to determine which assets are the cause. Alternatively, you can also choose File > EXPORT… from the menu bar to get a quick look at whether the effect meets our limits.

Once you've verified file size and exported successfully, you may submit the files to your partner manager.

Implementing Camera Effects

The title for the “open_camera” button should not be specific to a message or effect. The button title will be reused when the user tries on an effect and shares it, so the title has to be compatible with all effects.

Message Templates

The Messenger Platform's structured message templates allow you to make camera effects available as a CTA button in any template message your bot sends to a user.

{
  "type":"branded_camera",
  "title":"<CTA_TITLE>",
  "camera_metadata": {
    "content_id":"<OPTIONAL-DEFAULT-CAMERA-EFFECT-ID>"
  }
}

Quick Replies

Quick replies act as a nice guiding mechanism for people when they land in your experience, and are especially effective if your bot experience offers a wide variety of functionality.

{
  "content_type":"branded_camera",
  "title": "<quick reply title text>",
  "data": {
    "camera_content_id": "<OPTIONAL-DEFAULT-CAMERA-EFFECT-ID>"
  }
}

Persistent Menu

You may also configure the persistent menu for your bot to include a button that opens the camera effects by adding a call to action with type branded_camera.

{
  "persistent_menu":[
    {
      "locale":"default",
      "composer_input_disabled": false,
      "call_to_actions":[
        {
           "type":"branded_camera",
           "title":"<BUTTON TEXT>"
        }
      ]
    }
  ]
}

Webhook Events

Three webhook events related to camera effects can be sent by the Messenger Platform:

  • Camera Dismiss Event: The branded_camera webhook event is sent when a user dismisses the camera and returns to your bot.
  • New User Event: The messaging_postbacks webhook event is sent when a new user enters your bot from a branded camera share.
  • Existing User Event: The messaging_referrals event is sent when an existing user of your bot opens an existing thread from a branded camera share.

Camera Dismiss Event

The Messenger Platform will deliver a branded_camera webhook event when a person dismisses the camera and returns to your bot.

To receive this event, you must subscribe to it by selecting the branded_camera field when setting up your webhook.

{ 
  "sender": {
    "id": "<PSID>"
  },
  "recipient": {
    "id": "<PAGE_ID>"
  },
  "timestamp": 1469111400000,
  "branded_camera": { 
     "content_ids": [<CAMERA-EFFECT-ID>, <CAMERA-EFFECT-ID>, ...],
     "event": "dismiss"
  }
}

The branded_camera.content_ids property of the webhook event will contain an array of all the camera effect IDs the user interacted with while the camera was open. If the user did not interact with any camera effects, the array will be empty.

New User Event

When a new user opens a chat with your bot from shared camera effects content, and clicks the get started button, the Messenger Platform will send your webhook a messaging_postbacks event with the referral property:

{
  "sender":{
    "id":"<PSID>"
  },
  "recipient":{
    "id":"<PAGE_ID>"
  },
  "timestamp":1458692752478,
  "postback":{
    "payload":"<USER_DEFINED_PAYLOAD>",
    "referral": { 
      "source": 'BRANDED_CAMERA', 
      "type": 'OPEN_THREAD',
      "source_id": '<CAMERA-EFFECT-ID>'
    }
  }
}

In the referral property, source will always be set to BRANDED_CAMERA and source_id will be the ID of the camera effect that referred the user.

Existing User Event

When an existing user of your bot returns to the chat from a camera effects share, the Messenger Platform will send your webhook a messaging_referrals webhook event:

{
  "sender":{
    "id":"<PSID>"
  },
  "recipient":{
    "id":"<PAGE_ID>"
  },
  "timestamp":1458692752478,
  "referral": {
    "source_id": '<CAMERA-EFFECT-ID>',
    "source": "BRANDED_CAMERA",
    "type": "OPEN_THREAD",
  }
}

In the referral property, source will always be set to BRANDED_CAMERA and source_id will be the ID of the camera effect that referred the user.

Discovery

The camera effects CTA button is also supported in Click-to-Messenger Ads, and can be used to guide users to try out your branded camera experience.

To include the camera effects CTA button in a Click-to-Messenger ad, do the following:

  1. Set up a Click-to-Messenger ad in the Ads Manager.
  2. In the ads manager, click the JSON tab, and manually input JSON for a message with a camera effects button in the following format:
{
  "message": {
    "attachment": {
      "type": "template",
      "payload": {
        "template_type": "generic",
        "elements": [
          {
            "title": "<TITLE_TEXT>",
            "image_url": "<IMAGE_URL_TO_DISPLAY>",
            "subtitle": "<SUBTITLE_TEXT>",
            "buttons": [
              {
                "type": "branded_camera",
                "title": "<BUTTON_TEXT>",
                "camera_metadata": {
                  "content_id": "<OPTIONAL-CAMERA-EFFECT-ID>"
                }
              }
            ]
          }
        ]
      }
    }
  },
  "user_edit": true
}