@xema/omni-protocol 0.1.122 → 0.1.123

package/GLOSSARY.md

@@ -100,7 +100,7 @@ hands only through routing or a lead's take-over.
 
 | Term | In plain words | What others call it |
 | --- | --- | --- |
-| **History** | The steps a call went through before and with this agent: arrived, queued, answered, held, handed over. | *Contact trace record* (Amazon Connect), *conversation details* or *segments* (Genesys Cloud), *call detail record*. |
+| **History** | The steps a call went through before and with this agent: arrived, self-service, queued, answered, held, handed over. | *Contact trace record* (Amazon Connect), *conversation details* or *segments* (Genesys Cloud), *call detail record*. |
 | **Recording** | A recording of one side of the call, the customer's or the agent's. | *Call recording*, *screen and voice recording*. |
 | **Paused for sensitive details** | Recording stops while card or account details are given. | *Secure pause* (Genesys Cloud), *PCI pause*. |
 

package/dist/index.d.ts

@@ -872,7 +872,7 @@ export type TaskAttribute = TaskAttributeBase & ({
     type: "timestamp";
     at: IsoTimestamp;
 });
-export type HistoryStep = "arrived" | "queued" | "offered" | "answered" | "held" | "muted" | "transferred" | "conferenced" | "unanswered" | "callback-requested";
+export type HistoryStep = "arrived" | "self-service" | "queued" | "offered" | "answered" | "held" | "muted" | "transferred" | "conferenced" | "unanswered" | "callback-requested";
 /**
  * The call record: the steps that brought the task here, one entry per occurrence and oldest
  * first, and what they add up to before this agent -- stated by the provider from its own record,
@@ -907,7 +907,7 @@ export interface TaskHistoryStep {
      */
     seconds?: DurationSeconds;
     /**
-     * Who took part. Absent on `arrived` and `queued`, where nobody does; absent on `callback-requested`, where the
+     * Who took part. Absent on `arrived`, `self-service` and `queued`, where nobody does; absent on `callback-requested`, where the
      * caller chose it in the queue, and present there when an agent arranged it; absent on any other
      * step means the provider could not attribute it, which is a different claim and a legitimate one.
      */
