Sequences API - Open.cx Docs

A sequence is a multi-step outbound journey. Each person enrolled in it walks the steps in order, on the channel each step names (WhatsApp, an AI phone call, or email), waiting the step’s delay between messages, and leaves the journey the moment they engage. The engine tracks every person individually, so a sequence is both a plan and a live record of what happened to each contact. Every endpoint here is scoped with sequences:read or sequences:write. Two exceptions are called out below: audience discovery returns contact data and needs contacts:read, and reply previews need chat-sessions:read.

Lifecycle

A sequence has three stored statuses:

Status	Meaning
`draft`	Being authored. People can be enrolled and reviewed; nothing is sent.
`active`	Launched. Eligible people are armed and sent; new enrollees arm immediately.
`paused`	Sending is stopped. Everyone keeps their place and resumes from the same step.

Launch moves draft to active and arms every eligible candidate. Launching an already active sequence is idempotent: it only arms candidates added since. Launching a paused sequence is refused, resume it instead.
Pause and resume only touch the sequence itself. People keep their cursors; on resume, overdue steps go first.
There is no stored “done”. finished on the stats is derived (nothing left in flight and something already went out), so enrolling more people revives a finished sequence with no status change.

Recommended flow

The API is built for enroll first, author later: land a real audience, then write the steps for it.

Create the shell

Create with a name and a plain-text brief. Steps can wait.

Enroll people

Add contacts by contact id, phone, email or WhatsApp user id, with any facts you know about them in extra_data. Read the per-person outcomes; a successful call never implies everyone was enrolled. Use batch_key to label the wave. List contacts to review who landed.

Author steps and bind senders

Set steps on the draft. Set senders per channel; the email and voice catalogs tell you which senders are eligible and why not.

Preview, then launch

Launch preview mirrors launch clause for clause: who would start, who is held and why, and what would refuse the launch. Then launch.

Keep feeding it

Keep calling add contacts. On an active sequence with steps, new people arm the moment they are enrolled, so a CRM can push leads without anyone pressing launch again. Remove a person to stop every remaining step.

People

Every person in a sequence has one status:

Status	Meaning
`candidate`	Enrolled, not armed. Drafts hold everyone here; on an active sequence this is someone held back by a qualification verdict.
`active`	Armed. The engine sends their next step when it becomes due.
`parked`	Waiting on a human. `park_reason` says what to fix; the journey resumes where it stopped.
`exited`	Journey over. `exit_reason` is `replied` (they engaged) or `suppressed` (every channel they could be reached on is blocked).
`completed`	Every step went out and nobody replied.

Park reasons are always something a person must fix: needs_data (a step variable has no value and no fallback), unsendable_person (their own data cannot go on the wire), or template_broken (the step’s template is missing, rejected or mismatched for everyone). A removal through exit contact is a deletion, not an exit reason. The person leaves every read, and adding them again later starts them fresh from the first step. What was already sent is kept. Each person also carries a journey: one stamp per step (not_reached, waiting, parked, deferred, skipped, sent, delivered, read, replied, answered, no_answer, busy, failed) with the inbox session of the send when one exists. For the raw event log behind those stamps, read contact events.

Enrollment outcomes

Add contacts answers per person, index-aligned with what you sent:

Outcome	Bucket	Meaning
`enrolled`	enrolled	New row created.
`updated`	enrolled	Existing candidate refreshed, or a parked person given new data and returned to candidate.
`already_enrolled`	noop	Already active or completed here, or parked with nothing new supplied.
`skipped_previously_exited`	not enrolled	They exited this sequence before. An exit is terminal; enrolling never restarts a concluded journey.
`skipped_suppressed`	not enrolled	Every channel they could be reached on is on the outbound blocklist.
`skipped_active_elsewhere`	not enrolled	Active in another sequence (setting `block_active_elsewhere`, on by default).
`skipped_contacted_before`	not enrolled	Some sequence already messaged them (setting `block_contacted_before`, on by default).
`no_identity`	not enrolled	No valid phone, email or WhatsApp user id after normalization. `detail.dropped` names what was rejected.
`extra_data_too_large`	not enrolled	The `extra_data` bag exceeds its budget. Nothing written; trim and retry that person.
`conflict`	not enrolled	The handles match two different existing people. `detail.matches` carries their contact ids.
`error`	not enrolled	This row failed unexpectedly. The rest of the batch is unaffected; retry that person.

