Get KViews by Resource

get/v1/kviews/{resource}
Requires any one of these rolesAbout roles
org.permission.kview.read
Legacyorg.user.kview.readorg.admin.kview.read

The API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.

Retrieves all the KViews for a resource.

Optionally, the context can be included to be more specific.

If the context is included, it will be ordered according to when the KView was added or the order specified in the KView ordering endpoint.

About this resource

KViews

A KView (Klass View) is a view template that Kustomer renders in the agent desktop for one type of record, such as a card in the insights panel or the body of a custom object in the timeline. These endpoints read the KViews in your org, edit them and set the order they appear in.

KViews control how records look to agents. Each KView belongs to one resource (customer, company, conversation, or a custom object type written as kobject.<klass>) and renders in one context. Admins build them in Kustomer's KView editor, and apps install them from the kviews section of an app definition. Through this API you can read, edit, enable or disable, and reorder existing KViews; creating them happens in the editor or through an app.

Contexts

context Where it renders
smartbar-card A card in the insights panel to the right of the timeline
smartbar-details The details panel at the top of the insights panel
expanded-timeline The body of a custom object when an agent expands it in the timeline

meta.displayName is the card's title and meta.icon its header icon. enabled turns a KView on or off without deleting it.

Code and visual KViews

A KView is stored in one of two forms. When advanced is true, template holds JSX source that Kustomer evaluates in the browser, with access to the record, lodash, Moment.js and Kustomer's UI components; the KViews guide describes what's in scope. Otherwise the view was built in the visual editor and is stored as layout, a tree of row, column and component nodes, plus components, which maps each component ID to its componentType and componentAttributes. Editing template through the API is straightforward; leave layout and components to the editor.

Order and app-installed views

When several KViews share a resource and context, such as many cards on conversations, they appear in the order set by PUT /v1/kviews/{resource}/{context}/order. Send kviews as the full list of KView IDs in the order you want, up to 200. GET /v1/kviews/{resource} with a context returns views in that order. KViews installed by an app are hidden while the app is disabled, and the appDisabled filter lets you include or exclude them.

Which endpoint to use

To Call
List every KView in the org GET /v1/kviews
List the KViews for one resource, optionally one context, in display order GET /v1/kviews/{resource}
Edit a KView's template, title or icon, or enable or disable it PUT /v1/kviews/{resource}/{id}
Reorder the KViews in one resource and context PUT /v1/kviews/{resource}/{context}/order

Reading KViews works with agent or admin read roles; editing and reordering need a KView write role. A change applies to every agent as soon as it's saved, so try template edits in a sandbox org first and keep a copy of the previous template before you overwrite it. For KViews that belong to an app, change the app definition instead: an upgrade to a version where the KView changed updates it from the definition.

RelatedKViews guideKlassesAppsCards

Path parameters

resourcestringrequired

The KView resource. Common values include conversation, company, customer, and custom object resources such as kobject.shopify-order.

Example "conversation"

Query parameters

pageinteger

Page number to return.

Example 1
pageSizeinteger

Number of records to return per page.

Example 100
contextstring

Filter KViews by display context. Common values include smartbar-card, smartbar-details, and expanded-timeline.

Example "smartbar-card"
enabledboolean

Filter KViews by enabled status.

Example true
appDisabledboolean

Filter app-installed resources by app-disabled status.

Example false

Responses

OK

objectrequired
objectrequired
array<object>required