پایگاه دانش GetMyBot

Campaigns

Multi-step automated subscriber journeys: immutable versions, entry triggers, graph nodes, preflight, publishing, per-version reports, and one journey's trace.

در این صفحه

A campaign runs several steps with pauses and checks. For example, after a customer applies, send course details, check payment the next day, and remind those who have not paid. In the editor, steps are connected on a diagram, or graph. A step is a node; one customer's passage through the diagram is a journey. Campaigns can run for days or weeks. For a single message to a chosen audience, use a broadcast or email campaign.

Versions and the draft

A campaign has one editable draft (draft). Publishing saves an immutable copy, the published version (published), which can later be retired (retired). The version number tells you which rules applied to a customer. The draft contains the entry trigger, audience, settings, and step diagram. The save API uses PUT /draft with expected_revision; if someone else saved changes first, the server returns a conflict. Reload before editing again.

Publishing (POST /publish) freezes the current draft as a new published version and immediately opens the next draft as its copy. A subscriber who entered while version N was published walks their whole path on version N, even after version N+1 is published later: the trigger, audience, settings, and graph an already-running journey is executing never change under it.

The node graph can only be edited while the campaign is stopped: saving a graph while the campaign is Running or Paused is refused: a subscriber may be sitting on exactly that node by its id, and the executable graph must not change under a live subscriber.

Separate from versions, there is cloning: any existing version: a draft, a published one, or a retired one: can be opened as a new draft, replacing whichever draft is currently open. A campaign can also be archived (taken off the active list without deleting its history), but only while stopped.

Entry triggers

  • Manual: no configuration; the editor's "send a test to myself" button takes the same path and runs the entry node immediately, without waiting for the background sweep.
  • Site event: the same client SDK/widget event as in reactions, with the same condition editor. The Email subscription from a popup button selects the server event $email_subscribed, emitted after a new or renewed popup subscription is separately confirmed.
  • Schedule: once, at a fixed instant, or recurring. A recurring schedule is a local time of day (HH:MM) in an explicit IANA timezone: "Local" is refused: an optional weekday filter, and mandatory start_at/end_at no more than two years apart: a recurring schedule must have an end, or a forgotten campaign would sweep the audience forever. A wall-clock moment that does not exist because of a spring-forward transition is simply absent from the schedule by default; the "next valid instant" policy moves it to the end of the gap instead of skipping it.
  • Label changed: one specific label added or removed, never both at once : those are different journeys with different content.
  • Property changed: a transition of one approved profile property from one state to another. The "previous" and "new" conditions are independent and both optional; re-saving the same value is not a transition and never triggers entry.
  • Segment entered: a membership transition from "not a member" to "member" of a ready segment. An ordinary recompute that merely reconfirms existing membership does not count as entry.

Graph nodes

The diagram connects steps with transition lines. A line's label, such as yes or no, shows when that path is taken. There must be exactly one starting step, and every step needs a path to Goal or Exit. An unreachable step or a path without an ending prevents saving. In API terms, steps are nodes and lines are edges. A node's settings may use up to 32 KiB; a campaign may have at most 200 nodes and 400 edges.

  • Message: text/photo/file/delay blocks, run as an ordinary reaction against the same subscriber. AI blocks, a nested reaction, "expected answer" state, and parameter writes with a side effect are not supported here: retrying the node after a failure has to stay safe.
  • Content: unlike "Message", sends one specific published, version- pinned content document on one explicitly named channel (Telegram, VK, WhatsApp, web chat, email, browser push, or mobile push), and never switches channel by itself: an unreachable recipient either takes a separate "when unavailable" branch, if one is wired, or the node fails visibly. Push needs a published Push document. Email needs a published Email document, a subject, and configured delivery.
  • Delay: waits a fixed number of seconds (up to 180 days).
  • Wait for event: waits for a client event by name (up to 64 characters, no reserved $ prefix) with a timeout of up to 180 days; the node has exactly two branches: the default one (the event arrived) and timeout.
  • Condition: branches yes/no on subscriber parameters, time periods, time since last seen, or message count: the same condition vocabulary as reactions.
  • Split: a weighted A/B branch: a subscriber lands in the same branch deterministically, by a hash of the node and their own id, and that does not change on re-evaluation or restart.
  • Experiment: branches on a shared experiment's variant, with a pinned experiment id and version; two to sixteen variants, and every declared variant is a mandatory branch: an unwired variant would silently strand whoever the experiment assigns to it.
  • Channel available: branches yes/no on whether the subscriber can actually be reached right now on one explicitly named channel (email and phone do not qualify: neither is a delivery channel). It exists so an author decides the fallback channel question explicitly, rather than relying on a send silently switching channel on its own.
  • Action: change labels, including temporary labels with ttl_days; change a member's permissions in a named chat (change_rights: ban, unban, remove, approve or decline a join request, mute, unmute, or restrict). The chat_id field is required because a campaign step has no chat of its own. For example, use Delay, then Action → Change rights → Remove from chat to end access a set number of days after a label change. Enter chat_id as a plain number, with no spaces, leading plus sign, or leading zeroes. Supported actions vary by channel; see Permissions by channel. The action can also unset parameters (setting, appending, and incrementing are not supported here: the same retry-safety principle as "Message"); a synchronous web request (no async mode, no nested reaction on success/error; the Idempotency-Key header is reserved: the platform sets it itself and sends the same value when the same step is retried, so your endpoint can use it to drop duplicates, and you cannot set your own); sync to a connected CRM; assign the support dialog to an agent or a group; emit a customer event (the same as a widget track() call: segments, funnels, and a matching trigger will see it); start a lead bot.
  • Goal and Exit: terminal nodes with no configuration: the first is a successful finish, the second is leaving without one.

