Atomic channel coupling

What this solves

A weekly digest email has three placements: hero, body card, footer. If contact-policy fatigue or decisioning gates empty the hero, you don’t want to send a footer-only email — that’s worse than not sending. Atomic coupling lets you say “this channel is all-or-nothing within itself” without forcing every flow on that channel to be atomic.

Why this works

Coupling is per-channel, not global. Each Channel.couplingMode defaults to "partial" (any non-empty placement ships). Switching it to "atomic" makes the post-group coupling pass scan that channel’s placement results; if any one is empty, the rest are emptied with a cascade record in trace.channelCoupling[]. Cross-channel coupling is intentionally not supported — different channels are different attention surfaces, and an empty SMS shouldn’t suppress an email.

Three knobs

Setting	Where	Effect
`Channel.couplingMode`	`POST/PUT /api/v1/channels`	Default for the channel: `"partial"` (default) or `"atomic"`.
`DecisionFlow.couplingOverride`	`PUT /api/v1/decision-flows`	Per-flow override — beats the channel default when set. Useful when one channel serves both atomic (digest) and partial (transactional) flows.
`placementResults[*].count === 0`	derived	The trigger: zero offers in a placement, after group allocation.

Step 1 — Mark the email channel atomic

curl -X PUT https://playground.kaireonai.com/api/v1/channels \
  -H "Content-Type: application/json" -H "X-Requested-With: XMLHttpRequest" \
  -d '{ "id": "<email-channel-id>", "couplingMode": "atomic" }'

The channel id goes in the body — PUT /api/v1/channels updates by id, there is no /channels/{id} sub-route.

curl -X POST https://playground.kaireonai.com/api/v1/recommend \
  -H "Content-Type: application/json" -H "X-Requested-With: XMLHttpRequest" \
  -d '{
    "customerId": "cust-digest-001",
    "decisionFlowKey": "weekly-digest",
    "channelId": "<email-channel-id>",
    "placements": [
      { "placementId": "<email-hero>",      "limit": 1 },
      { "placementId": "<email-body-card>", "limit": 3 }
    ]
  }'

What you’ll see when coupling fires

Response body:

{
  "placements": {
    "<email-hero>":      { "count": 0, "offers": [] },
    "<email-body-card>": { "count": 0, "offers": [] }
  },
  "channelCoupling": [
    {
      "channelId":   "<email-channel-id>",
      "channelName": "email",
      "mode":        "atomic",
      "cascaded":    true,
      "emptyPlacements": ["<email-hero>"]
    }
  ]
}

Both placements are empty even though <email-body-card> would have had offers — because the hero was empty and the channel is atomic. The cascaded: true flag in channelCoupling[] is your audit trail: this wasn’t “no offers were available,” this was “we deliberately suppressed.”

Why not just use `Group.allowPartial`?

Group.allowPartial was the old switch. It’s deprecated and no-op now (the field still parses to keep legacy IRs valid). It conflated two distinct cases:

“Operator chose to require all placements filled” (now: Channel.couplingMode = "atomic")
“Contact policy fatigue happened to empty everything” (now: surfaces in the trace’s contactPolicyResults[] regardless)

The per-channel model lets you couple email but leave web partial; legacy allowPartial could only do flow-wide all-or-nothing.

Per-flow override

A weekly-digest flow needs atomic; a same-channel transactional alert flow needs partial. Set the channel default to atomic, then override on the transactional flow:

curl -X PUT https://playground.kaireonai.com/api/v1/decision-flows \
  -H "Content-Type: application/json" -H "X-Requested-With: XMLHttpRequest" \
  -d '{
    "id": "<transactional-flow-id>",
    "name": "Transactional Alerts",
    "couplingOverride": "partial",
    "rowVersion": <current>
  }'

Now the transactional flow sends whichever placements have offers; the digest flow on the same channel still goes all-or-nothing.

Proof reference

T8 of the proof bundle: channelCoupling.cascaded = true with both placements empty, when the hero is fatigued out by a frequency cap.

Get Started

Tutorials

Use Cases

Decisioning

Studio

Data Pipelines

AI & ML

Operations & Reporting

Governance & Security

Integrations

Reference

Atomic channel coupling

What this solves

Why this works

Three knobs

Step 1 — Mark the email channel atomic

What you’ll see when coupling fires

Why not just use `Group.allowPartial`?

Per-flow override

Proof reference

​What this solves

​Why this works

​Three knobs

​Step 1 — Mark the email channel atomic

​Step 2 — Fire a multi-placement recommend

​What you’ll see when coupling fires

​Why not just use Group.allowPartial?

​Per-flow override

​Proof reference

What this solves

Why this works

Three knobs

Step 1 — Mark the email channel atomic

Step 2 — Fire a multi-placement recommend

What you’ll see when coupling fires

Why not just use `Group.allowPartial`?

Per-flow override

Proof reference