Welcome to the reference for building Apps. These pages focus on Apps in Messenger for now but will expand to include new types of apps in the future.

Layout of this reference

This reference covers two large topics:

  1. Objects
  2. Components

Objects

During the individual cycles, you will receive or send payloads which will include objects. These will either need to be:

  • Accessed in order to get data about the input or conversation that triggered the cycle.
  • Created to send back to Intercom as part of your response, initiating the next step in the cycle.

More information on the app lifecycle and request flows can be found through those respective links.

Components

Components are powerful, pre-designed and built units of presentation. You can use components to quickly build our the UI of your app and collect and respond to user behavior. There are three categories of components:

  1. Presentation components
  2. Interactive components
  3. Action components

You can combine some of these components together in order to show/explain certain items, allow people to interact with sections, and then take the required action upon certain interactions.

Other resources

The admin object provides information on the Intercom teammate.

Key
Type
Description

type

string

Value will always be 'admin'.

id

string

The id of the admin.

name

string

The name of the admin.

email

string

The email address of the admin.

job_title

string

The job title of the admin.

away_mode_enabled

boolean

Identifies if this admin is currently set in away mode.

away_mode_reassign

boolean

Identifies if this admin has currently set replies to assigned conversations to go automatically into the workspaces default inbox.

avatar

object

Contains an 'image_url' string attribute within.

team_ids

array[integer]

This is a list of teams id's that the admin is a part of. Only set if the type is 'admin'.

{
  "admin": {
    "type": "admin",
    "id": "814860",
    "name": "IntercomTest",
    "email": "theadmin@example.com",
    "job_title": "Existentialist",
    "away_mode_enabled": false,
    "away_mode_reassign": false,
    "avatar": {
      "image_url": "https://static.site.test.icon"
    },
    "team_ids": [
      814865
    ]
  }
}
Suggest Edits

Input Values

 

The input-values object is a JSON hash where you can add key-value pairs.

It's returned to the relevant URLs to specify any data that had been inputted by teammates during the configure flow, and any data that has been inputted by end users during the submit flow.

"input_values": {
    "name": "Data one",
     ... //Can be more than one pair
  }
{
  "app_id": "<string id_code of the app using the card>",
  "admin": {<Admin object of admin who is performing configuration>},
  "current_canvas": {<Canvas object>},
  "component_id": "<component_id, component which triggered action>",
  "input_values": {
    "<component_id>": "<value entered in component>",
    ...
  },
  "context": {<Context object>}
}
{
  "app_id": "<string id_code of the app using the card>",
  "current_canvas": {<Canvas object>},
  "component_id": "<component_id, component which triggered action>",
  "input_values": {
    "<component_id>": "<value entered in component>",
    ...
  },
  "user": {<User object of end-user who triggered action>},
  "context": {<Context object>}
}
Suggest Edits

Card Creation Options

 

The card_creation_options object is a JSON hash where you can add key-value pairs.

It's sent to the initialize URL to specify any data that had been inputted by teammates during the configure flow. This happens once you respond with the results object at the end of the configure flow.

{
  "card_creation_options": {
    "name": "data one",
     ... //Can be more than one pair
  }
}
{
  card_creation_options: {
    <set of key-value pairs>
  },
  app_id: "<string id_code of the app using the card>",
  context: {<Context object>}
}
Suggest Edits

Current Canvas

 

The current_canvas object mirrors the same format as the canvas object, except is returned by Intercom to your web-service.

It's returned to the relevant URLs to specify what the canvas currently looks during the configure flow, and during the submit flow respectively.

To see what is included in a canvas object when you initially send it to us, click here.

 

The context object describes where an action has taken place, and includes any relevant information you may need to customise what appears on the card.

You will receive a context object as part of a request from Intercom, but depending on the webhook and the location where it is triggered, not all of this context information is available.

Webhooks can be hit from Messenger Web context, Messenger SDK context, Inbox context, or Messages context:

Key
Type
Description

location

string

This can be either 'conversation', 'home', or 'message', depending on where the action took place.

