Tutorial: Create your first app

🚧

Important

Always use a sandbox account or test organization to complete tutorials. You won't be able to uninstall an app once you register the app to an organization.

If you need to request a sandbox account or a test organization for development, see Getting access. If you register an app to a Kustomer organization on accident, you can contact [email protected] to remove the app from view.

This tutorial shows you how to create a simple "Hello World" app for a Kustomer organization. The "Hello World" app configures on the Insight Panel an Insight Card that displays "Hello, [Customer Name]!" for every customer that an agent views.

Tutorial goals

By the end of this tutorial, you'll know how to:

• Define a basic Kustomer app in JSON
• Register the app definition to a Kustomer organization using an API call
• Install the registered app from the app directory

Prerequisites

Before you get started, make sure you have the following:

• Access to a sandbox account or test organization with at least Administrator access
• A valid API Key that includes the following roles at the minimum: org.admin.apps and org.permission.apps

Step 1: Define your app

First, you'll create an app definition in JSON. Every app in Kustomer requires a valid JSON app definition.

We'll provide a basic "Hello World" app definition template for you to use for the tutorial. You'll notice that the "Hello World" app definition below specifies only a few properties: app, version , title, and kviews. You can learn more about Kustomer app definition properties and descriptions in App definition basics.

Replace <organization> in the app property and kviews.name property with the name of the Kustomer organization you'll register the app to or another unique string.

Examples:

• "app": "hello_world_kustomer"
• "name": "hello-world-kustomer.helloworld"

{
	"app": "hello_world_<organization>",
	"version": "0.0.1",
	"title": "Hello World",
	"kviews": [{
    	"name": "hello-world-<organization>.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 you have your app definition, you're ready to register your "Hello Word" app to the sandbox account or test organization.

Step 2: Register your app

After defining an app in JSON, you can create and send a Kustomer API call to upload the app definition to a Kustomer organization to register the app. Once registered, the app will be available for installation from the app directory of the Kustomer organization linked with the API key.

In your API call, use the POST method for the /v1/apps/available Kustomer endpoint. Authenticate the call with an API key for your organization and include the app definition as the body.

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

We've provided an API request in cURL for you to use as a template below.

Before sending the cURL request, replace <API-token-goes-here> with a valid API key and use your version of the "Hello World" app definition from the previous step in the body of the request.

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_<organization>",
	"version": "0.0.1",
	"title": "Hello World",
	"kviews": [{
    "name": "hello-world-<organization>.helloworld",
		"template": "<div style={ { padding: '10px' } }>Hello, {_.get(customer, 'name')}!</div>",
		"context": "smartbar-card",
		"resource": "customer",
		"meta": {
			"displayName": "Hello World",
			"icon": "earth",
			"state": "open"
		}
	}]
}'

Step 3: Install your app

If the API request and app registration are successful, your "Hello World" app will appear under the "Directory" tab in the app directory of your organization.

To access the app directory, select Settings in the Kustomer menu and go to Apps > App Directory. In the app directory, select the "Directory" tab and scroll until you see your "Hello World" app with the specified app name, logo, and app version.

Select your app to see the app details page.

Select Install to install your app to your Kustomer organization.

Once you install your "Hello World" app, you can go to the Kustomer timeline view. The "Hello World" Insights Card will appear in the Insights Panel when viewing customers.