Build an integration

Canvas objects

Building your app

Gist Apps enable you to pull data from a 3rd party source into the Inbox. 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.

Remix on Glitch

How it works?

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

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

After the app initialized, the app is make interactive using the submit URL. 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

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 / }
}
Attribute Type Description
workspace_id String The workspace ID of the teammate.
admin Object The teammate (admin) viewing the conversation.
conversation Object The conversation your app is being shown for.
contact Object The contact which is currently being viewed by the teammate in the conversation details panel. We send an individual initialize request for each customer when it's a group conversation.

Respone

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

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",
    "conversation": { / Object: See link in table for the full object / },
    "current_canvas": { / 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 / }
}
Attribute Type Description
workspace_id String The workspace ID of the teammate.
admin Object The teammate (admin) viewing the conversation.
component_id String The id of the component clicked by the teammate to trigger the request.
conversation Object The conversation where your app is being shown.
current_canvas Object The current_canvas the teammate can see.
contact Object The contact which is currently being viewed by the teammate in the conversation details panel.
input_values Object A list of key/value pairs of data, inputted by the teammate on the current canvas.

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