locale

string

The default end-user language of the Messenger. Use to localise Messenger App content.

conversation_id

integer

Only present if the app was added to a conversation.

messenger_action_colour

string

The messengers action colour. Use in Sheets and Icons to make a Messenger App experience feel part of the host Messenger.

messenger_background_colour

string

The messengers background colour. Use in Sheets and Icons to make a Messenger App experience feel part of the host Messenger.

referrer

string

The current page URL of the end-user.

{
  conversation_id: 4294967297,
  locale: 'en', 
  location: 'conversation',
  messenger_action_color: '#333333',
  messenger_background_color: '#333333',
  referrer: 'https://intercom.com/'
}
{
  locale: 'en', 
  location: 'home',
  messenger_action_color: '#333333',
  messenger_background_color: '#333333',
  referrer: 'https://intercom.com/'
}
{
  "locale": 'en',
  "location": 'message',
  "messenger_action_color": '#f06192',
  "messenger_background_color": '#00acc1'
}

The user object provides information on the Intercom end-user. It is sent to your web-service as part of the submit flow when an end-user interacts with a card.

More on the user object can be found on the REST API Reference through this link. The exact same attributes will be contained the object here.

Canvases are one of the most common objects in most app cycles. They enable Intercom to determine what your app will render, alongside how this content will be rendered. These can either be:

  • Static: the given content in the canvas will remain until an action is taken to change this.
  • Live: the given content in the canvas can change dynamically whenever anybody views the card. More about the Live Canvas can be found here.

Static Canvas

Key
Type
Description

content

object

More on the content object can be found here. Max Size is 64KB.

stored_data

object

More on the stored_data object can be found here. Max Size is 64KB.

Live Canvas

Key
Type
Description

content_url

string

The URL where the content object should be fetched from dynamically. More on the content object can be found here. Max size is 64KB.

stored_data

object

More on the stored_data object can be found here. Max Size is 64KB.

{
  "canvas": {
    "content": {
      "components": [
        {
          "type": "text",
          "text": "Hello World!"
        }
      ]
    },
    "stored_data": {} //optional
  }
}
{
  "canvas": {
    "content_url": "https://messengerapp.com/get-content-here",
    "stored_data": {} //optional
  }
}
 

The content object specifies which components you want to render within the canvas of your apps card or frame. There's a small difference to note between a static and a live canvas:

  • Static: you can provide the content object within the canvas.
  • Live: you will need to provide a content_url for us to POST a request to within the canvas, and subsequently respond with the content object there.
Key
Type
Description

components

array[object]

The list of components to be rendered within a card or a frame. See our components further in this reference.

{
  "content": {
    "components": [
      {
        "type": "text",
        "text": "This is your updated canvas",
        "align": "center",
        "style": "header"
      }
    ]
  }
}
Suggest Edits

Stored Data

 

A canvas object may optionally contain the stored_data object, which is a JSON hash where you can add data you want to persist through multiple cycles.

For example, a teammate may interact with multiple configure cycles when adding an app. You can use stored_data to pass data through each of these cycles until you need it at the end.

 

The results object should be sent as the final response during the configure flow, when you want to start the initialize flow after configuration to add the app is complete.

Key
Type
Description

results

object

Set of key-value pairs representing the configuration options entered by the teammate.

{
  "results": {
    "name": "Data one", //Example teammate input
    "email": "Data two" //Example teammate input
  }
}

The event object property enables Intercom to know more about the actions that were processed by your app, in the response to a submit or submit-sheet action.

Key
Type
Description

type

string

The event type of the reported action. The only value currently accepted is completed.

{
  "event": {
  	"type": "completed"
  }
}

The text component is used for rendering blocks of text inside messenger cards. It does not accept most styling information (e.g. font size and text color). Links and bold font can be rendered through Markdown however.

Parameter
Possible Values
Required
Function

id

Any string

No

Unique identifier for the component within this card.

text

Any string
Markdown (ie. [](), **)

Yes

The text that will be rendered inside the component.

