Configuration and Integration

Installation Settings

Learn how to manage app installation settings and provide a customized setup experience for users.

Installation settings allow developers to define customizable settings for their apps, providing users with a tailored installation experience. These settings can be configured through a schema provided on the app settings page and are presented to users during the app installation process.


To provide installation settings, developers need to define a settings schema on the app settings page. This schema outlines the fields and data types that users need to fill out when installing the app.

The schema is a JSON object that maps field names to the objects that define the field’s data type and other properties.

The following example shows a simple schema for a name field:

2 "name": {
3 "type": "text",
4 "description": "Your full name",
5 "displayName": "Name"
6 }

Supported Field Types

Field TypeDescription
textA simple text field.
passwordAn field for passwords.
paragraphA larger text field for long texts.
numberAn field for numeric values.
emailAn field for email addresses.
urlAn field for URLs.
dateAn field for date selection.
checkboxA checkbox field.
radioA radio button group.
selectA dropdown menu.
multiselectA multiple selection input.

Field Attributes

displayNameThe label displayed to the user.
descriptionA description of the field.
defaultValueThe default value of the field.
requiredA boolean indicating whether the field is required.
optionsA list of strings that can be selected from. Only used for radio, select and multiselect fields.

Accessing settings in app code

Settings are available as an object with keys corresponding to the field names in the schema, and values of the appropriate type.

Once the app is installed, apps can access these settings in the following ways:

Using getSettings in handleRequest

1export default {
2 handleRequest({getSettings}) {
3 const settings = await getSettings({
4 organizationId: 'ORGANIZATION_ID',
5 agentId: 'AGENT_ID',
6 })
7 console.log(settings.key1)
8 ...
9 }

Using settings in other handlers

The other handlers are called in the context of an organization and agent, so they can access the settings directly.

1export default {
2 preInstall({settings}) {
3 console.log(settings.key1)
4 ...
5 },
6 postInstall({settings}) {
7 ...
8 },
9 executeAction({settings}) {
10 ...
11 },