> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useboom.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Initiatives
> One outreach mission: who you reach, what the agent is trying to accomplish, and what it comes back with.
An initiative is one mission you send the agent on. It holds the objective, the
briefing the agent works from, the people it reaches, the template it opens with,
and the [fields it should extract](/extraction) from every conversation. Almost
everything else in these docs hangs off one.
What the mission is, is your call. A win-back, a support follow-up, an onboarding
nudge, a research round, a qualification pass. Boom does not ask you to pick a
category, and nothing in the API changes based on the job you have in mind. The
objective and the briefing are what make it that job.
## The fields that decide quality
Only `name` is required. In practice three fields decide whether the
conversations are any good, because they go straight into the agent's prompt:
| Field | What it does |
| - | - |
| `objective` | What the agent is trying to accomplish. One goal, stated plainly, not a topic and not a question list. |
| `context` | A Markdown briefing, up to 20,000 characters: who these people are, what happened before this conversation, what is true about your business that the agent needs. |
| `guidingQuestions[]` | What every conversation should come back having covered. The agent decides how and when to ask, and follows up on its own. |
The rest tune behavior:
| Field | What it does |
| - | - |
| `language` | Defaults to `es`. |
| `channel` | Read-only in practice: **what an initiative sends on is decided by its [journey](/journeys)**, not by this field. Responses report `channel` as the identifier people are reached by — `EMAIL` when the journey only mails, `WHATSAPP` when anything phone-shaped sends — and `sendChannels` as the full list (including SMS and the Meta DMs, which `channel` cannot express). The value you pass at creation is only used until the initiative has a journey. |
| `maxAttempts` | Outreach attempts per participant when someone does not answer, 1 to 5, default 3. Size the [journey](/journeys) you build to match it, with one approved follow-up template per extra round. |
| `isRecurring` | Keeps processing participants you add later, on a schedule, instead of ending after one pass. Default false. |
| `transactional` | Creates a Transactional instead of a campaign or initiative: one event sends a WhatsApp and/or email template: one notification per event, or one per value of `parallelRunsBy` when you set it. Pass `whatsapp` (`templateId` and `channelId`), `email` (`templateId`), or both, and optionally the rest of the setup in the same object: `eventName`, `parallelRunsBy` and the variable bindings (`whatsapp.templateBindings`, `email.bindings`). See [Send transactional messages](/transactional-messages#do-it-from-code-or-an-agent). You cannot combine it with `isRecurring: true`; that request is refused with `400 transactional_not_recurring`. A request that cannot be set up, such as an unapproved template, is refused with `422 transactional_not_ready`. `GET /api/v1/initiatives/{id}/transactional` returns its setup and what still blocks launch; `PATCH` the same path changes it. |
| `campaign` | Creates a one-time campaign: one email and/or WhatsApp message to an audience, once, at `sendAt`. Pass `audience` (`{ "kind": "manual" }` for people you add, or `{ "kind": "segment", "segmentId", "readAtSend" }`), `sendAt` (omit or `null` to send when scheduled), `email` and/or `whatsapp`, and optionally `reviewBeforeSending`. The journey is built for you. You cannot combine it with `isRecurring: true` (`400 campaign_not_recurring`) or with `transactional` (`400 campaign_and_transactional`). A campaign that cannot be set up, such as a send time in the past, is refused with `422 campaign_not_ready`. Campaigns are being enabled organization by organization; until yours has them, the request is refused with `400 campaigns_unavailable`. `GET /api/v1/initiatives/{id}/campaign` returns its setup and what still blocks scheduling; `PATCH` the same path changes it. See [Campaigns](/campaigns). |
| `flagCondition` | A condition in plain language. When a conversation matches it, the conversation is flagged for your team to look at. |
| `identityDeflection` | How the agent answers when someone asks whether it is a person. |
| `smartSendingMode` | What happens to this initiative's messages when your organization caps how often one person is messaged. `FORCE` always sends, `DROP` skips a message that would go over the cap, and `DEFER` (the default) currently behaves like `DROP`. See [Smart Sending](/smart-sending). |
| `contextSchema` | Declares the per-participant variables you will pass when enrolling, so the agent can personalize. Participant `context` keys are validated against it. Set through the CSV upload in the app, not over the API. |
An initiative is created as `DRAFT`. A draft is fully editable. **After launch,
what the agent says stays editable** — `name`, `objective`, `context`,
`guidingQuestions`, `flagCondition` and `identityDeflection` — and the edit
reaches the next turn of every conversation already open, with no publish step.
That is the intended way to fix wording mid-run. `smartSendingMode` also stays
editable, and applies to the next message the initiative sends.
Responses include `isTransactional`, true for a Transactional. `GET /api/v1/initiatives` returns every kind when you pass neither `isRecurring` nor `isTransactional`. Passing `isRecurring` alone leaves Transactionals out, and `isTransactional=true` returns only Transactionals. A launch of a Transactional whose setup is incomplete is refused with `journey_not_ready`.
A Transactional starts only from its event, so send each event with the single-event endpoint (`POST /api/v1/cdp/events`). Batch event recording stores the events but does not trigger enrollment. You cannot add people to a Transactional by hand; that is refused with `422 transactional_event_only`.
Everything else — `channel`, `language`, `maxAttempts`, `isRecurring`,
`contextSchema` and the voice and reward settings — is draft-only, because it
cannot change under conversations already in flight. A `PATCH` that names one of
them on a launched initiative fails with `409 initiative_not_draft` and lists the
fields it refused, changing nothing. A `COMPLETED` or `CANCELED` initiative is
frozen outright.
One edit a launched initiative refuses even though the field is editable:
**clearing `context` or `objective`**. Both are required to launch, so emptying
one would leave the agent with no brief on conversations already open. Sending
`""` (or only whitespace) fails and changes nothing; send the new text instead.
**Dropping a guiding question** from a launched initiative that already collected
answers for it **archives** the question rather than deleting it. The agent stops
asking it from the next turn and no new answers are extracted, but the answers
already collected are kept: they still appear in insights, the data view, CSV
exports (column marked `(archived)`) and the data summary (`archived: true`). A
question with no answers yet, or any question on a draft, is deleted outright.
An archived question can't be restored or edited; sending its old `id` again
creates a new question.
`initiatives_update` takes `guidingQuestions` as the **complete set**, not a
patch. Omit the field to leave the questions alone. When you send it, carry each
existing question's `id` (from `initiatives_get`) to edit it in place — a
question you leave out counts as dropping it, which on a launched initiative
archives it (see above). So the round-trip is: read, edit the array keeping
every `id` you mean to keep, write.
Within a question you send, a field you leave out keeps its current value. That
applies to `answerType`, `scaleMin`, `scaleMax` and `options`: an edit that names
only `id` and `questionText` re-words the question and changes nothing else, so a
multiple-choice question keeps its type and its answer options. To change one of
them, send it — including `options: []` to clear the options, and a new
`answerType` to retype the question, which discards options that no longer apply.
`OPEN` is the default only for a question you are adding.
## Lifecycle
```
DRAFT ──launch──► ACTIVE ──► COMPLETED
│ │
│ ├── content editable
│ └── cancel, archive
├── fully editable
└── archive
```
Archiving only hides an initiative from the default list — it changes nothing
else, and unarchiving restores it. A draft created by mistake can be archived
directly; it does not have to be canceled first. A running (ACTIVE or PAUSED)
initiative cannot be archived: pause, complete or cancel it first. Launching an
archived draft un-archives it, so a live initiative is never hidden from the
list.
Launching starts real outreach to real people. It is the one call here you
cannot take back, and it is gated accordingly.
### What "ready to launch" means
A launch that is not ready fails with a specific code rather than a generic
error, which tells you exactly what to fix:
| Code | What it means |
| - | - |
| `409 initiative_not_draft` | It already launched, or it is cancelled or archived. Only a draft launches. |
| `422 no_outreach_template` | Round one has no approved, active WhatsApp template linked. An initiative cannot open a conversation without one. |
| `422 journey_not_ready` | The journey behind it failed validation at publish. The response lists the issues, and you fix them with the journey tools before launching again. |
| `422 initiative_not_ready` | A required field is missing, or rewards are not set up. The message names what is missing. |
Launching **publishes the initiative's journey for you**, on WhatsApp and
email alike, so you do not need a separate publish call. You do have to have
built that journey first: a new initiative does not come with one, and a
launch without one is refused. On WhatsApp, a missing channel
on the opening message is filled in automatically when there is only one
sensible answer: the initiative's own channel, otherwise the organization's
primary, otherwise its only sendable one.
**Launch before you enroll.** Adding participants requires an initiative that
is already `ACTIVE` with a published journey, so enrolling first fails with
`initiative_not_active`. Launching with nobody enrolled sends nothing, which
makes it safe to do first. Every person you add after that receives a real
message right away, so add one test contact and read what arrives before you
add the rest.
## Participants
Participants exist only inside an initiative, addressed under
`/initiatives/{id}/participants`. There is no global participant list, and there
is no delete: stopping a participant halts their outreach and keeps the data.
A `participantId` is one person's single pass through the journey, so a person
enrolled twice has two of them. It is the same id [`journey_run.*`
webhooks](/webhooks) report as `run.engagementId` — capture it there to stop a
specific run later without listing participants at all.
Each person needs the identifier of the initiative's channel: `phoneNumber` in
E.164 format on WhatsApp, `email` on an email initiative. The other one is
optional. A row without the channel's identifier comes back in `errors` as
`missing_phone_number` or `missing_email` and is not enrolled; every other row in
the request still goes through. Each added row echoes the `phoneNumber` and
`email` you sent for it, `null` when you sent none.
Enrolling sends a real message. People on your Do Not Contact list are skipped
by the platform rather than by whoever wrote the flow, on both channels, so a
suppressed contact enrolled by mistake is not contacted and comes back as
`contact_suppressed`.
## Reading results
Three read paths, all covered in [extraction](/extraction): the aggregate summary
for the whole initiative, the per participant record with its extracted values,
and the full transcripts.
## Related
The flow an initiative runs, and how to shape it when the default is not what
you want.
The typed fields every conversation should yield. Set this before launching.
Define who the initiative reaches, and remember to evaluate it.
The other direction, where no initiative is involved.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.