align

left (default)
center
right

No

Aligns the text inside the component.

style

header
paragraph (default)
muted
error

No

Styles the text in a specific preset style.

bottom_margin

None

No

Disables a component’s default margin-bottom of 10px.

Line Breaks

Line breaks are not converted into tags in the rendered HTML, so all text will appear on a single line.

Card View

Frame View

{
  "type":  "text",
  "text":  "Welcome to the messenger app framework",
  "style": "header",
  "align": "left"
}

An image component is used to display an image inside a messenger card.

HTTPS Images

If your request URLs (or website URLs) are over HTTPS, you will need to ensure that images are loaded over HTTPS likewise. Otherwise, they will not work.

Parameter
Possible Values
Required
Function

id

Any string

No

Unique identifier for the component within this card.

url

A valid URL

Yes

The URL where the image is located.

align

left (default)
center
right

No

Aligns the image inside the component.

width

Any number

Yes

Width of the image in pixels.

height

Any number

Yes

Height of the image in pixels.

rounded

true
false (default)

No

Rounds the corners of the image if true.

Card View

Frame View

{
  "type": "image", 
  "url":  "https://somesite.com/images640_480.png",
  "width":  640,
  "height": 480
}

A spacer component is used to create empty space between other messenger card components.

Parameter
Possible Values
Required
Function

id

Any string

No

Unique identifier for the component within this card.

size

xs
s (default)
m
l
xl

No

Represents the amount of space between components.

Card View

Frame View

{
  "type": "spacer", 
  "size":  "xl"
}
 

A spacer component is used to create empty space between other messenger card components.

Parameter
Possible Values
Required
Function

id

Any string

No

Unique identifier for the component within this card.

bottom_margin

None

No

Card View

Frame View

{
  "type": "divider"
}

A button component is used to trigger an action. Depending on the action type, a button can:

Buttons are submittable, meaning that when they are clicked, they will dispatch a webhook to the url specified through the relevant action. Read more about this by clicking on the different actions that can be taken above.

Parameter
Possible Values
Required
Function

id

Any string

Yes

Unique identifier for the component within this card.

label

Any string

Yes

The text that will be rendered inside the button.

action

Object

Yes

style

primary (default)
secondary
link

No

Styles the button in a specific preset style.

disabled

false (default)
true

No

Styles as complete and prevents further editing or interaction.

Line Breaks

Line breaks are not converted into tags in the rendered HTML, so all text will appear on a single line.

Card View

Frame View

{
  "type":  "button",
  "id": "button-123",
  "label": "Submit form",
  "style": "secondary",
  "disabled": "true",
  "action": {
    "type": "url",
    "url": "https://www.intercom.com/"
  }
}

An input component is used to capture text input from the end user.

If you pass an action to the input component, it will render with an inline button which submits the value inside the input to the specified URL.

Parameter
Possible Values
Required
Function

id

Any string

Yes

Unique identifier for the component within this card.

label

Any string

No

The text shown above the input.

placeholder

Any string

No

An example value shown inside the input when it’s empty.

value

Any string

No

The default value of the input.

action

Action object

No

save_state

unsaved (default)
saved
failed

No

The defined state of the inputted value to render a specific style.

disabled

false (default)
true

No

Styles as complete and prevents further editing or interaction.

Saved States

A save_state of saved renders the input in a style which indicates a successfully submitted value, and prevents further editing or interaction with the input. It's the only save_state that changes the function and blocks any further interaction.

This is the same functionality as if you set the disabled boolean to true. If you set the save_state as saved but the disabled boolean as false, we'll overwrite the boolean and still show the component in this disabled state.

Card View

Frame View

{
  "type": "input", 
  "id": "user_email_address",
  "label": "Enter your email address",
  "placeholder": "user@domain.com",
  "value": "peter@intercom.io",
  "save_state": "unsaved",
  "disabled": "true",
  "action": {
    "type": "submit"
  }
}

A list component renders a collection of list items. Below you can see what's needed for both the List Component and List's Items array.

