Appearance
Engagement Studio reference
Engagement Studio reaches customers on a schedule and reacts to what they do. It has four screens, shown under Workspace > Engagement Studio in the Explorer: Journeys, Broadcasts, Audiences and Contact policy. A journey is a flow of steps that runs once for each customer; a broadcast is one message to a list; an audience is a saved group of customers; the contact policy limits how often and when anyone is contacted. For a task-oriented walkthrough see Reach customers with journeys; for the step nodes the journeys compile to see Workflow node reference.
Engagement is its own module with its own database schema (engagement). It uses the workflow, communication and voice engines through their public APIs. If the engine is not deployed in an environment, the screens and the /api/v1/engagement endpoints are not available there.
Journeys
Where to find it
Workspace > Engagement Studio > Journeys. The designer opens from the list.
Journey list
Each row shows the journey name, its status chip and the customers' counters. New journey opens the designer. Statuses:
| Status | Meaning | Transitions |
|---|---|---|
DRAFT | Being designed. Not running. | Publish makes it LIVE. |
LIVE | Published. Can be launched and tested. | Pause, End. |
PAUSED | Customers wait at their next step. | Resume, End. |
ENDED | Customers have left. | None. |
Journey designer
The top bar has the journey name, a code (2 to 60 lower-case letters, digits and dashes; fixed after the first save) and the buttons below.
| Button | Enabled when | Effect |
|---|---|---|
| Save | always | Saves the draft. Refused with Give the journey a name. if the name is empty, or The journey is too large. above 200,000 characters. |
| Check | saved | Lists problems on the steps. Nothing is published. |
| Publish | saved | Compiles the journey to a workflow version. New customers follow this version; customers already inside stay on theirs. Refused until the checks pass. |
| Test on one record | LIVE | Starts the journey for one record id you enter. |
| Launch | LIVE | Starts the journey for the audience's customers. |
| Pause, Resume, End | by status | Changes the status as in the table above. |
The counters above the canvas show Entered, On their way, Finished, Left early and Failed. Each step also shows how many customers reached it, are waiting there, went each way, or failed.
Describe the journey drafts a whole journey from a goal of 15 to 2,000 characters (POST /api/v1/engagement/journeys/draft). The draft uses only the message templates, voice agents, prompts and record types that exist in the workspace; anything the model could not decide is returned as notes. Nothing is saved until you save it.
Journey settings
| Field | Description |
|---|---|
| Audience | The saved audience the journey starts from. |
| Acts as (user) | The user the journey sends, calls and writes records as. Publishing is refused until one is chosen: Choose the user the journey acts as (it sends, calls and writes records as them). |
| Time zone | Used for quiet hours. |
| Quiet from, Quiet until | HH:mm. A step that falls inside quiet hours waits until they end. |
| A customer may enter again on a later launch | Allows re-entry (reentry). Off by default. |
Steps (tiles)
Steps are added with the "+" between two steps. Every step has a Name on the canvas. Steps that branch show one column per outcome.
| Step | Group | What it does | Fields |
|---|---|---|---|
| Message | Reach | Sends a template on a channel. Runs as engage.message. | Channel (E-mail, SMS, WhatsApp, Push, In-app); Template code (a template from Communications for the channel; WhatsApp needs a Meta-approved template); Language; Subject (e-mail only, optional). |
| Voice call | Reach | An AI voice agent calls; branches on the call outcome. Runs as engage.voice. | Voice agent (voice must be on for it); What the call is about; Calling line (+..., optional); Wait for the call's result (minutes). Branch on <step id>_intent (the agent's outcomes), <step id>_outcome or <step id>_status such as NO_ANSWER. |
| Wait | Wait | A fixed time or until a date. Runs as timer.delay or timer.until. | Days, Hours, Minutes; or Until (a date, or ${context.field}). |
| Wait for reply | Wait | Until the customer replies on any channel or the time is up. Runs as engage.wait-reply. | Wait up to (hours). Result <step id>_replied. |
| Condition | Decide | Branches on the customer's data or an earlier step's result. | Branches (below). |
| AI decides | Decide | A prompt reads the customer and picks a branch. | Prompt code (it must answer in JSON); Answer field the branches read. |
| Create record | Act | Creates a record of any entity. | Entity; Values, one per line as field=value, where values may use ${context.customer_name} and similar. |
| Update record | Act | Changes a record. | Entity; Record id; Values as above. |
| Notify a person | Act | An in-app message to a colleague. | Who (user id; several separated by commas); Subject; Message. |
| Exit | End | The customer leaves here. | Why the customer leaves (shown in the results). |
Branches. Under a step that branches, each branch has a name and, except the last, a rule: Value (a customer field or an earlier step's result), Is (is, is not, more than, less than, at least, at most, contains, is one of, is empty, has a value) and Compared with. The first branch whose rule matches is taken. Add "otherwise" adds the branch with no rule, which is taken when none matches.
Checks
The Check button and Publish report problems on the step that has them, for example a message without a template, a voice call without an agent, or a branch with no path.
Runtime
- Publishing compiles the tiles into workflow stages and transitions; each customer who enters gets one workflow run. Step results are written both as
context.<step>and as flat keys<step>.<field>, which is what branch conditions read. - Waiting never holds a thread. Timers, replies and calls put the task back in the queue (
TaskDeferredException), so journeys survive restarts and scale across workers. - Before every message or call the contact policy is asked.
- A customer who has already joined a journey cannot join it again unless re-entry is on.
- Engagement workflow nodes need a workflow worker for the tenant. Without one, launched journeys do not progress.
Permissions
The resource is engagement. view reads; manage saves, publishes, launches, pauses and deletes. A bot or API caller without the right is refused with actor "<name>" lacks engagement.<action> permission (HTTP 403).
API and CLI
| Action | Endpoint | CLI operation |
|---|---|---|
| Overview | GET /api/v1/engagement/overview | engagement-overview |
| List, read | GET /api/v1/engagement/journeys, GET /api/v1/engagement/journeys/{code} | engagement-journeys, engagement-journey |
| Save | PUT /api/v1/engagement/journeys/{code} with name, description, definition, audienceCode, runAs | engagement-journey-set |
| Draft with AI | POST /api/v1/engagement/journeys/draft with need | engagement-journey-draft |
| Check, publish | POST .../{code}/check, POST .../{code}/publish | engagement-journey-check, engagement-journey-publish |
| Launch, pause, resume, end | POST .../{code}/launch, POST .../{code}/{pause|resume|end} | engagement-journey-launch, -pause, -resume, -end |
| Customers in a journey | GET .../{code}/members | engagement-members |
| Delete | DELETE /api/v1/engagement/journeys/{code} |
Limits and behaviour
- A journey definition is limited to 200,000 characters.
- Journeys, audiences and the contact policy can move between environments; see Move definitions between environments. A journey installs as a draft with nobody chosen to act.
- Not built: A/B split steps, send-time optimisation and journeys started by an anonymous website visitor. Journeys start from records.
Broadcasts
Where to find it
Workspace > Engagement Studio > Broadcasts.
A broadcast sends one message to a list of people, once or repeating, inside a sending window in a time zone. It is a message campaign of the communication engine and starts by itself at its time. For anything with steps, waits or branches use a journey.
New broadcast
| Field | Type or values | Description |
|---|---|---|
| Name | text | Required. |
| Channel | EMAIL, SMS, WHATSAPP, PUSH, IN_APP | |
| Template code | text | A template from Communications for the channel. |
| Subject | text | E-mail only. |
| First send | date and time | When the first round starts. |
| Time zone | IANA zone | Defaults to the browser's zone, or UTC. |
| Send from, Until | HH:mm | The sending window. Outside it, messages wait. |
| Days | for example MON,TUE | Days of the week the window applies to. |
| Repeat | ONCE, DAILY, WEEKLY, MONTHLY | |
| Rounds | number | Only for repeating broadcasts: the maximum number of rounds. |
| Who | one address per line, comma or semicolon separated | Phone numbers and e-mail addresses as they are; for in-app, user ids. |
Schedule creates the broadcast, adds the recipients and launches it.
List
Each broadcast shows its name, a status chip (DRAFT, SCHEDULED, RUNNING, COMPLETED, CANCELLED), the channel, template, number of people, repeat and, for repeating ones, the current round. Cancel is offered while it is DRAFT, SCHEDULED or RUNNING.
API
GET /api/v1/communications/campaigns lists broadcasts; creation, recipients, launch and cancel use the same communication campaign endpoints. There is no named CLI operation; use erp api.
Limits and behaviour
The contact policy applies to broadcasts as to journeys. Recipients without an address are skipped.
Audiences
Where to find it
Workspace > Engagement Studio > Audiences.
An audience is a saved group of customers: a record type plus filters, with a live count and a preview.
Fields
| Field | Description |
|---|---|
| Name | Required. |
| Code | 2 to 60 lower-case letters, digits and dashes. Fixed after the first save. |
| Customers are records of | The entity the customers are records of. The code is validated as a name that starts with a letter (Choose the entity the customers are records of.). |
| Only customers where (all must hold) | Filters, each with Field, Is (an operator) and Value. All filters must hold. |
| Phone field, E-mail field, Name field | The fields that hold the phone number, the e-mail address and the display name. At least one of phone or e-mail is required: Choose the field with the phone number or the e-mail address. |
Filter operators are eq, neq, gt, lt, gte, lte, contains, in, isEmpty, isNotEmpty. A filter field must be a plain field name ("<name>" is not a field name.).
Preview
The preview counts people as the asking user sees the records. It returns the count, whether the cap was reached, how many have a phone and how many an e-mail, and a sample of ten. An audience resolves to at most the platform cap per launch.
Deleting
An audience used by a LIVE journey cannot be deleted: A live journey uses this audience.
API and CLI
| Action | Endpoint | CLI operation |
|---|---|---|
| List | GET /api/v1/engagement/audiences | engagement-audiences |
| Save | PUT /api/v1/engagement/audiences/{code} | engagement-audience-set |
| Preview | POST /api/v1/engagement/audiences/preview | engagement-audience-preview |
| Delete | DELETE /api/v1/engagement/audiences/{code} |
Permission: engagement.manage to save and delete, engagement.view to preview.
Contact policy
Where to find it
Workspace > Engagement Studio > Contact policy.
One policy per workspace is checked before every message and call, whatever started it (journey, broadcast or bot).
Limits and quiet hours
| Field | Default | Description |
|---|---|---|
| At most (contacts per customer) | none | Maximum contacts per customer in the period. Empty means no limit. |
| In (days) | 7 | The period. |
| Quiet from, Quiet until | none | HH:mm. Inside quiet hours a step waits until they end. |
| Time zone | UTC | The zone of the quiet hours. |
Do-not-contact list
| Field | Description |
|---|---|
| Phone (+...) or e-mail | The address, stored normalised. |
| Channel | A channel, or all. |
| Reason | Free text. |
Entries have a source: the customer asked, an administrator added it, or a call outcome. Removing an entry re-allows contact.
May I contact
A check form: enter a phone or e-mail and a channel and see whether contact is allowed and why not. The reasons are: on the do-not-contact list, over the contact limit, or inside quiet hours.
API and CLI
| Action | Endpoint | CLI operation |
|---|---|---|
| Read, save the policy | GET, PUT /api/v1/engagement/contact-policy | engagement-contact-policy |
| Do-not-contact list | GET, POST /api/v1/engagement/do-not-contact, DELETE .../{id} | engagement-dnc |
| Check | POST /api/v1/engagement/contact-check |
Limits and behaviour
- The policy is a compliance setting. Installing definitions from another environment never overwrites an existing policy.
- WhatsApp messages to someone who has not written first need a template approved by Meta; Spark sends what the provider allows and records the attempt in the contact log.
Related
Reach customers with journeys, Workflow node reference, Bots and voice, Move definitions between environments.