Two emails after a subscription

  1. Prepare email delivery: a plan with email, a verified sending domain, and a configured delivery method. Create and publish two Email documents in Content Studio.
  2. Create a campaign and select the Email subscription from a popup trigger. In the popup form, add a required email field and a separate consent checkbox, enable email subscription, and select both fields. The address must be verified and linked to the profile; if necessary, the visitor can verify it with a code in the popup. Verification of address ownership alone is not marketing consent.
  3. Connect Content → Delay → Content → Goal. For each Content node, select email as the channel, choose a published document, and enter a subject; the preheader is optional. Configure the unavailable branch and connect it to Exit.
  4. Run preflight, publish, and start the campaign. After submitting the form, the visitor receives a separate subscription email and must follow its link and confirm on the resulting page. Only then is $email_subscribed emitted and the journey can start. An existing active subscription does not emit another event. Make sure the participant has an available email address and is subscribed. Consent and unsubscribes are checked before each send: someone who unsubscribes after the first email will not receive the second. Preflight does not confirm actual delivery.

When saved SMTP settings cannot be used

If the service cannot use the project’s saved SMTP settings when sending an automated email, for example because it cannot decrypt the password, the journey trace asks you to check the project’s SMTP settings. The step waits for a correction without consuming an attempt or charging for that send. It does not switch to the platform server automatically. Check and save the settings in Email; after the correction, the step will be checked again automatically.

If the service cannot connect to the project's SMTP server, establish TLS or authenticate before sending begins, the step also waits for recovery without consuming an attempt or charging for that send. Check the connection and credentials; the service will check again automatically after recovery. Other SMTP errors, including MAIL or RCPT rejection and errors after sending begins, may be handled differently.

Permissions by channel

Before placing a member-permission action in the queue, the platform checks whether the subscriber's channel can perform that action in the named chat. If it cannot, the step fails and the journey stays on that node for another attempt. No partial permission change is made.

  • Telegram supports all eight actions in the explicitly named group, supergroup, or channel where the bot is an administrator: ban, unban, remove, approve or decline a join request, mute, unmute, and restrict.
  • VK can moderate only its own connected community. It supports ban, unban, remove, and approve a join request. chat_id must equal that community's ID, shown under Channels. Another ID is rejected. VK cannot mute, unmute, restrict, or decline a join request.
  • WhatsApp, Instagram Direct, Messenger, email, and the web widget do not support member-permission changes. A change_rights node on these channels always fails.

Preflight and publishing

POST /preflight checks the current draft's shape (the same graph validator that runs on every save) and its cross-entity references: do the named segments, content documents, and experiments actually exist: and sends nothing. The response is ready, the version number, its checksum, and a list of errors with a code (invalid_graph, invalid_reference) and a message. Preflight does not estimate audience size, channel eligibility, or consent: that is out of scope for it.

POST /publish re-runs the same reference checks again, in one transaction: a client that skipped preflight, or whose world changed since, still cannot publish a campaign pointing at a deleted segment or document. Publishing requires the draft's current revision: a stale revision or an already- published draft returns a conflict with no partial result.

Per-version reports and the journey trace

The report (GET /report) is computed per version, not for the campaign as a whole: version N and version N+1 carry different counters, and publishing a new version never shifts an old one's numbers. The report has a journey funnel (entered, active, waiting, on retry, done, exited, failed) and, per node, entered/completed/failed counts. A report is sealed once its version can no longer take a new entrant and no journey on it can move any further: those numbers are stored as final and never recomputed; a live published version's report is always recomputed on read.

One journey's trace (GET /journeys/{subscriberID}/{runNo}) is a bounded event log: entering a node, an effect firing, parking on a wait, leaving a wait, a retry being scheduled, giving up after exhausting attempts, finishing. The trace carries ids, branches, attempt counts, and error codes: never a message body or a provider response: it is an audit of the path taken, not a copy of what was sent. A truncated flag shows a journey exceeded the event cap and part of its history was not kept. A separate list (GET /failures) shows who is stuck, and on which node, after the runner exhausted its attempts; a stuck journey can be retried (POST /journeys/{subscriberID}/{runNo}/retry).

Quiet hours

Each version stores its send-window settings. Enable quiet hours to defer message, content, and channel-availability nodes during the configured weekly intervals or blackout dates. Once the window ends, the runner evaluates the node again; it does not take an unavailable-channel branch merely because the send window is closed.

Choose the bot timezone or recipient timezone. Recipient timezone is currently resolved for browser and mobile push; messenger channels use the bot timezone. A missing recipient timezone also falls back to the bot timezone. For example, a 22:00–08:00 quiet interval postpones a night-time reminder until the window allows it. Re-entry is configured separately on the campaign itself.

Permissions

Personal tokens and roles see campaigns through three separate scopes: campaigns:read, campaigns:write, and campaigns:publish: publishing a version and retrying a stuck journey are kept apart from ordinary draft editing. All three require the "Reactions" bot right: without it, the campaigns section is neither visible nor reachable for reading or writing.

What's next