Installation Lifecycle

Inbox Apps are installed by making an authenticated API request to the Inbox Apps Installation endpoint, providing the scope and the Subscription URL.

Scopes

📘

Account scopes require the account owner's API key.

If you wish to install your Inbox App with an account-wide scope, you must install the app using the account owner's API key. API keys from users can only be used for installations scoped to that user.

Inbox Apps can be scoped to a single user, or to the entire account. An Inbox App with an account scope has the ability to create conversations in all Team Inboxes as well as all User Inboxes. An Inbox App with a user scope can only create conversations in that user's Inbox.

Subscription URL

During installation you will provide a Subscription URL. This URL will be used by Follow Up Boss to send your application webhooks when a user replies to an Inbox App conversation from within FUB, or when certain Inbox App or conversation events occur such as a conversation being read or archived.

Subscription URLs may be unique to each Inbox App installation, or you can use the same Subscription URL across many installations and accounts.

Installation Lifecycle

Collect an API Key

You will need a valid API Key to install and use Inbox Apps. You can collect this from the user at the time they are installing the app, or may reuse one you have obtained for a broader integration.

An account owner's API key can be used to install an Inbox App account-wide, or for any active user. A user's API key can only be used to install an Inbox App for that user. It may be helpful to query GET /v1/me to determine what type of API key you have been provided.

Request Installation

You can initiate an installation by making request to POST /v1/inboxApps/install with the following payload.

{
  "publishedInboxAppId": 1,
  "userId": 1,
  "subscriptionUrl": "https://example.test/inbox-app-reply"
}

Confirm Subscription URL Validity

Follow Up Boss will synchronously make a POST request to your specified subscriptionUrl with the following payload. You must respond with a HTTP 200 OK status code to indicate your receipt.

{
  "test": 1
}

If you fail to respond with HTTP 200 OK in a timely manner, we will reject your POST /v1/inboxApps/install request with HTTP 400 Bad Request.

Installation complete

Once we receive an HTTP 200 OK response from your subscriptionUrl we will install and activate your Inbox App, responding to your install request with HTTP 201 Created and your newly installed Inbox App ID.

Installing from Follow Up Boss

📘

Inbox Apps are only available in FUB once published.

Inbox Apps in development or private beta will not be visible on the in-app Integrations page.

Inbox Apps can also be installed from Follow Up Boss. When you begin developing your Inbox App you will give us a Installation Redirect URL.

If a user installs an Inbox App from Follow Up Boss, we will redirect them to your Installation Redirect URL with a fubUserId query parameter, where you can complete installation following the standard installation lifecycle described above. If the requested installation scope is account-wide, fubUserId will be 0.

Legacy FUB-Initiated Installation

Documentation for the legacy FUB-Initiated Installation (also called "installation handshake") process is available here. Please note FUB-Initiated Installation is only available for existing Inbox Apps that are grandfathered in.