Templates mAPI reference
Complete reference documentation for the Templates resource.
Templates
#Templates represent the templated contents of a message sent to an individual recipient on a specific channel.
There are no endpoints for working directly with templates, instead you must do so through modifying a workflow.
Endpoints
Preview a template
#Renders a template preview, without requiring a template to be persisted within Knock. This is useful for previewing templates in isolation, without the need to use a workflow.
For email templates, you can optionally specify a layout by key or provide inline layout content.
Endpoint
Query parameters
The environment slug.
The slug of a branch to use. This option can only be used when environment is "development".
Request body
The channel type of the template to preview.
The data to pass to the template for rendering.
Email layout configuration. Only applicable for email channel type. Falls back to environment default if not provided.
Inline HTML content for the layout. Must include {{ content }} placeholder.
The key of an existing email layout to use.
Inline text content for the layout.
A recipient reference, used when referencing a recipient by either their ID (for a user), or by a reference for an object.
The template content to preview. Structure depends on channel_type.
The tenant to associate with the preview. Must not contain whitespace.
Optional workflow context for variable hydration. When provided, recipient/actor/tenant are resolved via Knock.
Workflow categories.
Whether the workflow is marked as commercial messaging.
The workflow key.
Whether to ignore recipient preferences for a given type of notification. If true, will send for every channel in the workflow even if the recipient has opted out of a certain kind. Defaults to false.
Returns
A response to a template preview request.
The content type of the preview.
A list of errors encountered during rendering. Present when result is "error".
The template field that caused the error, if available.
The line number where the error occurred, if available.
A human-readable description of the error.
The result of the preview.
The rendered template, ready to be previewed.
ChatTemplate
#A chat template.
Attributes
A JSON template for the chat notification message payload. Only present if not using the markdown body.
The markdown body of the chat template.
The summary of the chat template. Used by some chat apps in their push notifications.
EmailTemplate
#An email message template.
Attributes
An HTML or MJML template for the email body. Required if visual_blocks is not provided. Only one of html_body or visual_blocks should be set. When is_mjml is true, this must contain MJML components. Supports Liquid templating with variables like {{ recipient.name }}, {{ actor.name }}, {{ vars.app_name }}, {{ data.custom_field }}, and {{ tenant.name }}. See the template variables reference for available variables.
Whether this template uses MJML format. When true, the template content will be compiled from MJML to HTML. Only valid when the selected layout is also MJML or when no layout is selected.
The settings for the email template. Must be supplied with at least layout_key.
The object path in the workflow trigger's data payload to resolve attachments.Defaults to attachments.
The key of the email layout that wraps the email template. When omitted, the email template will need to define the <html> structure.
A liquid template that will be injected into the email layout above the message template content. Useful for setting variables that should be available to the email layout.
The subject of the email. Supports Liquid templating with variables like {{ recipient.name }}, {{ actor.name }}, {{ vars.app_name }}, {{ data.custom_field }}, and {{ tenant.name }}. See the template variables reference for available variables.
A text template for the email body. When omitted, the email template will be autogenerated from the html_body or visual_blocks.
The visual blocks that make up the email template. Required if html_body is not provided. Only one of html_body or visual_blocks should be set.
PushTemplate
#A push notification template.
Attributes
The settings for the push template.
The delivery type of the push notification. Set as silent to send a data-only notification. When set to silent, no body will be sent.
A JSON object that overrides the payload sent to the push provider.
The body of the push notification.
The title of the push notification.
SmsTemplate
#An SMS template.
Attributes
The settings for the SMS template. Can be omitted.
The message of the SMS.
InAppFeedTemplate
#An in-app feed template.
Attributes
The action buttons of the in-app feed message.
The URI for this action.
The label of the action button.
The URL to navigate to when the in-app feed is tapped. Can be omitted for multi-action templates, where the action buttons will be used instead.
The markdown body of the in-app feed.
RequestTemplate
#A request template for a fetch function step.
Attributes
The body of the request. Only used for POST or PUT requests.
The headers of the request. Can be a template string or a list of key-value pairs.
The HTTP method of the request.
The query params of the request. Can be a template string or a list of key-value pairs.
The URL of the request.
WebhookTemplate
#A webhook template. By default, a webhook step will use the request settings you configured in your webhook channel. You can override this as you see fit on a per-step basis.
Attributes
The body of the request. Only used for POST or PUT requests.
A list of key-value pairs for the request headers. Each object should contain key and value fields with string values.
The key of the header.
The value of the header.
The HTTP method of the webhook.
A list of key-value pairs for the request query params. Each object should contain key and value fields with string values.
The key of the query param.
The value of the query param.
The URL of the webhook.