List

Parameter
Possible Values
Required
Function

items

Array (see below)

Yes

The items that will be rendered in the list.

disabled

true
false

No

The defined state of the inputted value to render a specific style.

List Items

Parameter
Possible Values
Required
Function

id

Any string

Yes

Unique identifier for the component within this card.

title

Any string

Yes

The text shown as the title for the list item.

subtitle

Any string

No

The text shown underneath the list item's title.

image

A valid URL

No

An image that will be displayed on the left-hand side of the list

image_width

Any number

Yes (if image provided)

Width of the image in pixels.

image_height

Any number

Yes (if image provided)

Height of the image in pixels.

rounded_image

true
false (default)

No

Rounds the corners of the image if true.

disabled

true
false

No

The defined state of the inputted value to render a specific style.

action

Action object

No

Card View

Frame View

{
  "type": "list",
  "disabled": "true",
  "items": [
    {
      "type": "item",
      "id": "article-123",
      "title": "How to install the messenger",
      "subtitle": "An article explaining how to integrate Intercom",
      "image": "http://somesite.com/article.png",
      "image_width": 48,
      "image_height": 48,
      "roundedImage": false,
      "disabled": "true",
      "action": {
        "type": "submit"
      }
    }
  ]
}
Suggest Edits

Single-Select

 

A single select component is used to capture a choice from the teammate or end user. It requires a collection of single select options, which represent the possible choices.

Single-Select

Parameter
Possible Values
Required
Function

id

Any string

Yes

Unique identifier for the component within this card. Single select components are submitted in a hash, with this id used as the key and the id of the chosen option as the value.

label

Any string

No

The text shown above the input.

options

Array

Yes

The list of options. A minimum of 2 options is required, and no more than 11 are allowed. More on the Options array is below.

value

Any string

No

The default value of the option.

action

Action object

No

save_state

unsaved (default)
saved
failed

No

The defined state of the inputted value to render a specific style.

disabled

false (default)
true

No

Styles as complete and prevents further editing or interaction.

Saved States

A save_state of saved renders the input in a style which indicates a successfully submitted value, and prevents further editing or interaction with the input. It's the only save_state that changes the function and blocks any further interaction.

Options

Parameter
Possible Values
Required
Function

id

Any string

Yes

Unique identifier for the option. Single select components are submitted in a hash, with this id used as the key and the id of the chosen option as the value.

text

Any string

Yes

The text shown within this option.

disabled

false (default)
true

No

Styles as complete and prevents further editing or interaction.

Card View

Frame View

{
  "type": "single-select",
  "id": "industry",
  "label": "Choose your industry",
  "value": "banking",
  "save_state": "unsaved",
  "disabled": "true",
  "options": [
    {
      "type": "option",
      "id": "banking",
      "text": "Banking"
    }, 
    {
      "type": "option",
      "id": "tech",
      "text": "Technology",
      "disabled": "true",
    }
  ],
  "action": {
    "type": "submit"
  },
}
Suggest Edits

Submit Action

 

A submit action fires a webhook to the developer’s web-service with the current state of the card, including the values entered into any interactive components, so that the developer can trigger side-effects and/or return a new set of components to update the card state.

More on how this works is in the submit flow documentation through this link.

Input Components

If there are input elements present within the card, then a submit action from a button will submit the entire form.

action: {
  "type": "submit"
}
Suggest Edits

URL Action

 

A URL action opens the specified link in a new browser tab.

Encode non-ASCII characters

If your URL has non-ASCII characters that are not encoded, we will use the URL in a meta tag while opening the new window and it will break the non-ASCII encoding.

For JS - Use encodeURIComponent
For Ruby - Use URI.escape

action: {
  "type": "url",
  "url":  "https://www.example.com"
}
Suggest Edits

Sheets Action

 

A sheets action opens a given sheet in the URL specified, to populate a full-bleed iframe within the messenger.

More on how this works is in the sheets flow documentation through this link.

action: {
  "type": "sheet",
  "url":  "http://example.com"
}