Message types | Knock Docs

In-app UI

Message types

Message types map the components in your application to the guide editing experience in Knock.

A message type maps to a UI component/element in your product that you show to your users.

Once a message type exists, you can use it to create guides to render non-feed messages in your product.

Overview

A message type has:

A schema. A schema defines the fields a message type will have in the template editor and forms the structure of the message contents returned by the guides API.
At least one variant. Message types can have one or more variants.
A template preview. A template preview is a visual representation of what the message type will look like in the template editor.

Variants

A message type can have one or more variants. For example, the card template type comes with 3 variants:

Default. Content with an action URL to determine where the cell should route to.
Single action. Content with a single primary button.
Multi-action. Content with two buttons, one primary and one secondary.

When creating an in-app template, your content editors can select from the available variants and customize the message's contents based on the selected variant.

Schemas

A message type has a schema that defines the fields a message type will have in the template editor and forms the structure of the message contents generated when a message is produced from an in-app step.

You can think of the schema as a blueprint for how the content editor will create the message template and what fields can be edited within that experience.

As an example, the Banner schema is defined as:

If the editor creates an in-app message template using the “default” variant for this component, then the structure of a generated message’s content will be:

Template previews

A template preview is a visual representation of what the message type will look like in the template editor.

You draft template previews using HTML, CSS, and Liquid.

You can reference variables from your schema to customize the preview, like this:

You can also reference variant keys to customize the preview based on the variant that is selected in the template editor, like this:

Pre-built message types

Knock comes with the following pre-built messages types to use out-of-the-box, each of which maps to a component you’ll find in @knocklabs/react.

Banner (<Banner />)
Modal (<Modal /> )
Card (<Card />)

Headless message types

You can also create your own message types that map to your own UI components.

An in-app message schema has the following structure:

Variants

Your schema must have one or more variants. Each of these variants must have:

A key uniquely identifying the variant for the message type
A name to display in the message template editor to select the variant
One or more fields (see below)

Every schema must define a variant with the key "default". You can name your variants anything you would like, but the variant key must be unique.

Fields

All fields must have:

type: The type of the field to render (see below)
key: A unique key for the field in the variant
label: A label to render

Field types

A plain text, single line text field.

Settings

required (boolean): Indicates this field is required
description (string): An optional friendly description
default (string): The default value to display
minLength (integer): The minimum length to validate
maxLength (integer): The maximum length to validate against

Example

A markdown editor for creating rich text. Will always be rendered as HTML.

Settings

required (boolean): Indicates this field is required
description (string): An optional friendly description
default (string): The default value to display

A multi-line plain text area

Settings

required (boolean): Indicates this field is required
description (string): An optional friendly description
default (string): The default value to display
minLength (integer): The minimum length to validate
maxLength (integer): The maximum length to validate against

Example

A checkbox that returns either true or false (checked or unchecked).

Settings

required (boolean): Indicates this field is required
description (string): An optional friendly description
default (boolean): The default value to set

Example

A single select box that defines a static list of options for editors to pick from.

Settings

options (object[]): A list of option objects that must include a label and a value
required (boolean): Indicates this field is required
default (string): The value of the default option to set

Example

In your template preview, you can access the value of the selected option using the field's key. For example:

A multi-select box that defines a static list of options for editors to pick from.

Settings

options (object[]): A list of option objects that must include a label and a value
required (boolean): Indicates this field is required
default (string[]): The values of the default options to set

Example

In your template preview, you can access the selected values using the field's key. For example:

A button, with text to display and an action to perform when clicked.

Every button field contains two subfields:

text: A text field that represents the button's text
action: A text field that represents the button's action

Settings

required (boolean): Indicates this field is required
description (string): An optional friendly description

Example

Settings

required (boolean): Indicates this field is required
description (string): An optional friendly description
default (string): The default URL to display

Example

An image field, used to display an image with alt text and an optional action to perform when clicked.

Every image field contains three subfields:

url: A URL field that represents the source of the image to be displayed
alt: A text field that represents the image's alt text
action: An optional text field that represents an action to perform when the image is clicked

Settings

required (boolean): Indicates this field is required
description (string): An optional friendly description

Example

Versioning message types

Message types are versioned using Knock’s commit model, meaning changes to a message type schema are committed into the current environment.

When you make an update to a message type, any templates using that message type will continue to use the old version until you explicitly update the template to use the new version. You can do this by navigating to the template in the Knock dashboard and clicking the "Update" button.