Skip to main content
Each initiative has its own agent, with its own objective and instructions. Some conversations need a different agent partway through: a support chat that should end with a satisfaction survey, or one inbound number where merchants, buyers and new leads each need a different flow. The Route to initiative step (ROUTE_TO_INITIATIVE) does that handoff.

​
What it does

When a person reaches a Route to initiative step, three things happen:
  1. Their run in this initiative ends. The conversation so far stays with this initiative, so its transcript and extracted data are still here.
  2. They are enrolled into the target initiative, and its journey starts.
  3. The live WhatsApp conversation moves onto the target. It is the same number and the same thread for the person; from then on the target initiative’s agent answers.
The step is an end point, like EXIT: nothing can follow it in the journey. The target must be a different initiative in your organization. It cannot be archived, cannot be the journey’s own initiative, and cannot be a Transactional (a Transactional only starts from its own event). Publishing is refused if any of these is not true.

​
The router pattern

One WhatsApp number can only be owned by one inbound journey. When different kinds of people write to that number and each needs a different agent, put a small router initiative in front:
  • The router’s ENTRY has an inbound trigger on the number, so a message to the number starts a router run.
  • A CASE on a person attribute (from your CDP) picks the target. Every branch, including the default, must be wired.
  • Send the default branch to your general support initiative, so someone the CASE can’t place still gets an answer.

​
The target must open by sending

The message that caused the routing belongs to the router’s part of the conversation. The target’s Wait for reply and Handle conversation steps only see messages that arrive after the handoff. So if the target’s journey starts with a wait, it waits for a new message the person has no reason to send, and the person is left without an answer. Start every target journey with a send. A branch first (a DECISION, see below) is fine, as long as each branch reaches a send before any wait.

​
Passing context to the target

Each route step can carry context: named values handed to the target (in the builder, Details for the next agent). A value is either text you write or a variable resolved at the moment of routing, such as data the router’s agent extracted or a person attribute. In the target, each value is available as engagement.workflowState.<name>. The target’s DECISION and CASE steps can branch on it, and its agent sees it as part of the conversation’s background.

​
Skip the template when the person just wrote

A target initiative is often also reachable another way, for example from a CDP event, where it opens with an approved template because the person hasn’t written recently. When the person arrives by routing, they wrote seconds ago, so the 24-hour window is open and a short free-text message reads better than a formal notice. Use context to tell the two apart:
  1. On the route step, add the context entrada = ruteo.
  2. In the target, put a DECISION right after ENTRY: engagement.workflowState.entrada equals ruteo.
  3. YES (arrived by routing): a short free-text message, then the conversation. Free-text sends also emit WINDOW_CLOSED, which must be wired, usually to the template send.
  4. NO (entered by the event): the template notice and its reminder, as before.
Both branches can then lead into the same conversation step. A step can have several incoming connections; only outgoing ones are limited to one per handle.

​
When the person already has a run of the target

If the person already has an active run of the target initiative, routing does not start a second one. The conversation moves onto the run they already have, and nothing new is sent: that run carries on from wherever it was. The context values from the route step are not added to that run.

​
When routing is refused

A route that can’t be carried out never fails the router’s run. The router’s run still ends, the conversation stays where it was, and the step records why. Routing is refused when:
  • A person on your team owns the conversation at that moment (it is assigned to a user), or a person on your team replied in it in the last 7 days and no agent is assigned. Routing would hand their customer back to an AI. Once your team resolves the conversation and the agent takes it back, routing works normally.
  • The target is this initiative, or the target has no agent.
  • The routing chain is too long. A person can be routed at most 5 times in a row (A to B to C…), so two initiatives that route to each other cannot loop forever.
  • The target won’t take the person: for example it has no live journey, or its frequency cap refuses another entry.
Check a person’s steps (in the app, or with initiatives_participant_steps_list) to see whether the route step handed them off and, if not, the reason.

​
Building it over MCP or the API

Route to initiative is available through the MCP and the journey API, with one condition: the call must come from a signed-in user, such as an AI tool connected to Boom’s MCP with your account, or the in-app assistant once you approve its change. It moves live conversations to another initiative’s agent, so someone accountable has to ask for it. Calls made with an API key alone are refused with signed_in_user_required, and nothing is saved.
  • journeys_authoring_catalog describes the step and its inputs: initiativeId (the target) and context (a map of names to text, or to { "var": "<path>" } for a value resolved at routing time).
  • journeys_validate checks the graph shape, such as no connection leaving the route step.
  • journeys_publish checks the target. A target in another organization, an archived one, the journey’s own initiative or a Transactional is refused with route_target_invalid, and the message names the step.

Journeys

Every step kind, and how to build, validate and publish a journey.

Inbound conversations

How a journey starts from a message a person sends first.