Get all shortcuts

get/v1/shortcuts
Requires any one of these rolesAbout roles
org.permission.shortcut.read
Legacyorg.user.content.shortcut.readorg.user.shortcut.readorg.admin.content.shortcut.readorg.admin.shortcut.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 shortcuts or filter by shortcut name starting with text

About this resource

Shortcuts

A shortcut is a saved reply that agents insert into a conversation instead of typing the same answer again. Its text can include placeholders such as the customer's first name, and it can also update the conversation, for example by adding a tag or marking it done.

Shortcuts are an org's library of reusable replies, often called canned responses. Admins create them in the Kustomer admin settings or through these endpoints, and agents search for one by name while writing a reply in the agent desktop. Inserting a shortcut fills in its placeholders for the current conversation and puts the text in the agent's reply, where they can edit it before sending. Shortcuts are organized into categories, and a shortcut can be limited to some teams or users.

Text and placeholders

The reply text is draft.text, up to 10,240 characters of Markdown. It can contain two kinds of placeholder:

Placeholder Example Filled in with
Handlebars variables {{customer.firstName}}, {{conversation.name}}, {{currentUser.displayName}} Data about the customer, the conversation, and the agent who inserts the shortcut.
Snippet references [[sn.org.billing.refund_policy]] The current text of that snippet, so one edit to the snippet updates every shortcut that uses it.

Both are filled in when the agent inserts the shortcut, not when you save it. Kustomer does check that draft.text is a valid Handlebars template when you save it. Snippet references also work in a shortcut's name. When you read shortcuts, Kustomer replaces references in the name with text in the lang language; pass translate=false to get the stored values with the [[...]] references left as they are, which is what you want before editing and saving a shortcut.

Conversation actions

conversation describes changes to make to the conversation when the agent uses the shortcut. Each entry has an operator and a value: tags, assignedUsers and assignedTeams take append, replace or remove with a list of IDs; name, status (open or done) and subStatus take replace or remove; snooze and queue take replace; and custom sets conversation custom attributes.

Categories and access

Categories form a tree. Every org has one root category, which can't be deleted, and a shortcut or category created without parent goes into the root. A category with shortcuts or subcategories in it can't be deleted (409), so move or delete its contents first. accessTeams and accessUsers (up to 10 IDs each) make a shortcut private to those teams and users; with neither, everyone in the org can use it.

Which endpoint to use

To Call
List or search shortcuts GET /v1/shortcuts, with name for a case-insensitive name prefix, tagId, appCreated or deleted
Create, read, update or delete a shortcut POST /v1/shortcuts, GET, PUT, DELETE /v1/shortcuts/{id}
List categories GET /v1/shortcuts/categories
Create, read, update or delete a category POST /v1/shortcuts/categories, GET, PUT, DELETE /v1/shortcuts/categories/{id}

Deleting a shortcut is a soft delete: it disappears from lists unless you pass deleted=true or deleted=all, and PUT with deleted: false restores it. A deleted shortcut keeps its name, and names must be unique in the org, so restore it rather than creating a new one with the same name. An org can have up to 6,000 shortcuts that aren't deleted. Shortcuts installed by an app (appCreated=true) are managed by that app and can't be edited through these endpoints. Lists default to 100 per page, up to 1,000.

RelatedSnippetsConversationsDrafts

Query parameters

pageinteger

Page number of results to return.

Example 1
pageSizeinteger

Number of results to return per page.

Example 100
translatestring

Set to false to return untranslated shortcut content.

One offalseExample "false"
deletedstring

Filter shortcuts by deletion state.

One oftruefalseallExample "false"
namestring

Case-insensitive prefix filter for shortcut names. For example, follow up matches shortcut names beginning with follow up.

Example "follow up"
appCreatedboolean

Filter shortcuts by app ownership. true returns shortcuts created by apps; false returns shortcuts not created by apps.

Example false
tagIdstring

Filter shortcuts by exact tag ID.

Example "6026aba3fcca5f03e5541cd5"
langstring

Language code used to localize the response.

Example "en_us"

Responses

OK

objectrequired
array<object>required
objectrequired