Register and update apps

To register a new app or to update an existing app, create and send a Kustomer API call to upload a new or updated app definition to the appropriate Kustomer organization.

Getting a Kustomer API key

You can set up an API key in Kustomer under Settings > Security > API Keys. Create an API Key with the org.admin.apps role. Learn more about creating API keys in: Kustomer Help Center | API Keys

Registering an app through the Kustomer API

To register a new app, make an API call using the POST method for the /v1/apps/available endpoint. Authenticate the call with an API key for your organization and include the JSON app definition as the body.

You can use tools such as Postman or cURL to construct and send your API request.

The body of the request must include the app definition including a valid version. For the first version, you'll use the following for the version property: "version": "0.0.1".

Example cURL call to register an app to a Kustomer organization:

curl --location --request POST 'https://api.kustomerapp.com/v1/apps/available'
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API-token-goes-here>' \
--data-raw '{
    "app": "hello_world_example",
    "version": "0.0.1",
    "title": "Hello World",
    "kviews": [{
    "name": "hello-world-example.helloworld",
        "template": "<div style={ { padding: '10px' } }>Hello, {_.get(customer, 'name')}!</div>",
        "context": "smartbar-card",
        "resource": "customer",
        "meta": {
            "displayName": "Hello World",
            "icon": "earth",
            "state": "open"
        }
    }]
}'

Once registered, an app will be available for installation from the app directory of the Kustomer organization linked with the API key.

Updating an app through the Kustomer API

To update an app, modify the version and body for the API request you used to register the app. Use the POST method to send the updated app definition to the same /v1/apps/available endpoint.

In the updated app definition, you must include a new valid app version and can also include any relevant updates in the body of the definition (for example, link to updated release notes, an updated description, and so on).

Example cURL call to update an app to a Kustomer organization with a new version:

curl --location --request POST 'https://api.kustomerapp.com/v1/apps/available'
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API-token-goes-here>' \
--data-raw '{
    "app": "hello_world_example",
    "version": "0.0.2",
    "title": "Hello World",
    "kviews": [{
    "name": "hello-world-example.helloworld",
        "template": "<div style={ { padding: '10px' } }>Hello, {_.get(customer, 'name')}!</div>",
        "context": "smartbar-card",
        "resource": "customer",
        "meta": {
            "displayName": "Hello World",
            "icon": "earth",
            "state": "open"
        }
    }]
}'

Updating certain app fields without a version bump

The following fields can be updated without a version bump via PATCH /v1/apps/available/:appVersion:

title
iconUrl
description
vendor
website
screenshots
instructions
releaseNotesUrl
postInstallMessage

The endpoint's appVersion path segment can either be <name>-<version> or <name>-latest. So for the hello_world_example app it could be either hello_world_example-0.0.2 or hello_world_example-latest.

Notice: While the endpoint is the same for both public and private apps, it can only be called by the org that initially registered the app. Therefore, if the app is a public app registered by the Kustomer team, it can only be updated by the Kustomer team.

curl --location --request POST 'https://api.kustomerapp.com/v1/apps/available/<appVersion>'
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API-token-goes-here>' \
--data-raw '{
    "title": "Hello World!",
    "description": "A Hello World App"
}'

Registering and updating an app through Kustomer App Starter Config

You can also use the available Kustomer App Starter Config repo to make it even simpler to register or update your app and to get started with building apps.

After you define your app and add the app to the index.js file, you can run npm run register-new-version <app-name> to register or to update your app.

Troubleshooting

Having trouble with registering or updating an app? Here are some common things to check for and to try:

Duplicate app id

The app property must be defined with an id that is globally unique to each Kustomer organization.

You will get the following error message in your JSON response if you try to register a new app with an app id already registered to the same Kustomer organization:

...
 "errors": [
        {
            "status": 409,
            "source": {
                "parameter": ""
            },
            "code": "duplicate"
        }
    ]
...

Troubleshooting steps

Update your app definition so that the app id is globally unique for the Kustomer organization. You can then submit the app definition again with the same version.

App won't install or upgrade from the app directory

An app registered or upgraded with errors in the definition might cause installation issues from within the app directory. If you are unable to install an app from the app directory or you run into app installation errors, you will need to update the app with the corrected version.

Troubleshooting steps

Step 1: Update the app with a minimal app definition

Submit a new version of the app definition that defines just the two app properties required to register an app: app and version.

Once you update the app definition, you should be able to upgrade and install the new version.

Step 2: Update the app with the correct app definition

Correct any errors in your original app definition. Submit the corrected full app definition under a new app version.

Once you register the corrected app definition, you should be able to upgrade to and install the new app version.