@xema/omni-protocol 0.1.129 → 0.1.130
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/GLOSSARY.md +2 -2
- package/README.md +6 -8
- package/dist/index.d.ts +138 -87
- package/dist/index.js +24 -9
- package/dist/testing.d.ts +14 -14
- package/dist/testing.js +79 -82
- package/dist/validation.d.ts +23 -23
- package/dist/validation.js +174 -121
- package/guide/agent.md +23 -23
- package/guide/breaks.md +1 -1
- package/guide/lead.md +34 -17
- package/guide/phone.md +22 -22
- package/guide/queue.md +7 -7
- package/guide/voice.md +64 -54
- package/guide.md +163 -143
- package/package.json +1 -1
package/guide/voice.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# `@xema/omni-protocol`: Voice
|
|
2
2
|
|
|
3
|
-
What is true of a call and of nothing else: preview, connecting back, ending a call,
|
|
3
|
+
What is true of a call and of nothing else: preview, connecting back, ending a call, adding to a call, every dial and its outcome, recording. Part of the contract in `guide.md`, which holds the terms, the shapes and the rules every file here relies on; a reference in bold names the file it points into where that is not this one.
|
|
4
4
|
|
|
5
5
|
## Preview: the agent presses Call
|
|
6
6
|
|
|
@@ -62,10 +62,10 @@ publication carried, counted from its receipt: the agent application infers no d
|
|
|
62
62
|
was stated and reads no clock against another. Neither elapsed time nor submission changes the
|
|
63
63
|
task phase: subsequent authoritative events state ringing, answer, audio and completion.
|
|
64
64
|
|
|
65
|
-
An agent application must serialize manual clicks and its timer under the exact provider/
|
|
65
|
+
An agent application must serialize manual clicks and its timer under the exact provider/session/task/assignment
|
|
66
66
|
scope, allowing at most one unresolved submission. Recheck the current phase, deadline owner,
|
|
67
67
|
assignment and whether an attempt already exists before dispatch. A new snapshot or policy update
|
|
68
|
-
cancels an obsolete timer;
|
|
68
|
+
cancels an obsolete timer; session loss, disconnect, task end and assignment replacement fence its
|
|
69
69
|
callback. Reconnect past a deadline first reconciles current task and attempt state; it must not
|
|
70
70
|
blindly submit again. An uncertain prior submission remains unresolved, without automatic retry.
|
|
71
71
|
The provider atomically arbitrates any residual manual/timer race and does not accept a second
|
|
@@ -87,7 +87,7 @@ provider is told through `refused` exactly which rule, so the state that looked
|
|
|
87
87
|
is named on its side. The task past preview has no deadline to wait for, so it carries neither
|
|
88
88
|
field.
|
|
89
89
|
|
|
90
|
-
**Provider execution and agent application controls are distinct.** Answer, hold/resume,
|
|
90
|
+
**Provider execution and agent application controls are distinct.** Answer, hold/resume, add to call,
|
|
91
91
|
lead assist and interaction completion are executed by the provider
|
|
92
92
|
through the adapter. The task's applicable capability, phase, completion mode and command-specific
|
|
93
93
|
prerequisites decide which controls are offered. Caller disconnect also executes at the provider. Microphone mute is agent application-owned, never a provider
|
|
@@ -99,7 +99,7 @@ own assignment, and two open at once carry two assignment ids. Restore them unch
|
|
|
99
99
|
reconnect. Commands, audio, endings and history reports name the exact assignment; never retarget
|
|
100
100
|
an old command to the newest interaction of a journey. `validateTaskCommandRequest` checks the
|
|
101
101
|
request's assignment against the supplied published task and then its command prerequisites. The
|
|
102
|
-
caller must select that task within the correct provider/
|
|
102
|
+
caller must select that task within the correct provider/session and recheck at the provider; the
|
|
103
103
|
validator cannot prove source freshness or authorization.
|
|
104
104
|
`task-ended` retires only that interaction's resources. Another interaction, caller channel or IVR/queue
|
|
105
105
|
portion must not be cleared because this task ended. Snapshot counts include all still-owned wrap
|
|
@@ -107,7 +107,7 @@ and active interactions; task completion is not caller hangup.
|
|
|
107
107
|
|
|
108
108
|
**Voice describes the agent's interaction within the wider call.** The task defines that agent's
|
|
109
109
|
workspace, tools, permissions, audio participation and completion work. The caller's channel may
|
|
110
|
-
continue through IVR, queues, other agents, holds or
|
|
110
|
+
continue through IVR, queues, other agents, holds or people added while this interaction ends or wraps.
|
|
111
111
|
Completing this task ends this interaction responsibility; it is not evidence that the caller's channel
|
|
112
112
|
or journey ended. Task audio describes this agent's attachment, not the lifetime of every party's
|
|
113
113
|
connection. Commands retain their explicit targets and effects; task completion must not silently
|
|
@@ -116,7 +116,7 @@ become a caller-disconnect operation.
|
|
|
116
116
|
**A task is never its audio.** A voice task represents the agent’s interaction: the call is offered when it is
|
|
117
117
|
routed to the agent and accepted as its `acceptance` dictates, and its presence and phase follow
|
|
118
118
|
the provider's reports about the work — never the audio. Wherever audio moves — an offer, a hold, a
|
|
119
|
-
|
|
119
|
+
someone added joining or leaving, a lead joining, a take-over, a connect-back — the audio follows
|
|
120
120
|
separately, arriving on `task-audio-started`, attaching through `openAudio` and ending with
|
|
121
121
|
`task-audio-ended`. Omni does not ring,
|
|
122
122
|
bridge, or hold a line. How the phone rings, whether it rings at all, and where legs join and leave
|
|
@@ -154,7 +154,7 @@ deadline.
|
|
|
154
154
|
|
|
155
155
|
**The room shows the party being dialled.** From the moment any agent application dial places the party -- a
|
|
156
156
|
dialpad call, a preview Call, a connect-back -- the `party` entry carries `stage: "ringing"` and
|
|
157
|
-
the agent application's `dialId`, exactly as
|
|
157
|
+
the agent application's `dialId`, exactly as an added entry does from its dial; `joined` on
|
|
158
158
|
the publication that follows the answered `dial-outcome` and never before it
|
|
159
159
|
(`stream.taskUpdated.stage`); and no stage from the next publication on, so `joined` is transient
|
|
160
160
|
and a later copy still carrying it is stale (`stream.taskUpdated.stage.lingering`). An agent application shows a
|
|
@@ -199,48 +199,58 @@ const immediateProviderCompletion = {
|
|
|
199
199
|
| Capability | Omni UI | Contract |
|
|
200
200
|
| --- | --- | --- |
|
|
201
201
|
| `decline` | Pending-task button: Decline | The provider can decline a pending voice offer. Omni shows it only when local policy also permits declining. |
|
|
202
|
-
| `hold` | Primary toggle: Hold | Omni may issue voice-task `hold` and `resume` commands. |
|
|
202
|
+
| `hold` | Primary toggle: Hold | Omni may issue voice-task `hold` and `resume` commands. Hold holds the caller: while the task is `paused` the party waits on hold and the agent keeps talking with everyone else on the call -- an added colleague, a lead who joined -- and `onCall` marks the party `held: true`. |
|
|
203
203
|
| `endCall` | Primary button: End call | The provider ends the agent's channel and every channel the agent added; the caller continues on the provider's path. The task goes to its wrap. See **Ending a call, and removing one person from it**. |
|
|
204
204
|
| `terminateCall` | Primary button: Terminate call | The provider ends the whole call: every channel on it, the agent's, the caller's, any colleague's and anyone else's. The task goes to its wrap. See **Ending a call, and removing one person from it**. |
|
|
205
205
|
| `connectBack` | Completing-task button: Connect back | Omni may have the provider connect the agent back to the task's party while the task is `completing`, returning it to `in-progress` on the same task. Not offered where there is no `completing` window: `provider-automatic` with a zero allowance completes the task at provider end. See **Connecting back during completion**. |
|
|
206
206
|
| `schedule` | Secondary menu item: Schedule | Omni may put a follow-up for this party on the calendar, from the call or from its wrap: a time, and a note. See **Scheduling a follow-up** in `guide/agent.md`. |
|
|
207
207
|
| `leadAssist` | Secondary menu item: Lead assist | Omni may ask a lead to join this call, with a note. The lead's decision reaches the agent on `Task.leadAssist`. See **Lead assist** in `guide/lead.md`. |
|
|
208
|
-
| `
|
|
208
|
+
| `addToCall` | Secondary button: Add to call | Omni may dial a contact or a typed number into the active call (`add-to-call`), and remove one person from it (`remove-from-call`) -- an added entry, one still ringing included, which calls the dial off, or the party, leaving the agent with the colleague. See **Ending a call, and removing one person from it**. |
|
|
209
209
|
| `recording` | Overflow menu item: Recording | Per-task provider and agent application policies expose only their permitted recording actions; each has independent state and routing. |
|
|
210
210
|
| `outcomes` | Primary button: Complete | Omni may request task completion with a provider outcome and notes. |
|
|
211
211
|
|
|
212
|
-
## `
|
|
212
|
+
## `addToCall`
|
|
213
213
|
|
|
214
214
|
```ts
|
|
215
215
|
capabilities: {
|
|
216
|
-
|
|
217
|
-
destinations: [
|
|
218
|
-
{ id: "tier2", label: "Tier 2 support" },
|
|
219
|
-
{ id: "main-menu", label: "Back to the main menu" },
|
|
220
|
-
],
|
|
221
|
-
},
|
|
216
|
+
addToCall: { destinations: "any-number", contactIds: ["c-17", "c-20"] },
|
|
222
217
|
}
|
|
223
218
|
```
|
|
224
219
|
|
|
225
220
|
| Field | Contract |
|
|
226
221
|
| --- | --- |
|
|
227
|
-
| `destinations` |
|
|
228
|
-
| `
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
222
|
+
| `destinations` | Whom the agent may bring in, in the dialpad's own words (`task.addToCall.destinations`): `contacts-only`, an entry of this provider's contacts; `any-number`, a number the agent types as well. |
|
|
223
|
+
| `contactIds` | Optional. The contacts this task offers, by id: a billing call may offer the billing specialist and the translator line and nothing else (`task.addToCall.contactIds`, `.unique`). Omitted, every contact is offered. Ids only -- the agent computer shows the names it holds -- and an add naming another contact is refused before it is sent (`command.addToCall.contactId.unlisted`). |
|
|
224
|
+
|
|
225
|
+
**The directory is the provider's contacts, at the agent computer.** It reaches the agent
|
|
226
|
+
computer once, with the snapshot, and again whenever it changes (`contacts-updated`), never on a
|
|
227
|
+
task, a call or a history. Each entry is a contact with a unique `id` (`contact.id`,
|
|
228
|
+
`contact.id.unique`), a name, and a number that may be withheld: a person the agent can reach -- a
|
|
229
|
+
colleague, a specialist, an outside number such as a translator line. Adding to the call brings a
|
|
230
|
+
person in while the agent stays; it is not a way to send the caller to a queue or a menu. The wire
|
|
231
|
+
names a contact by its `id` alone, and the agent computer shows the name it holds for it:
|
|
232
|
+
|
|
233
|
+
```ts
|
|
234
|
+
const contacts: ContactEntry[] = [
|
|
235
|
+
{ id: "c-17", name: "Ravi, billing specialist", number: "+914023400000" },
|
|
236
|
+
{ id: "c-20", name: "Translator line" },
|
|
237
|
+
];
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
**Adding to the call names a contact by its id, or a typed number where the task allows any number.**
|
|
241
|
+
|
|
242
|
+
```ts
|
|
243
|
+
{ type: "add-to-call", dialId: "dial-7f2", contactId: "c-17" } // from the contacts
|
|
244
|
+
{ type: "add-to-call", dialId: "dial-9b4", number: "+914023456789" } // typed
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
A typed number on a `contacts-only` task is refused before it is sent
|
|
248
|
+
(`command.addToCall.number.contactsOnly`), and an add names one of the two, never both
|
|
249
|
+
(`command.addToCall.number.both`). The provider rechecks either and may refuse it
|
|
250
|
+
(`omni.destination-not-permitted`). A typed number becomes a contact: the provider enters it in its
|
|
251
|
+
contacts under an id of its own, publishes the entry, and names the person by that id from then
|
|
252
|
+
on -- on `onCall`, in the `added` step, on the dial's outcome and on a remove -- as it names
|
|
253
|
+
everyone else.
|
|
244
254
|
|
|
245
255
|
## Ending a call, and removing one person from it
|
|
246
256
|
|
|
@@ -250,12 +260,12 @@ provider. Two of them end the agent's part; they differ in what happens to the c
|
|
|
250
260
|
```ts
|
|
251
261
|
{ type: "end-call" } // the agent's channel and the channels the agent added end; the caller continues
|
|
252
262
|
{ type: "terminate-call" } // every channel on the call ends
|
|
253
|
-
{ type: "
|
|
254
|
-
{ type: "
|
|
263
|
+
{ type: "remove-from-call", party: true } // the customer leaves; the agent stays with the colleague
|
|
264
|
+
{ type: "remove-from-call", contactId: "c-17" } // the added person leaves; ringing, this calls the dial off
|
|
255
265
|
```
|
|
256
266
|
|
|
257
267
|
**`end-call` ends my part.** The agent's channel and every channel the agent added -- a
|
|
258
|
-
|
|
268
|
+
added colleague, a lead who joined -- end, and the caller continues on the path the
|
|
259
269
|
provider decides: another IVR, a queue, a survey, or the end of the call. Gated by `endCall`.
|
|
260
270
|
|
|
261
271
|
**Never from hold.** An `end-call` while the task is `paused` would leave the caller in the hold
|
|
@@ -280,8 +290,8 @@ capabilities** sets out. The provider knows which channels are the agent's and w
|
|
|
280
290
|
the agent application sends the command and no channel list, and the provider rechecks ownership
|
|
281
291
|
when it acts.
|
|
282
292
|
|
|
283
|
-
`
|
|
284
|
-
for the rest; it is gated by `
|
|
293
|
+
`addToCall` `remove` takes one person off, named as the room names them, and the call goes on
|
|
294
|
+
for the rest; it is gated by `addToCall`, since it only means something with a third person on
|
|
285
295
|
the line. Removing the party leaves the agent with the colleague, a warm hand-over in reverse. A
|
|
286
296
|
remove that would leave the agent alone is not a remove but an `end-call`, and a provider answers
|
|
287
297
|
it `failed`.
|
|
@@ -314,7 +324,7 @@ inside Omni.
|
|
|
314
324
|
## Every dial has an outcome
|
|
315
325
|
|
|
316
326
|
Four commands place a call: `dial()` from the idle dialpad, the `dial` command from preview, a
|
|
317
|
-
`
|
|
327
|
+
`addToCall` `add`, and `connect-back`. Each is accepted or refused at once, and each then ends later
|
|
318
328
|
and apart from its answer -- the destination picks up, is busy, or never does -- and a dial placed
|
|
319
329
|
late in a call routinely outlives the call. Nothing in between is reported: the wire says
|
|
320
330
|
`dialling`, then says how it ended, once.
|
|
@@ -327,16 +337,16 @@ declare const connection: Connection<"voice">;
|
|
|
327
337
|
declare const assignmentId: AssignmentId;
|
|
328
338
|
|
|
329
339
|
// 1. Out, minted by the agent application.
|
|
330
|
-
const result = await connection.execute({ assignmentId, command: { type: "
|
|
340
|
+
const result = await connection.execute({ assignmentId, command: { type: "add-to-call", dialId: "dial-7f2", contactId: "c-17" } });
|
|
331
341
|
|
|
332
342
|
// 2. Back on the result, restated, so the agent application compares and confirms.
|
|
333
343
|
expect(result).toEqual({ status: "dialling", dialId: "dial-7f2" });
|
|
334
344
|
|
|
335
345
|
// 3. On the outcome, however late, against the task it belonged to.
|
|
336
|
-
const outcome: ProviderEvent<"voice"> = { type: "dial-outcome", dialId: "dial-7f2", assignmentId,
|
|
346
|
+
const outcome: ProviderEvent<"voice"> = { type: "dial-outcome", dialId: "dial-7f2", assignmentId, contactId: "c-17", outcome: "no-answer", reason: "No route to destination" };
|
|
337
347
|
|
|
338
348
|
// 4. In the record, so a dial made before a take-over is placeable by whoever holds the task now.
|
|
339
|
-
const step: TaskHistoryStep = { step: "unanswered", at: "2026-08-21T09:15:30Z", by: "A-12", dialId: "dial-7f2",
|
|
349
|
+
const step: TaskHistoryStep = { step: "unanswered", at: "2026-08-21T09:15:30Z", by: "A-12", dialId: "dial-7f2", contactId: "c-17" };
|
|
340
350
|
```
|
|
341
351
|
|
|
342
352
|
The identity is a correlation handle between agent application and provider and **is never shown to the
|
|
@@ -352,11 +362,11 @@ nothing, is refused (`result.status`). `validateResult(result, method, path, dia
|
|
|
352
362
|
`dialId` the agent application sent for that reason.
|
|
353
363
|
|
|
354
364
|
**The outcome is stated, once, either way.** A `dial-outcome` names the `dialId`, the task where
|
|
355
|
-
there was one, the
|
|
365
|
+
there was one, the contact it went to where there was one, and how the dial ended -- from a closed
|
|
356
366
|
set: `answered`, `busy`, `no-answer`, `unreachable`, `rejected`, `cancelled`, `unexplained`.
|
|
357
367
|
`answered` is stated rather than read off somebody appearing on the call, because an agent application that infers
|
|
358
368
|
success cannot tell "reached" from "still ringing". `cancelled` is the dialler calling the dial off
|
|
359
|
-
before anyone answered -- the agent hanging up while
|
|
369
|
+
before anyone answered -- the agent hanging up while an added colleague still rings -- which is not a
|
|
360
370
|
`no-answer` the destination never gave. `unexplained` is the switch dropping the call with no cause among
|
|
361
371
|
those named here: a statement about the switch, sent instead of the nearest cause it did not give.
|
|
362
372
|
`reason` is the switch's own words, optional, and shown to the agent attributed to the switch rather
|
|
@@ -393,7 +403,7 @@ provider does report -- `busy`, `no-answer`, `unreachable`, `rejected` or `cance
|
|
|
393
403
|
switch gave none, while one that reports none would be sending the generic failure this set exists
|
|
394
404
|
to refuse. A provider that dials at all declares it: an idle
|
|
395
405
|
dialpad requires it (`manifest.dialOutcomes.required`), and a task that declares `connectBack`
|
|
396
|
-
or `
|
|
406
|
+
or `addToCall` under a manifest without it is refused
|
|
397
407
|
(`task.capability.dialOutcomes.required`). Off voice nothing dials, and the field is a compile
|
|
398
408
|
error there.
|
|
399
409
|
|
|
@@ -405,14 +415,14 @@ knows the room:
|
|
|
405
415
|
const onCall: OnCall[] = [
|
|
406
416
|
{ role: "party", since: "2026-08-21T09:12:00Z" },
|
|
407
417
|
{ role: "agent", userId: "A-12", since: "2026-08-21T09:12:04Z" },
|
|
408
|
-
{ role: "
|
|
409
|
-
{ role: "
|
|
418
|
+
{ role: "added", contactId: "c-17", dialId: "dial-7f2", stage: "joined", held: true, since: "2026-08-21T09:15:30Z" },
|
|
419
|
+
{ role: "added", contactId: "c-20", dialId: "dial-3c9", stage: "ringing", since: "2026-08-21T09:16:02Z" },
|
|
410
420
|
];
|
|
411
421
|
```
|
|
412
422
|
|
|
413
423
|
`party` is the customer and `agent` a person by user id; neither was dialled from anywhere, so
|
|
414
|
-
neither carries a destination. A `
|
|
415
|
-
`
|
|
424
|
+
neither carries a destination. A `added` colleague was, so the entry carries the
|
|
425
|
+
`contactId` of its entry in the provider's contacts, a typed number's included, and, where an agent application's dial brought them, its `dialId`; a person
|
|
416
426
|
the platform added itself carries none. `held: true` is presence as claim. A snapshot establishes state, so an agent application that attaches
|
|
417
427
|
after a take-over reads the room from here rather than inferring it from a sequence of outcomes it
|
|
418
428
|
never saw.
|
|
@@ -436,10 +446,10 @@ describing the room live was never followed by one saying it had emptied, and ev
|
|
|
436
446
|
derived anything from it was wrong in a way that looked like its own bug.
|
|
437
447
|
|
|
438
448
|
**A dialled entry is listed from the moment the dial is placed, not from the answer.** The entry is
|
|
439
|
-
what `
|
|
449
|
+
what `addToCall` `remove` names, and a destination the agent cannot call off while it rings is a
|
|
440
450
|
customer kept waiting with no way back -- which is the very case `cancelled` exists for. The
|
|
441
|
-
`
|
|
442
|
-
naming a still-ringing `
|
|
451
|
+
`added` entry appears with its `dialId` when the dial is placed, and a `addToCall` `remove`
|
|
452
|
+
naming a still-ringing `contactId` calls that dial off, with `cancelled` as its outcome.
|
|
443
453
|
|
|
444
454
|
**The entry says where it stands.** A dialled entry carries `stage`: `ringing` until its dial is
|
|
445
455
|
answered, `joined` after. The `dial-outcome` is the transition and the stage is the state, the same
|
|
@@ -548,7 +558,7 @@ recording, and what the agent sees is the recording. Retention is not a promise
|
|
|
548
558
|
audio.
|
|
549
559
|
|
|
550
560
|
Provider commands go only to `Connection.execute`; agent application commands go only to
|
|
551
|
-
`HostRecording.execute`. Both name the assignment. Ids are opaque and scoped by provider
|
|
561
|
+
`HostRecording.execute`. Both name the assignment. Ids are opaque and scoped by provider session,
|
|
552
562
|
task and recorder; they are never inferred from filenames or the current agent. Reconnect creates
|
|
553
563
|
no recording; the recorder restates its list. There is no automatic restart, hand-over to another
|
|
554
564
|
recorder, or stop on task hold or disconnect. Task removal does not prove recording stopped:
|