Kustomer Apps PlatformKustomer APIRequest a Partner Account
Developer Portal

App definition basics

Learn about the basic JSON app definition properties you can use to define and register your app to a Kustomer organization.

Suggest Edits

You can create apps for a single Kustomer organization through the API call POST /v1/apps/available with an app definition in the body of the call.

This article introduces a sample app definition and lists the descriptions for the basic JSON object properties in the app definition.

Defining an app

The body of the API call POST /v1/apps/available takes a JSON object with the following app definition properties:

{
  "app": "standard_ecomm_app",
  "version": "1.2.4",
  "title": "Standard Ecommerce",
  "dependencies": ["other_ecomm_app-^1.4.0"],
  "iconUrl": "https://standardecomm.com/kustomer/app-logo.png",
  "description": "A standard app to connect to your organization's store.\nSee more at [Our Website](https://standardecomm.com)",
  "appDetails": {
    "appDeveloper": {
      "name": "Ecommerce Guild",
      "website": "https://standardecomm.com",
      "supportEmail": "[email protected]"
    },
    "externalPlatform": {
      "name": "Standard Ecomm",
      "website": "https://standardecomm.com"
    },
    "documentationLinks": [
      {
        "title": "Getting Started",
        "url": "https://standardecomm.com/getting-started"
      }
    ]
  },
  "tags": ["ecommerce", "featured"],
  "screenshots": [
    "https://standardecomm.com/kustomer/screenshot1.png",
    "https://standardecomm.com/kustomer/screenshot2.png"
  ],
  "changelog": {
    "1.2.4": "{{November 2021}}What's New \n-   We've changed something else on this version",
    "1.2.3": "{{November 2021}}What's New \n-   We've changed something on this version"
  },
  "actions": [/* data */],
  "commands": [/* data */],
  "dataSubscriptions": [/* data */],
  "hooks": [/* data */],
  "i18n": {/* data */},
  "klasses": [/* data */],
  "kviews": [/* data */],
  "meta": {/* data */},
  "outboundWebhooks": [/* data */],
  "shortcuts": [/* data */],
  "settings": {/* data */},
  "settingsPageConfig": {/* data */},
  "triggers": [/* data */],
  "widgets": [/* data */],
  "workflows": [/* data */],

}

App definition properties

The basic app definition properties and their descriptions are listed below:

app

Required. The primary universal id for the app. The name should be meaningful and human-readable and must be globally unique.

Validation: Must be globally unique. Must use alphanumeric characters and underscores only. Maximum length of 128 characters.

Example: "app": "standard_ecomm_app"

📘

Namespacing for private app names

When you register a private app, the Kustomer Apps Platform automatically namespaces the app id with _ followed by your organization ID, or orgId to ensure that the app name is globally unique. Public app names, however, do not get namespaced.

For example, let's say you registered a private app definition with the app property my_app to your Kustomer organization with an orgId of 123456789abc. Your new namespaced app id value would be my_app_123456789abc.

version

Required. The app version. The Kustomer platform uses Semantic Versioning to interpret app versions.

Validation: Must be a valid semantic version string.

Example: "version": "1.2.4"

title

Required. A display name for the app. Appears in the app directory and UI.

Example: "title": "Standard Ecommerce"

dependencies

An optional array of apps that are required as dependencies for this app. Dependencies are listed as semantic version rules. You can specify a minimum version, a range of versions, or an exact version.

Example: "dependencies": ["other_ecomm_app-^1.4.0"]

Note: This feature is geared toward more advanced, multi-app integrations. Most app developers won't need to include a list of dependencies in the app definition. For compatibility, we strongly recommend that you use minimum versions when possible. Listing an exact version may prevent users from installing your app. Example minimum version string : other_ecomm_app-^1.4.0

iconURL

A URL pointing to the logo for the app. Appears in the app directory.

Logos should be in PNG format, with a minimum size of 1200 x 1200 px.

Example: "iconUrl": "https://standardecomm.com/kustomer/app-logo.png"

description

The app description in the app directory. Supports Markdown formatting. Use \n to create a new line.

Example: "description": "A standard app to connect to your organization's store.\nSee more at [Our Website](https://standardecomm.com)."

appDetails

Details about the app to appear in the Kustomer app directory and UI. Contains information about the app developer, external platform to integrate with Kustomer, and links to support documentation.

Example: 

"appDetails": {
    "appDeveloper": {
      "name": "Ecommerce Guild",
      "website": "https://standardecomm.com",
      "supportEmail": "[email protected]"
    },
    "externalPlatform": {
      "name": "Standard Ecomm",
      "website": "https://standardecomm.com"
    },
    "documentationLinks": [
      {
        "title": "Getting Started",
        "url": "https://standardecomm.com/getting-started"
      }
    ]
  }

