Check out the video below for a technical overview of how the request-response cycles work, and then read on for a written breakdown with links for more information.
This flow allows teammates to configure an app prior to sending it to a user. This flow can occur multiple times as a teammate interacts with your app. On each request, you have the opportunity to respond and update the canvas that is displayed to the teammate. This allows more complicated, multi-stage configuration steps.
This flow is about initializing the app in order to render how it first displays to an end user.
This flow is triggered any time a user interacts with your app and specifies the resulting action is to submit - more can be found about the components that can support this and the relevant object through this link. This flow can occur multiple times as a user interacts with your app. On each request/response loop you have the opportunity to respond and update the canvas that's displayed to the user.
This flow provides access to Sheets, a full-bleed takeover of the Messenger window. Sheets are populated with iframes. There are two actions which are relevant if you're using sheets:
- The open-sheet action you use to open a sheet
- The submit-sheet action which is used when closing a sheet
While each individual flow is different, they do share a common pattern. Once you get used to the pattern you'll start to see your app as a tennis match between users or teammates triggering actions in your app and your backend service handling those requests and responding with the JSON to update the UI of your app appropriately.
You can see the general format of an individual flow, and whether they occur on the Intercom side or on your side, in the diagram below:
A flow begins with an interaction. This can either be a teammate adding your app to the Messenger/Message/Conversation, or an end-user interacting with your app.
Following an interaction, Intercom will send an HTTP
POSTrequest to your web-service with the data you'll need in order to respond. Examples of what we include in these requests can be found here..
You'll need to consume the HTTP request and get the data you need to enable you to decide how to respond. This is where any backend processing you might need to do would occur.
Armed with the data from the interaction step, you can decide how to respond. All responses should be valid JSON. Examples of what you can send in response can be found here.
Unless otherwise specified, each request from the Framework is signed by Intercom via an X-Body-Signature header. We do this so that you can check that each request is actually sent by Intercom by decoding the signature.
The value of this X-Body-Signature header is computed by creating a signature using the body of the JSON request and your app's OAuth client_secret value, which you can find on the Basic Info page of your app. It is a hexadecimal (64-byte) value that is computed using the HMAC-SHA256 algorithm as defined in RFC2104.
The X-Body-Signature header value is the signature value. For example, X-Body-Signature:
Each request happens at a different time within the app's lifecycle, and will be sent to the URL that you must setup and then specify on your Messenger Framework page. Below is an overview of how teammates and end users can interact with the app through each flow and a description of each can be seen below.
User data and your Messenger App
As a developer building on top of the Intercom Platform, it’s important to know that Intercom customers (and their end users) can put whatever data they want into Intercom at any stage of the flow and that data will not be checked for authenticity or veracity.
Get more details on each of the request flows with example request and response objects.