Skip to content

Channel steps

The channel steps are in_app, email, push, chat and sms. Each renders its templates, applies the gates (condition, throttle, preferences), sends, and records a message. The stream step has its own page.

Fields below go in the step’s controlValues. Text fields are templates. Every field is optional at the API level, but a step with an empty body sends an empty body.

Email, push, chat and SMS steps also accept:

FieldMeaning
integrationThe identifier of a specific integration to send through. Empty means the channel’s primary integration.

in_app

Writes a message to the subscriber’s inbox. Nothing is sent externally; the message is readable at GET /v1/messages and is pushed to open inbox streams.

FieldMeaning
subjectTitle.
bodyMessage body. Values are inserted as sent: the inbox treats the text as text, so a client must not render it as HTML.
avatarAvatar URL.
redirect{"url": "...", "target": "_self"}. url is required when redirect is present; target is one of _self, _blank, _parent, _top.
primaryAction, secondaryActionCall-to-action buttons: {"label": "...", "redirect": {"url": "...", "target": "..."}}. redirect is optional.
dataA free-form JSON object delivered with the message.
layoutKeyA layout to wrap the body in.

avatar, redirect, the actions and data are stored on the message under extras.

email

Sends to the subscriber’s email address.

FieldMeaning
subjectSubject line. Always inserted as plain text.
bodyThe body. By default it is the plain-text part.
editorType"html" sends body as an HTML body and escapes inserted values for HTML. Anything else (or absent) sends plain text.
htmlBodyAn HTML alternative. When set, body is the plain-text part, htmlBody the HTML part, and the message goes out as multipart/alternative.
layoutKeyA layout to wrap the body (or htmlBody) in.
fromOverrides the integration’s From address.
replyToSets Reply-To.
replytrue opts the message into reply-to-notification: notify sets Reply-To to a tokenized mailbox on one of your verified inbound domains, and a reply is delivered to your outbound webhooks as an email.reply event. If inbound is not available for the scope, the message is sent without it. If arming the reply fails, the send fails. Default false.

push

Sends through the active push integration. The target is the subscriber’s address for that provider; see push addressing.

FieldMeaning
subjectTitle. (title is accepted as an older spelling.)
bodyBody.
priorityInteger 1 (min) to 5 (max); 0 or absent uses the provider default. ntfy.
tagsArray of strings. ntfy.
markdowntrue to render the body as Markdown. ntfy.
data_jsonA JSON object whose values are all strings, as a string, for example "{\"screen\":\"inbox\"}". Forwarded as native data to FCM and Expo (deep links, badges). Anything else is rejected with data must be a JSON object with string values only.

For Web Push, the notification is sent to every browser subscription the subscriber has registered.

chat

Posts to a chat provider. The address comes from the subscriber’s channel credentials; see chat addressing.

FieldMeaning
bodyMessage text. Escaped for the destination: HTML for Telegram messages, mrkdwn escapes for Slack, plain for the rest.
integrationAs above.

A Telegram subscriber with no chat_id is a permanent failure for that step.

sms

Sends body to the subscriber’s verified phone. Only the subscriber can verify a phone, with a code texted to it (phone verification). A phone you set through the API is stored but never texted. A subscriber with no verified phone gets the step skipped with skipReason: "no_verified_phone"; the run carries on and nothing is an error.

FieldMeaning
bodyMessage text, inserted as plain text. Keep it short; carry a link, never a secret. The link should still require the person’s own session.
integrationAs above.
defaultEnabledtrue sends to a subscriber who has no SMS preference for this workflow. Default false: SMS is off unless the subscriber turned it on. Set it on workflows that must reach a phone, such as sign-off requests.
{ "stepId": "text", "type": "sms", "controlValues": { "body": "Sign-off needed: {{payload.link}}", "defaultEnabled": true } }

Inline throttle

Any channel step can also carry a throttle in its controlValues:

{ "body": "…", "throttle": { "limit": 5, "windowSec": 3600 } }

Over the limit, the step records a message with status throttled and sends nothing; the run continues. This differs from the standalone throttle step, which fails the whole run.

What gets recorded

Each channel step writes one message: channel, provider id, integration id, rendered subject and content, a status of sent, error, skipped or throttled, errorText and errorClass or skipReason where they apply, and the seen, read and archived flags. Terminal statuses are also published as delivery events for analytics, the console’s live activity view and outbound webhooks.