​

The routing-claim election lifecycle

The group messaging model separates fan-out (one operation reaching many recipients) from thread assignment (one conversation reaching one owner). That page stops at the border of assignment; this one is what happens on the destination side. A conversation routed to your team is elected — one claim wins, every competing claim loses, and the winner owns the work item through a lifecycle that runs open → pending → resolved. Nothing else about routing makes sense until that primitive is pinned down. The primitive has a strict rule the whole platform enforces: the claim module never runs two competing claims on one work item at the same time. Configuring a surface as if a label were routing — or expecting a group send to carry thread semantics back — both trace to the same mistake, which is treating something that is not a claim as if it were one.

​

1. The four-agent cast

Every routing election is decided by four different systems acting in sequence, and a configuration that conflates them is where routing bugs come from. Name the cast first, then the families:

• Presence — the five-state machine in Agent presence and aux-code lifecycle. It answers one question: is this agent even a candidate? available is eligible; busy, wrapup, paused, and offline are excluded (voice excludes all four; digital excludes only busy, wrapup, and offline — paused stays eligible).
• Eligibility — the pool membership and skills filter. The ACD queue model holds the queue roster, and the skill catalog holds the tags a work item can require. Presence admits an agent to the election; eligibility narrows the election to agents on this queue carrying this skill.
• Capacity ledger — the atomic reserve/release counter described in Omnichannel capacity and reservation model. It answers the second question: does this eligible agent have a free slot? The ledger refuses the reservation at the saturation ceiling, which is what makes the election winnable by exactly one claimant.
• Election primitive — the single atomic offer. For digital queues the offer is a slot reservation plus the assignment row; for voice ring groups the offer is the strategy-picked member’s endpoint, held through the acceptance window. One winner; every other candidate’s claim loses and re-routes.

The four agents are deliberately separate. Presence without capacity is a double-booked agent; eligibility without presence rings a phone nobody answers. Read all four together, in that order, on every routing decision.

​

2. Three election families compared

Three things participate in answering “whose is this conversation.” They look similar in the dashboard but are different families, and only two of them are routing at all. The first two families route; each terminates in a durable assignment record every surface agrees on, because there is only one record to agree about. The third annotates work that is already routed. The sections below take each family to the level an operator needs.

​

3. Why presence + capacity is atomic

Consider two digital channels assigning to the same blended agent at the same instant. Each checks presence — the agent is available, admitted. Each checks eligibility — the agent is on the queue, admitted. If the decision stopped there, both channels would read “this agent has headroom” and both would assign, landing the agent one conversation over their ceiling. A gauge that reads load can describe that overshoot; it can never prevent it. So the election is decided by an atomic slot reservation, not by observation. When the digital router picks a candidate, it first reserves one blended slot as a single indivisible step: prune expired holds, count base load plus live holds, and grant the new hold only if base load + live holds + 1 ≤ the ceiling. Because the count and the claim happen in the same step, two channels racing for the last slot cannot both win — the loser is refused at reservation and re-routes to the next candidate, an overflow queue, or the unassigned pool. The winner then writes the assignment row — the conversation’s ownership record — and releases the slot hold once the row is durable. Release-on-durable matters: the row itself then represents the load, and every read surface — inbox views, the supervisor wallboard, reporting, the disposition stats — reads ownership from that one row. The reservation is what makes the election winnable by exactly one claimant; the assignment row is what makes the winner visible to everything else. A leaked reservation cannot strand a slot either — every hold carries a short TTL and expires on its own, and a degraded reservation store fails open (assignment proceeds, marked as unenforced) rather than blocking inbound work on an infrastructure blip.

​

4. Ring strategies compared

A voice-ring claim elects one member per call by the strategy you configure on the ring group. The three strategies differ only in how they order the candidate list; the atomic one-member-one-call guarantee is identical under all three. The election runs in lockstep with the ring attempt: candidates are pre-ordered per call, the highest-priority candidate whose presence allows eligibility wins, and the call is offered to exactly that member’s endpoint for the acceptance window. On timeout or decline, the call rotates to the next elected member — the ring group never double-offers, and no second endpoint ever holds the same call.

​

5. The label trap: QA vs dispatch

