Create snippet
/v1/snippetsorg.permission.snippet.createThe API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.
Creates a new snippet document.
Snippets
A snippet is a piece of text stored once with a translation for each language, such as a greeting or a policy sentence. Shortcuts, chat settings and other customer-facing text reference it by key, and Kustomer fills in the right language when the text is shown.
Snippets are how Kustomer translates text that your team writes. Rather than putting a sentence directly into a shortcut or the chat widget's greeting, you create a snippet with one value per language and reference it by key, in double square brackets: [[sn.org.chat.greeting]]. When the text is shown, Kustomer replaces the reference with the snippet's value in the requested language, and falls back to the snippet's source language if there's no translation. Editing the snippet updates every place that uses it. Admins manage snippets on the snippets page of the Kustomer admin settings, and Kustomer also provides built-in snippets with keys starting sn.kustomer., such as the default text of knowledge base themes.
Snippets and shortcuts
The two work together but do different jobs. A shortcut is a whole reply an agent inserts into a conversation, with placeholders for customer and conversation data and optional actions on the conversation. A snippet is a single translated string with no logic, which shortcuts, chat settings and other text can include. Use a snippet when the same words must appear in several places or in several languages, and a shortcut when an agent needs a ready-made reply.
Key fields
| Field | Meaning |
|---|---|
key |
The identifier used in [[...]] references. Kustomer generates it from category and name when you create the snippet, as sn.org.<category>.<name> in snake case, adding a number if that key is taken. It doesn't change when you rename the snippet. |
name, description |
Labels for the people managing snippets. name is required. |
category |
A label for grouping snippets, which also becomes part of the key. |
source |
The language the snippet was written in, such as en_us. It must be one of the org's languages and defaults to the org's default language. |
langs |
The text, keyed by language code: { "en_us": { "value": "Go back", "outdated": false }, "es": { "value": "Volver", "outdated": false } }. Each entry needs both value and outdated. |
Which endpoint to use
| To | Call |
|---|---|
| List the org's snippets | GET /v1/snippets |
| Create a snippet | POST /v1/snippets |
| Read a snippet by ID or by key | GET /v1/snippets/{id} |
Replace a snippet's fields, or delete it with deleted: true |
PUT /v1/snippets/{id} |
| Add or change some translations, keeping the rest | PATCH /v1/snippets/{id} |
The difference between the two updates is langs: PUT replaces the whole langs object, so any language you leave out is removed, while PATCH merges the languages you send into the existing ones. There is no DELETE endpoint; PUT with deleted: true marks the snippet deleted, and the list endpoint still returns snippets deleted this way. Pass lang (one code or a comma-separated list) to return only those languages, which keeps responses small, and fields on the single-snippet endpoint to choose attributes. Agents with snippet read access can read snippets, but creating or changing them requires an admin role with permission to manage snippets.
Request body
application/jsonrequiredResponses
Created