Skip to main content
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: The rest tune behavior: 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. 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. Two edits 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. Removing one deletes it outright, and with it every answer already extracted for it across every participant — so it is refused after launch. Re-word a question in place, or add a new one; both are allowed and reach the next turn.
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 is what a launched initiative refuses. So the round-trip is: read, edit the array keeping every id, write.

​
Lifecycle

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:
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. 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. 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.