In-app UI
Message types

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.

In-app message types

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 />)
Pre-built components

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. You can name your variants anything you would like, but the variant key must be unique.

Each variant 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)

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

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

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.