@@ -2053,6 +2053,7 @@ export declare const DEFAULT_TASK_TYPE_PRESENTATION: {
 };
 export declare const DEFAULT_HISTORY_STEP_LABELS: {
     readonly arrived: "Incoming call";
+    readonly "self-service": "Self-service";
     readonly queued: "Queued";
     readonly offered: "Offered";
     readonly answered: "Answered";
@@ -2086,8 +2087,8 @@ export declare const assignmentKey: (providerId: string, assignmentId: Assignmen
  */
 export declare const userKey: (providerId: string, userId: UserId) => string;
 /**
- * Every history step somebody from the provider takes part in. `arrived` and `queued` are the ones
- * nobody does, and `callback-requested` is the caller's choice unless an agent arranged it, so none
+ * Every history step somebody from the provider takes part in. `arrived`, `self-service` and
+ * `queued` are the ones nobody does, and `callback-requested` is the caller's choice unless an agent arranged it, so none
  * of them is here.
  */
 export declare const HISTORY_STEPS_WITH_A_PERSON: readonly ["offered", "answered", "held", "muted", "transferred", "conferenced", "unanswered"];

package/dist/index.js

@@ -146,7 +146,7 @@ export const DEFAULT_TASK_TYPE_PRESENTATION = {
     email: { singular: "Email", plural: "Emails", referenceLabel: "Email ID" },
 };
 export const DEFAULT_HISTORY_STEP_LABELS = {
-    arrived: "Incoming call", queued: "Queued", offered: "Offered", answered: "Answered", held: "On hold",
+    arrived: "Incoming call", "self-service": "Self-service", queued: "Queued", offered: "Offered", answered: "Answered", held: "On hold",
     muted: "Muted", transferred: "Transferred", conferenced: "Conferenced", unanswered: "Unanswered",
     "callback-requested": "Callback requested",
 };
@@ -188,8 +188,8 @@ export const assignmentKey = (providerId, assignmentId) => `${encodeURIComponent
  */
 export const userKey = (providerId, userId) => `${encodeURIComponent(providerId)}:${encodeURIComponent(userId)}`;
 /**
- * Every history step somebody from the provider takes part in. `arrived` and `queued` are the ones
- * nobody does, and `callback-requested` is the caller's choice unless an agent arranged it, so none
+ * Every history step somebody from the provider takes part in. `arrived`, `self-service` and
+ * `queued` are the ones nobody does, and `callback-requested` is the caller's choice unless an agent arranged it, so none
  * of them is here.
  */
 export const HISTORY_STEPS_WITH_A_PERSON = [

package/dist/validation.js

@@ -58,7 +58,7 @@ const TEAM_AVAILABILITIES = membersOf({
     ready: true, "on-task": true, "on-break": true, elsewhere: true, "signed-out": true,
 });
 const HISTORY_STEPS = membersOf({
-    arrived: true, queued: true, offered: true, answered: true, held: true, muted: true, transferred: true, conferenced: true, unanswered: true,
+    arrived: true, "self-service": true, queued: true, offered: true, answered: true, held: true, muted: true, transferred: true, conferenced: true, unanswered: true,
     "callback-requested": true,
 });
 const CUSTOM_UI_CONTROLS = membersOf({ button: true, toggle: true, "menu-item": true });
@@ -995,8 +995,8 @@ function validateHistory(value, path, into, task = {}) {
         }
         if (entry.by !== undefined) {
             into.require(isUserId(entry.by), "task.history.by", `${at}.by`, "by must be a non-empty user id; omit it when the person cannot be identified");
-            // On `arrived` and `queued` nobody takes part, so there is nothing to name.
-            into.require(entry.step !== "arrived" && entry.step !== "queued", "task.history.by.unexpected", `${at}.by`, `${describeValue(entry.step)} names nobody`);
+            // On `arrived`, `self-service` and `queued` nobody takes part, so there is nothing to name.
+            into.require(entry.step !== "arrived" && entry.step !== "self-service" && entry.step !== "queued", "task.history.by.unexpected", `${at}.by`, `${describeValue(entry.step)} names nobody`);
         }
         // A step that dialled says where to and, when a host placed it, which dial; no other step dialled.
         const dialled = typeof entry.step === "string" && HISTORY_STEPS_THAT_DIAL.includes(entry.step);

package/guide/agent.md

@@ -409,7 +409,8 @@ first, and what they add up to before this agent:
 ```ts
 history: {
   steps: [
-    { step: "arrived",     at: "2026-08-21T00:58:40Z", seconds: 20 },
+    { step: "arrived",     at: "2026-08-21T00:58:40Z", seconds: 2 },
+    { step: "self-service", at: "2026-08-21T00:58:42Z", seconds: 18 },
     { step: "queued",      at: "2026-08-21T00:59:00Z", seconds: 41 },
     { step: "answered",    at: "2026-08-21T00:59:41Z", seconds: 312, by: "a-17" },
     { step: "held",        at: "2026-08-21T01:02:10Z", seconds: 35, by: "a-17" },
@@ -430,7 +431,7 @@ something else, which will arrive under its own name and must not be folded in h
 
 It rides in the snapshot and is replaced whole like everything else there.
 
-Steps are `arrived`, `queued`, `offered`, `answered`, `held`, `muted`, `transferred`, `conferenced`,
+Steps are `arrived`, `self-service`, `queued`, `offered`, `answered`, `held`, `muted`, `transferred`, `conferenced`,
 `unanswered`, `callback-requested`, and each is defined on `TaskHistoryStep`.
 
 **The record starts where the call started.** `arrived` is the instant the call reached the
@@ -442,6 +443,14 @@ arrive omits it rather than guessing an instant. Omni shows it as *Incoming call
 Amazon Connect keeps an initiation time, Genesys Cloud a conversation start and NICE CXone a contact
 start, separate from the queue.
 
+**Time with the IVR or a bot is `self-service`.** The caller pressing through a menu, talking to a
+voice bot, or a chat customer with a bot before a person takes over: one step for all of them, on
+every channel, the way Genesys Cloud and NICE CXone report IVR and bot time together as
+self-service. Nobody from the provider takes part, so it has no `by`. `at` is when the customer
+entered it and `seconds`, once it ended, how long they spent there; a customer sent back to a menu
+after a transfer has a second entry, one per visit, as a second queue is a second `queued`. A
+customer that words it *IVR* for its agents does so in `labels.historySteps`.
+
 **A callback carries the call it comes back to.** When a caller asks to be called back, or an agent
 arranges it, the provider writes a `callback-requested` step: `by` names the agent who arranged it, and
 is absent when the caller chose it in the queue. The callback reaches an agent as a new task, and that
@@ -551,7 +560,7 @@ Four rules a provider has to keep:
   wrongly; carrying the name here would also copy it into every task and leave it to go stale.
 
 **An absent `by` means different things on different steps, and both are legitimate.** On
-`arrived` and `queued` nobody takes part, so there is nothing to name. On every other step somebody did — see
+`arrived`, `self-service` and `queued` nobody takes part, so there is nothing to name. On every other step somebody did — see
 `HISTORY_STEPS_WITH_A_PERSON` and `historyStepExpectsAPerson()` — so an absent `by` there says
 *this was handled and the provider cannot say by whom*. The one step that is never unattributed is
 `muted`: the agent application has exactly one agent and the provider knows who, so `by` is required there
@@ -564,7 +573,7 @@ worse than one saying plainly it could not attribute a leg — and far better th
 nothing because a single leg could not be named.
 
 An agent application must render the two differently. Showing an unattributed `answered` the same way as
-`queued` or `arrived` tells the agent nobody was involved, which is not what was said. Omni renders it as
+`queued`, `self-service` or `arrived` tells the agent nobody was involved, which is not what was said. Omni renders it as
 *"not recorded"* in the place the name would go.
 
 Omit `history` entirely when the provider cannot observe the steps. Empty `steps` is a

package/guide.md

@@ -696,6 +696,7 @@ type TaskAttribute = TaskAttributeBase & (
 
 type HistoryStep =
   | "arrived"
+  | "self-service"
   | "queued"
   | "offered"
   | "answered"
@@ -1362,7 +1363,7 @@ const OMNI_FAILURE_CODES = [
 type OmniFailureCode = (typeof OMNI_FAILURE_CODES)[number];
 ```
 
-`HISTORY_STEPS_WITH_A_PERSON` is every `HistoryStep` except `arrived` and `queued`, which nobody
+`HISTORY_STEPS_WITH_A_PERSON` is every `HistoryStep` except `arrived`, `self-service` and `queued`, which nobody
 takes part in, and `callback-requested`, which the caller may choose alone. `historyStepExpectsAPerson()` tests membership.
 
 ### Failure and validation
@@ -1445,6 +1446,7 @@ agent's languages:
 ```ts
 const DEFAULT_HISTORY_STEP_LABELS = {
   arrived: "Incoming call",
+  "self-service": "Self-service",
   queued: "Queued",
   offered: "Offered",
   answered: "Answered",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xema/omni-protocol",
-  "version": "0.1.122",
+  "version": "0.1.123",
   "description": "The Omni protocol: the contract every provider adapter implements",
   "type": "module",
   "license": "MIT",