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.

Reinstalling an Inbox App

If you attempt to perform an installation for an Inbox App that has previously been installed and is currently deactivated, we will reactivate the existing Inbox App ID instead of creating a new one. Your Subscription URL will be updated according to the one included in the new install request.

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.

Deactivating an Inbox App

Users can deactivate (called "Uninstall" in-app) an Inbox App from Follow Up Boss, at which point you will no longer be able to create new conversations or add messages or notes to conversations, and users will not be able to reply to any existing conversations.

You can also proactively deactivate an Inbox App using our Deactivate Inbox App API. This is useful in cases where a user unsubscribes from your service, or requests that you turn off your Inbox App for their account.

Deactivation Webhook

Whenever an Inbox App is deactivated - whether by the user or by using the Deactivate API - Follow Up Boss will send an inboxAppDeactivated webhook to that app's Subscription URL.

{
  "eventId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "eventCreated": "2024-01-01T12:00:00+00:00",
  "event": "inboxAppDeactivated",
  "data": {
    "inboxAppId": 1
  }
}