Custom object sidebar apps

Custom object record sidebar apps let you embed contextual, interactive applications alongside custom object record pages in the Zendesk agent interface. This enables object-specific workflows, such as order history, account details, and other industry-tailored use cases, directly within the agent workspace.

The app is displayed in the apps tray on the right side of a custom object record page in the agent interface. While the user experience matches existing sidebar locations, app visibility can be explicitly scoped to specific custom object types.

What you can do with custom object record sidebar apps:

• Target specific objects: Configure your manifest.json using objectTypes to show apps only on relevant custom object record pages (for example, car or truck).
• Build dynamic UI: Access real-time record context and schema info directly from the client cache using client.get('custom_object_record').
• React to live edits: Listen for field and record updates to keep your app UI in sync with agent actions.

Note: Custom object record sidebar apps work with the current custom objects experience only. It is not compatible with custom data developed using the Legacy Custom Objects API.

Before you begin

Before building a custom object record sidebar app, make sure you have:

• A Zendesk account with custom objects enabled
• ZCLI installed
• The ZAF SDK imported in your app. See Getting the SDK
• The keys of the custom object types your app will target. You can find these in Admin Center under Objects and rules > Custom objects

Getting started

1. Configure your manifest: manifest.json is your app's configuration file. It tells Zendesk where to display your app and how to load it. Set up the custom_object_record_sidebar location in manifest.json and specify the target objectTypes.

2. Declare object dependencies: requirements.json declares the Zendesk resources your app needs. Zendesk creates or validates these resources when the app is installed. Add your custom object definitions to requirements.json under custom_objects_v2 so they exist when the app is installed.

3. Initialize ZAF: The Zendesk Apps Framework (ZAF) SDK provides the client-side API that lets your app read record data, respond to events, and interact with the Zendesk interface. Use ZAFClient.init() to initialize the client in your app code, then begin fetching record context using client.get('custom_object_record').

4. Test your app: Run your app locally using ZCLI to verify placement, data binding, and change event handling on custom object record pages. See Testing your app.

Supported locations

Use the custom object record sidebar location to control where an app appears on custom object record pages. An app can target one or multiple custom object types.

For example, an app can be configured to appear only on car and truck record pages, while staying hidden on other custom object pages.

Manifest configuration

Define the custom_object_record_sidebar location in your app's manifest.json file under location.support.

{
  "location": {
    "support": {
      "ticket_sidebar": {
        "autoLoad": false
      },
      "custom_object_record_sidebar": {
        "url": "assets/iframe.html",
        "objectTypes": ["car", "truck"]
      }
    }
  }
}

This example shows custom_object_record_sidebar alongside an existing ticket_sidebar location. You can include both locations in the same app, or use custom_object_record_sidebar on its own.

For custom_object_record_sidebar, objectTypes is required and must be a non-empty array of custom object keys. The values must match the keys of existing custom object types in your Zendesk account. You can find custom object keys in Admin Center under Objects and rules > Custom objects. The objectTypes field is only supported on custom_object_record_sidebar.

For available location properties, see Setting the app location.

Requirements.json dependencies

Custom object record sidebar apps require the targeted custom object definitions to exist before the app can bind to them during setup.

When distributing your app, declare any required custom object resources in your requirements.json file using the custom_objects_v2 property. This allows Zendesk to automatically validate or create the required custom objects during app installation.

Example:

{
  "custom_objects_v2": {
    "objects": [
      {
        "key": "car",
        "title": "Car",
        "title_pluralized": "Cars"
      }
    ]
  }
}

For more information, see Specifying app requirements.

Accessing record context

In addition to the objects available in all locations, apps running on custom object record pages can retrieve real-time record context directly from the client-side cache using the ZAF client.

Before calling any client methods, make sure the ZAF SDK is imported in your app's HTML file. See Getting the SDK.

Get current user context

Like other app locations, you can retrieve information about the currently signed-in agent:

var client = ZAFClient.init();

client.get('currentUser').then(function(data) {
  console.log(data.currentUser);
});

Get the full record object

Use client.get('custom_object_record') to retrieve all properties for the current custom object record.

var client = ZAFClient.init();

client.get('custom_object_record').then(function(data) {
  console.log(data.custom_object_record);
});

Get specific standard properties

To retrieve standard attributes like the id, name, or external id:

var client = ZAFClient.init();

client.get(['custom_object_record.id', 'custom_object_record.name', 'custom_object_record.externalId']).then(function(data) {
  console.log(data);
});

Get custom field values

To retrieve specific custom fields, use custom_object_record.customField:fieldKey, replacing fieldKey with the key of your custom field.

var client = ZAFClient.init();