The appDetails definition properties and their descriptions are listed below:

appDeveloper

App developer name, website, and support contact.

  • name for link title to app developer website. Data type: string.
  • website for link URL to app developer website. Data type: string.
  • supportEmail for app developer support email address. Data type: string.

Example: 

"appDeveloper": {
      "name": "Ecommerce Guild",
      "website": "https://standardecomm.com",
      "supportEmail": "[email protected]"
    }

externalPlatform

Name and website of the external platform to integrate with Kustomer.

  • name for link title to external platform website. Data type: string.
  • website for link URL to the external platform website. Data type: string.

Example:

 "externalPlatform": {
      "name": "Standard Ecomm",
      "website": "https://standardecomm.com"
    }

documentationLinks

An array of links to support documentation (for example, help center or knowledge base articles).

  • title for the link title of support documentation. Data type: string.
  • url for the link URL to support documentation. Data type: string.

Example:

"documentationLinks": [
      {
        "title": "Getting Started",
        "url": "https://standardecomm.com/getting-started"
      }
    ]

tags

An array of tags to categorize the app in the app directory.

Validation: You can use one or more from the following five options: ai, analytics, csat, ecommerce, and messaging.

Example: "tags": ["ecommerce", "featured"]

Note: Only Kustomer can set the non-category tags builtByKustomer and featured.

screenshots

An array of URLs that point to screenshots to appear in the app directory. Choose screenshots that display how your app appears to users.

Example: "screenshots": ["https://standardecomm.com/kustomer/screenshot1.png", "https://standardecomm.com/kustomer/screenshot2.png"]

changelog

An object of release notes with the keys being versions of the app and the values being the release notes. The values are markdown so it allows for formatting. The current version of the app is required to be part of the changelog object or else the registration will fail. The date is required to be defined between curly braces and at the beginning of the release note. E.g. {{date}}.

Example: 

  "changelog": {
    "1.2.4": "{{November 2021}}What's New \n-   We've changed something else on this version",
    "1.2.3": "{{November 2021}}What's New \n-   We've changed something on this version"
  },

📘

Note

You can create apps to install and configure a variety of domain objects. See the respective pages linked in the descriptions below for more information.

actions

An array of Workflow Actions configured by the app.

commands

An array of Commands configured by the app.

dataSubscriptions

An array of specified data event subscriptions for your app.

Note: For use with meta.externalQueues for voice apps.

click-to-dial

Displays a click to dial option for voice channel team members assigned to the specified external queue.

Corresponds to Kustomer.on Cards SDK method for number-dialed event.

status-sync

Syncs voice app agent status changes for voice channel team members assigned to the specified external queue.

Corresponds to Kustomer.on Cards SDK method for routing-status-change event.

Example: 

"dataSubscriptions": [
	"click-to-dial",
	"status-sync"
]

hooks

An array of Inbound Webhooks configured by the app.

i18n

A JSON object that configures the Internationalization strings for your app.

klasses

An array of Klasses configured by the app.

kviews

An array of Klass Views configured by the app.

meta

A JSON object that configures the metadata for your app.

externalQueue

Metadata to specify an external queue name for a voice channel app.

Use externalQueue to assign voice channel teams to the external queue and to exclude voice app calls from routing to other teams.

Once configured, the external queue name appears as an option in Kustomer under Settings > Users > Teams > [Voice channel team name] > Routing Profile in the External Queues block.

Note: Can use with dataSubscriptions for voice app features.

Example: 

"meta": {
	"externalQueue": "sampleVoiceApp"
}

outboundWebhooks

An array of Outbound Webhooks configured by the app.

settings

A JSON object that configures the App Settings for your app.

settingsPageConfig

A JSON object that configures the Custom Settings Pages for your app.

shortcuts

A pre-defined block of text that can be used as a canned response.

Example:

"shortcut": {
  name: string;
  draft: {
    text: string;
    template: string;
  };
  payload: any;
  accessTeams: string[];
  accessUsers: string[];
  conversation: ConversationActions;
}

triggers

An array of Triggers configured by the app.

widgets

An array of Widgets for your app.

workflows

An array of Workflows for your app.

Registering an App

After defining an app in JSON, you can post your JSON app definition to the /v1/apps/available Kustomer API endpoint to register the app. Once registered, the app will be available for installation from the app directory of the specified Kustomer organization.

Updated 7 months ago