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`.
`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.
`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.
`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. Only a draft is editable through the API, so get the configuration right before launching, and treat a launched initiative as frozen.

Lifecycle

DRAFT ──launch──► ACTIVE ──► COMPLETED
  │                 │
  └── editable      └── cancel, archive

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.

When the initiative is set to WhatsApp, launching publishes its journey for you, 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. 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. Enrolling sends a real message. People on your Do Not Contact list are skipped by the platform rather than by whoever wrote the flow, so a suppressed contact enrolled by mistake is not contacted.

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