Building your app

Gist Apps enable you to pull data from a 3rd party source into the Inbox or Messenger. Ideally, it would display information that adds context about the customer and your relationship; such as account level/plan, order history, how long they have been a customer or anything else that’s important to your business.

For example, you could create an App that pulls information from a custom CRM, which includes contextual information about the customer: company name (including a link), how long they've been a customer, user role, plan name and lifetime value.

Example app

We have provided some Node.js code that you can use to quickly setup a simple counter app. Plus, we are using a tool called Glitch to build an app with this code.

How it works?

When a user installs your app in their workspace, it will be added to their Inbox or Messenger and they can start interacting with it.

When your app loads in the Inbox or Messenger, we make a POST request to the initialize URL that you provide when creating the app. You will need to return a JSON object letting us know how to render the UI.

After the app is initialized, it is made interactive using the Submit action. For example, whenever a user clicks a button in your app, we send a POST request to the submit URL that your provide when creating the app. You will need to turn a JSON object letting us know how to render the UI.

Initialize

The Initialize request is triggered when your app loads in the Inbox or Messenger: - Each time a user switches to a new conversation in Inbox. - Each time a user navigates to the Messenger home screen.

Request

The request payload will have all the data needed for you to understand who is using your app, where they are using it, and how you should respond.

{
    "workspace_id": "abcd123",
    "admin": { / Object: See link in table for the full object / },
    "conversation": { / Object: See link in table for the full object / },
    "contact": { / Object: See link in table for the full object / },
    "context": { / Object: See link in table for the full object / },
    "card_creation_options": { "key": "value" } //can be more than one pair
}

Response

We expect a Canvas object in response to the request. This is where you'll specify the UI for the first screen of the app using components.

{
    "canvas": { / A canvas object with content and components / }
}

Submit

The Submit request is triggered when a component with a submit action is interacted with.

Request

The format of the request we send is similar to the Initialize request but contains the current_canvas, input_values and the component_id. This allows you to understand what component the request came from, see what the value of any input was, action anything in your codebase, and then respond knowing what canvas was previously shown beforehand.

{
    "workspace_id": "abcd123",
    "admin": { / Object: See link in table for the full object / },
    "component_id": "id-assigned-by-you",
    "context": { / Object: See link in table for the full object / },
    "current_canvas": { / Object: See link in table for the full object / },
    "conversation": { / Object: See link in table for the full object / },
    "contact": { / Object: See link in table for the full object / },
    "input_values": { / Object: See link in table for the full object / }
}

Response

We expect a Canvas object in response to the request. This will replace the previous canvas that was visible until the app was interacted with.

{
    "canvas": { / A canvas object with content and components / }
}

You can optionally provide a card_creation_options object with the key-value pair of configuration data you want to attach to this installation instance. We send back this information to the initialize request so you can use it to render your UI. This is primarily used in the Configure flow (see next section).

{
  "canvas": { / A canvas object with content and components / },
  "card_creation_options": { "key": "value" } // Can be more than one pair
}

Configure (Optional)

Once installed, your app can optionally be configured by users before the initialize request is sent to render the app, if you provide a Configure URL during the app creation flow.

Request

The request we send will allow you to know the workspace where this is happening, the admin who will be configuring the app, and additional context such as where this will be added once complete.

For subsequent requests whereby an admin has interacted with a component with a Submit action, we send a request to the Submit URL and the request payload will contain the same details with current_canvas, input_values and the component_id also present. This allows you to understand what component the request came from, see what the value of any input was, action anything in your codebase, and then respond knowing what canvas was previously shown beforehand.

Configure Request Payload - Initial

{
  "workspace_id": "abcd123",
  "admin": { / Object: See link in table for the full model / },
  "context": { / Object: See link in table for the full model / }
}

Submit Request Payload - After Submit Action

{
  "workspace_id": "abcd123",
  "admin": { / Object: See link in table for the full model / },
  "component_id": "<component_id>",
  "context": { / Object: See link in table for the full model / },
  "current_canvas": { / Object: See link in table for the full model / },
  "input_values": { "<component_id>": "<Value entered in component>" }, //Can be more than one pair
}

Response A canvas object which will replace the previous canvas that was visible until the teammate interacted with your app.

Configure Response Payload - Initial

{
  "canvas": { / A canvas object with content and components / }
}

Submit Response Payload - After Submit Action

{
  "canvas": { / A canvas object with content and components / },
  "card_creation_options": { "key": "value" } // Can be more than one pair
}

Signing Requests

Each App SDK request is signed by Gist via an X-Body-Signature header. We do this so that you can check that each request is actually sent by Gist by decoding the signature.

The value 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 Authentication tab of your app.

It is a hexadecimal (64-byte) value that is computed using the HMAC-SHA256 algorithm as defined in RFC2104.

-H "X-Gist-Signature": "sha256=gg76d28s7hdh938dhed98h2j389d9e7dhu923"