Initiatives

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 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, 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 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. 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.
`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.
`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 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: the aggregate summary for the whole initiative, the per participant record with its extracted values, and the full transcripts.

Journeys

The flow an initiative runs, and how to shape it when the default is not what you want.

Extraction

The typed fields every conversation should yield. Set this before launching.

Segments

Define who the initiative reaches, and remember to evaluate it.

Inbound conversations

The other direction, where no initiative is involved.

Start here

How Boom works

Connect your tools

Reference

Initiatives

The fields that decide quality

Lifecycle

What “ready to launch” means

Participants

Reading results

Journeys

Extraction

Segments

Inbound conversations

​The fields that decide quality

​Lifecycle

​What “ready to launch” means

​Participants

​Reading results

​Related

Journeys

Extraction

Segments

Inbound conversations

The fields that decide quality

Lifecycle

What “ready to launch” means

Participants

Reading results

Related