Messenger Framework

Our Messenger Framework allows you to easily build apps that work directly in the Messenger.

Find an overview of the different types of apps in the Messenger through this link.


How the Messenger Framework works, at a high level

During the lifecycle of an app in the Messenger, Intercom and your web-service pass JSON objects back and forth that define an interaction for your user. In each step of this process, the objects you define are rendered by Intercom.

This could be a simple one-sided event like presenting some relevant information in your Messenger Home (like our Statuspage app). Your user can view this information in the Messenger without starting a conversation.

It could also be something more complex, with many variables being passed backwards and forwards between your user and your web-service. A good example of this is an app allowing your users to book a meeting:

  • You define which calendar the booking should be on.
  • Your user defines which time suits them.
  • You confirm the booking has been made.
  • Your user enters their email so you can send them a reminder.
  • You thank them for making the booking.

Learn more about the lifecycle of an app through this link.

The anatomy of an app

Check out the video below for terminology surrounding how you build apps in the Messenger with our Messenger Framework, alongside example screens of how to add and use apps.

Cards

A card is the containing element that defines the boundaries of an app. Every time a teammate selects an app and inserts an instance of it in a conversation, that’s a new card.

Canvases

You render each user step in an app is with a set of canvases. A canvas is a group of UI components that make up the interface of an app at a given point in time. You can change those UI components any time a user interacts with your app.

Read more on the detailed canvas reference page here.

UI Components

UI components are pre-designed and build UI elements you use to build your app’s interface. They are simple, clean, and automatically match the style of the Messenger where your app is being used, so all you have to do is define the content you want, and any actions that end users can take.

Take a look at all the available Components and Actions here.

Sheets

Sheets allow you to present a more customized UI experience to your users, by providing an iframe for you to embed an app or webpage within the entire Messenger window. This is a full-bleed experience where end users can interact with your UI and execute actions (e.g. signing up to a webinar or making a purchase) while still in the Messenger. It's perfect for when you need a larger area, or our UI Components don't suit what you need.

More about how to use Sheets during the flow can be found here.

Note

Sheets cannot exceed the size of the Messenger.

You can use both canvases and sheets within your app by:

  • Opening a sheet when users complete a submit action in your current canvas.
  • Returning to the same canvas, or to a new one when they close the sheet.

Here is an example app that opens a sheet with the user clicks the "View property" button.

Frames

Before you send a Messenger app to your users, you may need teammates to specify options or configure the app in some way. This can be achieved with frames.

A frame is rendered as an area of UI within the Intercom teammate-facing app environment (which can be the Inbox, Messages, or Messenger Home settings, depending on where the app is being used). This allows you to add interactive components for a guided approach to configuring the app, before sending it to your users or installing it in the Messenger home.

When do teammates interact with frames?

The configure flow is where you, as the developer of an app, specify what UI components will show to teammates. This only happens at the start, before the app gets 'initialized' and inserted into the Messenger. It is not possible to have an app in the Messenger go back and forth between teammate and user input.


What's Next

Now you have an understanding of how users and teammates can interact with apps in the Messenger, see how they work on a technical level.

App Lifecycle