Labels and claims have different binding semantics. A claim is lifecycle-bound — it exists from assignment to resolution and its state changes the conversation’s behavior: SLA timers run against open, pending parks the SLA clock, resolved discharges the ownership. A label is static — it exists whenever you stick it on, and conversation state, ownership, and SLA behavior are indifferent to whether the label is present. Misuse shows up in two predictable places. In QA: an evaluator applies a disposition label to score or categorize a conversation and the operation seems to “route” — it dispenses into a review distribution, but review distribution is not assignment. In dispatch: an operator assumes applying a queue-named label moves the conversation into that queue. It does not. The split is a one-way door in the data model: dispatch never reads the label store. Only the conversations claim — an election through presence and capacity — moves ownership; labels write annotation metadata for QA scorecards, reporting filters, and saved views. If you find a workflow that expects a label to change who owns an item, re-read the disposition lifecycle under the Inbox API reference and use the assignment surface for the ownership change the workflow actually wants. The quality evaluation lifecycle is where labels pay off; they are the QA surface, never the routing surface.

​

6. How election composes with group fan-out

The election primitive sits on the destination side; the group messaging model sits on the send side. They compose in one direction: a group operation fans out to N recipients, and every reply that comes back is a fresh inbound work item that the claim election treats exactly like any other inbound conversation. Pick the destination first, then let that pick the channel: Carrier evidence runs one way only: SMS and MMS have no joint thread object, so group MMS is a fan-out of per-recipient copies and the replies you get back are claims on individual threads again. Outbound still exits exclusively via the Devotel wholesale softswitch in either channel choice — election governs inbound ownership, never outbound termination.

​

7. Two claim walks end to end

Sequence walk A — inbox digital queue claim. A customer message lands on a WhatsApp channel:

1. Ingest — the inbound channel adapter creates the conversation and the inbox routing-rule evaluator targets a digital queue under /api/v1/inbox/digital-queues.
2. Presence filter — the digital router drops members whose worst-case presence is busy, wrapup, or offline from the election pool (paused members stay eligible for digital work).
3. Eligibility filter — the queue membership roster and any required skill tags narrow the pool to the agents this conversation may go to.
4. Atomic reservation — the router asks the capacity ledger to reserve one slot for the lead candidate: count base load + live holds against the ceiling in one indivisible step. A refusal re-routes to the next candidate, the overflow queue, or the unassigned pool.
5. Assignment row — the winner’s ownership row is written; the SLA clock starts against open. The slot hold is released once the row is durable.
6. Lifecycle — the claim carries the conversation open (awaiting first reply) → pending (waiting on the customer or a teammate) → resolved (claim discharged). Read the distribution from the dispositions stats endpoint; apply a manual override with POST /conversations/:id/disposition.

Sequence walk B — voice ring group claim. An inbound PSTN call lands on a ring group:

1. Arrival — inbound voice routing hands the call to the ring group on the DID’s routing config.
2. Candidate ordering — the configured strategy pre-orders the eligible members: member order (first-available), rotated starting point (round-robin), or answered-call count (fewest-calls).
3. Presence + eligibility check — candidates whose presence (busy, wrapup, paused, offline) or queue eligibility excludes them are skipped in order.
4. Atomic election — the head of the order is elected; that member’s endpoint and only that endpoint holds the call for the acceptance window.
5. Loss path — on timeout or decline the ring group never re-offers the call to a second endpoint in parallel; it rotates to the next elected member.
6. Winner recorded — the answering member’s election becomes the accepted call leg; every surface — attendant console, wallboard, reporting — reads the same single leg.

​

Where this page sits

Adopt this lifecycle as the destination-side companion to the fan-out page:

• Group messaging model — resolves fan-out versus thread on the send side and hands the ownership question to this page.
• Agent presence and aux-code lifecycle — the presence half of the election pool.
• Omnichannel capacity and reservation model — the atomic capacity half of the same election.
• The ACD queue model — queue membership, skills, and FIFO dispatch feeding the same presence + capacity election.
• Skill catalog — the eligibility tags a queue can require of its members.
• The call-quality evaluation lifecycle — where disposition labels actually drive value: QA distribution, never dispatch.
• Omnichannel queue routing for digital channels — the operator guide for the digital queues the conversations claim lands in.
• Set up and run voice queues — ring-group strategies and queue operation.