client.get('custom_object_record.customField:serial_number').then(function(data) {
  console.log(data['custom_object_record.customField:serial_number']);
});

Values are returned as:

• string for text, multiline, regexp, integer, decimal, currency, date, and dropdown fields
• boolean for checkbox fields
• string[] for multiselect fields
• { id: string | null, name: string | null } for lookup and parent fields
• null when no value is set

Note: custom_object_record.customField only supports custom field keys. For standard attributes, use custom_object_record.name and custom_object_record.externalId.

Get all field values at once

Use custom_object_record.fields to return all record field values as a key-value object:

var client = ZAFClient.init();

client.get('custom_object_record.fields').then(function(data) {
  console.log(data['custom_object_record.fields']);
});

Accessing schema information

Apps can retrieve complete schema metadata for the record's fields using custom_object_record.schema. This includes field properties, field types, requirement status, and dropdown options.

var client = ZAFClient.init();

client.get('custom_object_record.schema').then(function(data) {
  console.log(data['custom_object_record.schema']);
});

Field schema properties

• key: Field key
• title: Field title
• type: Normalized field type (checkbox, currency, date, decimal, dropdown, integer, lookup, multiline, multiselect, parent, regexp, text, or unknown)
• isRequired: Whether the field is required
• options: Available options for dropdown and multiselect fields
• relationshipTargetType: Target type for lookup and parent fields
• allowedCurrencies: Allowed currencies for currency fields

Working with change events

In addition to core events, you can use the following events to listen for changes to the current custom object record:

• custom_object_record.name.changed
• custom_object_record.externalId.changed
• custom_object_record.customField:[field_key].changed

For custom fields, replace [field_key] with the custom field's key.

Example:

var client = ZAFClient.init();

client.on('custom_object_record.customField:serial_number.changed', function(value) {
  console.log('Serial number updated to:', value);
});

The event payload is the latest value for the changed property.

Admin controls and security

Admins manage custom object record sidebar apps in Admin Center using standard app management controls:

• App title: Admins can change how the app name appears to agents.
• Access controls: Admins can apply role and group restrictions to control app visibility.

Data access & security

Apps running in the custom object record sidebar must respect agent permissions. The app should only display data that the currently signed-in agent is authorized to view. If an agent lacks access to a field or related record, the app must mask or exclude that data.

Agent experience

From the agent's perspective, custom object record sidebar apps appear in the apps tray on the custom object record page, matching the look and feel of user and organization sidebar apps.

To provide a consistent agent workspace experience, design your app with:

• A clear, descriptive title
• A compact, single-column layout optimized for the sidebar container
• Clear data hierarchy and scannable content

Example app

The following example shows a minimal custom object record sidebar app that displays the record name and a custom field value when the app loads, and updates the display when that field changes.

assets/iframe.html

<!DOCTYPE html>
<html>
  <head>
    <script src="https://static.zdassets.com/zendesk_app_framework_sdk/2.0/zaf_sdk.min.js"></script>
  </head>
  <body>
    <p id="record-name"></p>
    <p id="color"></p>
    <script>
      var client = ZAFClient.init();

      client.get(['custom_object_record.name', 'custom_object_record.customField:color'])
        .then(function(data) {
          document.getElementById('record-name').textContent = data['custom_object_record.name'];
          document.getElementById('color').textContent = data['custom_object_record.customField:color'];
        });

      client.on('custom_object_record.customField:color.changed', function(value) {
        document.getElementById('color').textContent = value;
      });
    </script>
  </body>
</html>

manifest.json

{
  "name": "Car Details",
  "author": {
    "name": "Your Name",
    "email": "[email protected]",
    "url": "https://example.com"
  },
  "defaultLocale": "en",
  "private": true,
  "version": "1.0",
  "frameworkVersion": "2.0",
  "location": {
    "support": {
      "custom_object_record_sidebar": {
        "url": "assets/iframe.html",
        "objectTypes": ["car"]
      }
    }
  }
}

requirements.json

{
  "custom_objects_v2": {
    "objects": [
      {
        "key": "car",
        "title": "Car",
        "title_pluralized": "Cars"
      }
    ]
  }
}

Testing your app

You can use ZCLI to run your custom object sidebar app locally during development. See Testing your Zendesk app locally.

Important: The ZCLI local server does not process requirements.json. This means that custom object definitions declared under custom_objects_v2 will not be automatically created during a local test session. As a result, the custom object types your app targets may not exist in your test account when running locally.

To work around this, use one of the following approaches before testing:

• Create custom objects manually: In your test account, manually create the custom object types your app targets. Your app can then bind to them during the ZCLI test session.

• Install as a private app: Package and install the app as a private app. This triggers Zendesk to process requirements.json and automatically create the required custom object resources. See Uploading and installing a private app.