Phone numbers must be in international format, emails are lowercased, and duplicates inside one call are reported with detail.in_batch.

Steps

A step is a channel, its content, and delay_minutes: how long to wait after the previous step actually sent. The first step must have a delay of zero because launch and enrollment arm it, not a timer.

WhatsApp step

References an approved message template by template_name and template_language. variables is keyed by the template’s positional index ("1", "2"), each bound to a person column (display_name, phone, email) with an optional fallback. No value and no fallback parks the person; the engine never sends generic filler. A template still under review does not block a launch: armed people wait and send the moment it is approved. A rejected or disabled template refuses the launch.

Voice step

The call brief: extra_instructions rendered per person and handed to the bound phone agent as call-only guidance. The agent carries the persona (voice, language, tone, tools); the step never overrides it. Both fields are optional for an agent whose persona already holds the whole mission. One step is one dial attempt per person, ever: to retry no-answers, author further voice steps with delays. An answered call is the reply and exits the journey.

Email step

Inline subject, html and text (all three required). Every {{name}} placeholder must have a binding in variables; an unbound placeholder is refused at authoring time rather than shipped. {{signature}} is a system token filled from the sending mailbox and needs no binding.

Drafts take a full step list through set steps. Once launched, use edit steps: content and delay updates are allowed on any step (people already past it keep what they received), appends are always allowed, and removing a step somebody already reached is refused. Changing a step’s channel is a remove plus an append.

Senders

Each channel needs at least one bound sender before launch: WhatsApp numbers, AI phone agents for calls, mailboxes for email. Set senders replaces the binding for one channel. Unbinding the last sender of a channel while an active sequence still has sends pending on it is refused; pause first. The email and voice catalogs report eligibility and the reason when a sender cannot be bound. Email health numbers are information beside eligibility, never a gate.

Settings

Setting	Default	Effect
`block_active_elsewhere`	on	Skip people currently active in another sequence.
`block_contacted_before`	on	Skip people any sequence already messaged.
`respect_office_hours`	on	Send only inside the send window. Off means send any time.
`office_hours_id`	org default	A named office-hours schedule to use instead of the org default. Null on update clears it.

Settings are read live by the engine, so a change applies to the next send decision in any status.

Qualification

A sequence can also carry qualification criteria and run an enrich and judge pass over its people. Those endpoints exist for the assistant-driven authoring flow and are not needed to run a sequence from the API: people you enroll and never judge always arm. The endpoint pages under Qualification describe them. The engine enforces the outbound blocklist at enrollment, at launch, and again before every single send. If the blocklist cannot be read, the send is held rather than released.

Available endpoints

Create sequence

Create a draft with brief, criteria and settings

List sequences

Every sequence with its live numbers

Get sequence

One sequence’s definition

Update sequence

Name, brief, criteria, reply instructions, settings

Set steps

Replace the step list of a draft

Edit steps

Update, append or remove steps in any status

Update step delay

Change one step’s wait

Add contacts

Enroll people with per-person outcomes

List contacts

Paginated people with status, fit and journey

Get contact

Full judgment and enrichment for one person

Get contact events

The per-person ledger

Update contact

Correct a name or handle

Include anyway

Override a below-cutoff judgment

Remove contact

Stop every remaining step for one person

Launch preview

What launching would do

Launch

Arm eligible candidates

Pause

Stop sending, keep places

Resume

Make people sendable again

Get stats

Numbers plus who is stuck and why

List replies

Who answered, newest first

List senders

Senders bound per channel

Set senders

Replace one channel’s senders

List email senders

Mailboxes with eligibility and health

List voice senders

Phone agents with eligibility and persona

Enrich contacts

Snapshot what the org knows about people

Judge contacts

Score people against the criteria

List qualification runs

Enrich and judge runs, latest first

Get qualification run

One run’s counts and aggregates

Set columns

Project evidence into the People table

Enrichment catalog

Paths a column may project

Discover contacts

Find an audience from what customers said

​Lifecycle

​Recommended flow

​People

​Enrollment outcomes

​Steps

​Senders

​Settings

​Qualification

​Consent

​Available endpoints