Request Flows

Configure Flow

This is an optional request flow that you can implement if your app requires configuration before displaying it to an end user. You can implement the configure-flow by simply specifying a configure_url when setting up your app. Then, an HTTP POST will be made to that URL when a teammate selects your app.

This request allows you to respond with an updated canvas which the teammate can interact with to help construct the app. Or, you can return a result object containing card creation options which indicates the configuration is now complete.

Once a result object is sent, the collected information will be posted to the initialize-url URL.

Example Configure Flow

# This is the initial POST request which Intercom will send to your configure-card URL. 

{
  app_id: <string id_code of the app using the card>,
  admin: <Admin object of admin who is performing configuration>,
  context: <Context object>
}

# You can then decide which of the two responses you would like to send; a canvas or results object. 
# This object will be used to render a configuration UI inside the inserter or home screen configuration. 

{
  canvas: <Canvas object>
}

# Taking an action in this UI will result in a further request to the configure URL with the following payload.

{
  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>
}

# As with the initial request, this may be responded to with either another canvas or a configuration result.
# To finish configuration the developer responds with a results object indicating the computed configuration options.

{
  results: {
    <set of key-value pairs>
  }
}

# These results will then be posted to the initialize-url as card creation options.

Objects in Configure Flow

Initialize Flow

Teammates can add a card instance of your Messenger App to conversations, to the homescreen, or to a Message. When they do, the framework sends a HTTP POST to your webservice via the initialize_url you provided. This asks you what the initial canvas for your new card should look like.

If you have implemented the configure flow then a teammate will have entered some configuration options. These are known as card creation options.

We gather those card creation options from the teammate, and send them to you as part of the payload of the initialize-card request. You return back a canvas containing the initial UI for the new card.

What if I have no configure flow?

Remember, the configure flow is optional, so if you haven't specified a configure_url then the framework will just start with the initialize flow when the teammate adds the app to the inbox.

Example Initialize Flow

# When a card is being added, Intercom POSTs a request to the Messenger app’s initialize_url with the card creation parameters gathered from the teammate. The payload is in the following form:

{
  card_creation_options: {
    <set of key-value pairs>
  },
  app_id: <string id_code of the app using the card>,
  context: <Context object>
}
# The developer returns a response in the following format.

{
  canvas: <Canvas object>
}

Objects in the Initialize Flow

Submit Flow

When an end user clicks a button or submits text to an input field on a card, the framework fires a HTTP POST to the submit_url you have provided. The purpose of this request is to tell you a user took an action on the card, and ask how it should be updated.

This request also gives you a chance to trigger any actions you want in your own code, like adding a user’s email to your own database or scheduling a calendar event.

The payload contains information about the end user: the action they took, what values they had filled into each input field, and the card’s current canvas. In the response, you return back a new canvas object, containing the updated UI for the card.

App Completion Tracking (optional)

App completion events will help you understand how your customers are using your app and will add more value to it, making it possible for bots to know when to continue with their flows.

You can optionally add an event object to your submit flow response to tell us if your messenger app has completed its purpose. For example, an email collector app completes when the end-user submits their email address.

Example Submit Flow

# When an end-user triggers a submit action on a card, Intercom POSTs a request to the messenger-app’s `submit_url` with the following payload.

{
  app_id: <string id_code of the app using the card>,
  current_canvas: <Canvas object>,
  component_id: <component_id>,
  input_values: {
    <component_id>: <value entered in component>,
    ... 
  },
  user: <User object of end-user who triggered action>,
  context: {
    location: <"conversation"/"home">,
    conversation_id: <conversation_id> # Only needed if location == conversation
  }
}
# The developer returns a response in the following format.

{
  canvas: <Canvas object>,
  event: { type: “completed” }, # App Completion Tracking (optional)
}

# The card which triggered the request is updated with the new canvas from the response.

# The app completion event is recorded by Intercom.

Objects in the Submit Flow

Live-canvas Flow

The live canvas is an optional extension of the canvas object which enables developers to provide up-to-date information in a card

It can be implemented by simply returning a content_url in a canvas object.

Whenever the card containing that canvas object is rendered in the Messenger, a POST request will be sent to that content URL.

This enables a developer to provide a live (rather then the regular static) version of a canvas.

No interaction required

Note that no user interaction is required for the POST request to be triggered. It will occur whenever the card is viewed in a conversation. The live canvas can also be rendered in a teammate inbox.

Why would I need a live canvas?

You can usually realize similar functionality to a live canvas by requiring a user interaction.

Think of a webinar booking app as an example scenario. You may have a button a user can click on to show them the availability and times for the next webinar.

However, in some cases this is not ideal. If you had an app that showed the current health status of your product or platform for example.

Ideally, you would like this to show the current state without requiring a user to manually trigger a status refresh. You would use a live canvas to do this.

As a result, whenever a user opens up their conversation with the health status card they will always get the latest state (which is hopefully green), and they will not need to instigate any action to do so.

Example Live Canvas Flow

Objects in the Live Canvas Flow

Please see the canvas object for more details on how to implement this flow and the expected response from your webservice.


What's Next

Sheets are an alternative to canvas cards, whereby you can use the messenger for more lengthy, complicated workflows. You can find more about all components and object ins our reference. Our Configuring your app guide will then help you set up all your endpoints for us to POST these requests to.

Sheets Flow
Framework Reference
Configuring your app