@xema/omni-protocol 0.1.129 → 0.1.131
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 +145 -94
- package/dist/index.js +27 -12
- package/dist/testing.d.ts +18 -18
- package/dist/testing.js +89 -92
- package/dist/validation.d.ts +23 -23
- package/dist/validation.js +178 -125
- package/guide/agent.md +34 -34
- 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 +168 -148
- package/package.json +1 -1
package/GLOSSARY.md
CHANGED
|
@@ -20,7 +20,7 @@ for orientation only: each platform's own documentation is the authority on its
|
|
|
20
20
|
| **Agent computer** | The agent's screen and machine, where the agent application runs. | *Desktop*, *workstation*, *station*. |
|
|
21
21
|
| **Manifest** | What a provider declares about itself up front: its name, channel, phones and features. | *Integration definition*, *app manifest* (Twilio Flex plugins, Salesforce call center definition file). |
|
|
22
22
|
| **Channel** | The kind of work: voice, chat or email. | *Media type* (Genesys Cloud), *channel* (Amazon Connect, Salesforce Omni-Channel), *media* (NICE). |
|
|
23
|
-
| **
|
|
23
|
+
| **Session** | One agent signed in on one provider, from sign-in until it ends. | *Session*, *agent session*. |
|
|
24
24
|
|
|
25
25
|
## The work
|
|
26
26
|
|
|
@@ -58,7 +58,7 @@ for orientation only: each platform's own documentation is the authority on its
|
|
|
58
58
|
| **Mute** | Silence the agent's microphone. The caller hears nothing from the agent. | The same everywhere. |
|
|
59
59
|
| **End call** | End the agent's part. The caller carries on to wherever the provider sends them, such as a survey. | *Leave*, *drop*, *hang up* (agent leg only). |
|
|
60
60
|
| **Terminate call** | End the whole call for everyone. | *Disconnect all*, *end conversation*. |
|
|
61
|
-
| **
|
|
61
|
+
| **Add to call** | Bring someone onto the call while the agent stays; they leave when the agent ends their part. | *Conference*, *add participant*, *three-way call*. |
|
|
62
62
|
| **Connect back** | Call the customer again after the call has ended, during the wrap. | *Callback from wrap*, *re-dial*. |
|
|
63
63
|
| **Schedule** | Put a follow-up with this customer on the calendar. | *Scheduled callback* (Amazon Connect, Genesys Cloud), *personal callback* (Five9). |
|
|
64
64
|
| **Callback requested** | The customer asked to be called back, or an agent arranged it. | *Queued callback* (Amazon Connect), *callback* (Genesys Cloud), *virtual hold*. |
|
package/README.md
CHANGED
|
@@ -47,7 +47,7 @@ at such as `snapshot.tasks[0].browsers[1].url`, and a `message`.
|
|
|
47
47
|
|
|
48
48
|
Some rules need more than the object in hand. A team member list never carries the agent it is published to,
|
|
49
49
|
a lead's snapshot always carries one and nobody else's ever does — and a validator cannot know who
|
|
50
|
-
is reading, or what their
|
|
50
|
+
is reading, or what their session declares, from the snapshot alone. `validateTeamMembers`,
|
|
51
51
|
`validateSnapshot`, and `validateEventEnvelope` each take an optional final `{ self, capabilities }`
|
|
52
52
|
from the `authenticated` state; given them, they report `team.member.self`, `team.request.self`,
|
|
53
53
|
`team.required`, `team.unentitled`, `team.requests.capability`, and `team.requests.required`.
|
|
@@ -62,14 +62,14 @@ validateSnapshot(snapshot, manifest, "snapshot", { self: identity.id, capabiliti
|
|
|
62
62
|
|
|
63
63
|
`testAdapter` validates the manifest, opens an authenticated session, connects, checks
|
|
64
64
|
required capability methods, subscribes, validates the snapshot, every delivered event, and every
|
|
65
|
-
authentication state published during the run — against the latest
|
|
65
|
+
authentication state published during the run — against the latest session — states a capacity,
|
|
66
66
|
then unsubscribes and disconnects. `result.notTested` names what the run never reached — each
|
|
67
67
|
optional part of a task, of the break state and team member list, each contribution, each event type — so a
|
|
68
68
|
clean result is read for what it covers and not for the whole contract; `assertReached(result,
|
|
69
69
|
subjects)` is the paired assertion.
|
|
70
70
|
|
|
71
71
|
```ts
|
|
72
|
-
const context = { protocolVersion: OMNI_PROTOCOL_VERSION,
|
|
72
|
+
const context = { protocolVersion: OMNI_PROTOCOL_VERSION, sessionId: "session-1", host: stillHost(report) };
|
|
73
73
|
const result = await testAdapter(adapter, context, { collectOnly: true });
|
|
74
74
|
expect(result.violations).toEqual([]);
|
|
75
75
|
expect(result.disconnectWasClean).toBe(true);
|
|
@@ -102,14 +102,12 @@ const task = {
|
|
|
102
102
|
|
|
103
103
|
**Switch on `command.action` with no `default`.** A `default` turns a future action into whatever
|
|
104
104
|
the default does, silently; naming every arm means dropping one fails the build — indirectly, as a
|
|
105
|
-
missing return — and keeps the narrowing that lets you read `
|
|
105
|
+
missing return — and keeps the narrowing that lets you read `dialId` without a cast.
|
|
106
106
|
|
|
107
107
|
```ts
|
|
108
108
|
switch (command.action) {
|
|
109
|
-
case "
|
|
110
|
-
case "
|
|
111
|
-
case "complete": return completeWarmTransfer();
|
|
112
|
-
case "cancel": return cancelWarmTransfer();
|
|
109
|
+
case "add": return addToCall(command.dialId, command.contactId ?? command.number);
|
|
110
|
+
case "remove": return removeFromCall(command.party === true ? "party" : command.contactId);
|
|
113
111
|
}
|
|
114
112
|
```
|
|
115
113
|
|
package/dist/index.d.ts
CHANGED
|
@@ -27,8 +27,8 @@ export type UserId = string;
|
|
|
27
27
|
/**
|
|
28
28
|
* The provider's name for one assignment: the call routed to this agent, from the offer until the
|
|
29
29
|
* task ends. Non-empty, opaque, unique within the provider and never reused while the provider is
|
|
30
|
-
* still speaking about it -- a lead names a member's assignment from another
|
|
31
|
-
* the provider, not the
|
|
30
|
+
* still speaking about it -- a lead names a member's assignment from another session, so the scope is
|
|
31
|
+
* the provider, not the session. What the platform calls its own record, and whether it reuses that
|
|
32
32
|
* name, is the adapter's business: a platform that reoffers a closed call under the same handle
|
|
33
33
|
* seconds later is why the adapter, not the agent computer, is held to this. Scope it with `assignmentKey()`.
|
|
34
34
|
*/
|
|
@@ -108,7 +108,7 @@ export declare const DIAL_OUTCOMES: readonly ["answered", "busy", "no-answer", "
|
|
|
108
108
|
* How the agent hears the call: on a `softphone`, where the host owns the audio and opens it
|
|
109
109
|
* through `openAudio`, or on a `hardphone`, a handset the platform rings, where the host opens
|
|
110
110
|
* nothing and only shows the call. A voice manifest lists the phones its platform supports, and
|
|
111
|
-
* the host picks one for the
|
|
111
|
+
* the host picks one for the session at authentication.
|
|
112
112
|
*/
|
|
113
113
|
export type Phone = "softphone" | "hardphone";
|
|
114
114
|
export declare const PHONES: readonly ["softphone", "hardphone"];
|
|
@@ -124,7 +124,7 @@ export type PhoneChannelState = "ringing" | "active" | "held";
|
|
|
124
124
|
export declare const PHONE_CHANNEL_STATES: readonly ["ringing", "active", "held"];
|
|
125
125
|
/**
|
|
126
126
|
* One call on the phone, as the phone sees it: ringing, the one active, or held. A bridge is one
|
|
127
|
-
* channel, so a
|
|
127
|
+
* channel, so a call with people added is one entry and they are on the task's `onCall`. Where the call
|
|
128
128
|
* is a task's, `assignmentId` names it and the two views agree; absent, the call is the phone's
|
|
129
129
|
* alone -- an internal call on the extension, a lead's listening leg.
|
|
130
130
|
*/
|
|
@@ -134,7 +134,7 @@ export interface PhoneChannel {
|
|
|
134
134
|
assignmentId?: AssignmentId;
|
|
135
135
|
}
|
|
136
136
|
/**
|
|
137
|
-
* The phone's own view, published by a provider that declares `phoneStatus`: the device the
|
|
137
|
+
* The phone's own view, published by a provider that declares `phoneStatus`: the device the session
|
|
138
138
|
* is on, whether it can take a call, its own mute where the platform observes it, and its channels
|
|
139
139
|
* -- one active at most, any number held. The task side says which of those calls are the agent's
|
|
140
140
|
* work and where each stands; the phone side exists whether or not a task is behind a call. `muted`
|
|
@@ -142,7 +142,7 @@ export interface PhoneChannel {
|
|
|
142
142
|
* never a softphone's, whose microphone is the host's and whose mute is the host's report.
|
|
143
143
|
*/
|
|
144
144
|
export interface PhoneState {
|
|
145
|
-
/** The agent's phone for this provider, as the host chose it for the
|
|
145
|
+
/** The agent's phone for this provider, as the host chose it for the session at connect: which of the manifest's phones the agent hears this provider's calls on. */
|
|
146
146
|
phone: Phone;
|
|
147
147
|
status: PhoneStatus;
|
|
148
148
|
/** The phone's own mute, on a hardphone the platform observes; absent where it does not, or on a softphone. */
|
|
@@ -227,12 +227,12 @@ export interface Manifest<C extends Channel = Channel> {
|
|
|
227
227
|
/**
|
|
228
228
|
* The outcomes this platform distinguishes when a dial ends, `answered` and at least one way of
|
|
229
229
|
* not reaching the destination. Required of a provider that dials at all -- an idle dialpad, or
|
|
230
|
-
* a task that may
|
|
230
|
+
* a task that may add to the call or call back -- and forbidden off voice, where nothing dials.
|
|
231
231
|
*/
|
|
232
232
|
dialOutcomes?: C extends "voice" ? DialOutcome[] : never;
|
|
233
233
|
/**
|
|
234
234
|
* The phones this platform can put an agent on. Required of every voice manifest, and forbidden
|
|
235
|
-
* off voice, where there is no call to hear. The host picks one of these per
|
|
235
|
+
* off voice, where there is no call to hear. The host picks one of these per session.
|
|
236
236
|
*/
|
|
237
237
|
phones?: C extends "voice" ? Phone[] : never;
|
|
238
238
|
/**
|
|
@@ -260,21 +260,21 @@ export interface SecretStore {
|
|
|
260
260
|
delete(key: string): Promise<void>;
|
|
261
261
|
}
|
|
262
262
|
/**
|
|
263
|
-
* A small store for one
|
|
263
|
+
* A small store for one session's operational state -- what an adapter holds about open work that
|
|
264
264
|
* its platform cannot hold for it, such as the interaction legs a host reported. Kept by the host for
|
|
265
|
-
* the life of the
|
|
265
|
+
* the life of the session, across a reload of the host, and cleared at sign-out. Never for anything
|
|
266
266
|
* sensitive: that is `SecretStore`, whose contract is that a host may clear it aggressively, and
|
|
267
267
|
* clears it once the session has ended.
|
|
268
268
|
*/
|
|
269
|
-
export interface
|
|
269
|
+
export interface SessionStore {
|
|
270
270
|
get(key: string): Promise<string | undefined>;
|
|
271
271
|
set(key: string, value: string): Promise<void>;
|
|
272
272
|
delete(key: string): Promise<void>;
|
|
273
273
|
}
|
|
274
274
|
export interface AuthenticationContext {
|
|
275
275
|
protocolVersion: number;
|
|
276
|
-
/** Omni's identity for this
|
|
277
|
-
|
|
276
|
+
/** Omni's identity for this session. The same value arrives later as `ConnectContext.sessionId`. */
|
|
277
|
+
sessionId: string;
|
|
278
278
|
/**
|
|
279
279
|
* The zone the agent's day is reckoned in, as the host's clock has it, stated before any
|
|
280
280
|
* identity exists so the first `authenticated` state already carries it. The same value arrives
|
|
@@ -289,7 +289,7 @@ export interface AuthenticationContext {
|
|
|
289
289
|
*/
|
|
290
290
|
languages: readonly LanguageTag[];
|
|
291
291
|
/**
|
|
292
|
-
* How this
|
|
292
|
+
* How this session hears its calls, chosen by the host from the manifest's `phones`. Required for
|
|
293
293
|
* a voice provider and absent for any other. The same value arrives later as `ConnectContext.phone`.
|
|
294
294
|
*/
|
|
295
295
|
phone?: Phone;
|
|
@@ -322,12 +322,12 @@ export interface AuthenticationFailure {
|
|
|
322
322
|
export type ListeningMode = "listen" | "coach" | "join-call";
|
|
323
323
|
export declare const LISTENING_MODES: readonly ["listen", "coach", "join-call"];
|
|
324
324
|
/**
|
|
325
|
-
* What this
|
|
326
|
-
* of who the agent is on this provider: the provider knows the roles and says
|
|
327
|
-
* Current as of the latest `authenticated` state, never fixed for the
|
|
325
|
+
* What this user may do for the session, beyond any one task. It travels with the identity
|
|
326
|
+
* because it is part of who the agent is on this provider: the provider knows the roles and says
|
|
327
|
+
* so at sign-in. Current as of the latest `authenticated` state, never fixed for the session.
|
|
328
328
|
*/
|
|
329
329
|
export interface UserCapabilities {
|
|
330
|
-
/** This
|
|
330
|
+
/** This session may request a break. Requires the four break methods. */
|
|
331
331
|
breaks?: true;
|
|
332
332
|
/**
|
|
333
333
|
* The platform lines calls up for this agent: the agent may press Next call while on one to
|
|
@@ -338,15 +338,48 @@ export interface UserCapabilities {
|
|
|
338
338
|
/** The choices the team left to this person, with where each stands. Omitted when there are none. Requires `setPreference`. */
|
|
339
339
|
preferences?: AgentPreference[];
|
|
340
340
|
/**
|
|
341
|
-
* This
|
|
342
|
-
*
|
|
343
|
-
*
|
|
344
|
-
* assumes nothing of the switch: the
|
|
345
|
-
*
|
|
346
|
-
*
|
|
341
|
+
* This session leads a team, with the lead capabilities it holds for the whole session. Its
|
|
342
|
+
* presence turns on the team feature in the agent application: the lead sees their members with
|
|
343
|
+
* their tasks and stats, and acts on them through `executeTeam` with the commands its lead
|
|
344
|
+
* capabilities allow, and no others. The provider assumes nothing of the switch: the
|
|
345
|
+
* application sends `lead-features` on every connect, and only while it is on does the team
|
|
346
|
+
* reach the lead -- `team-updated` whole after the switch and on any snapshot, then one member at
|
|
347
|
+
* a time as members change; to nobody else, ever.
|
|
347
348
|
*/
|
|
348
|
-
lead?:
|
|
349
|
-
}
|
|
349
|
+
lead?: LeadCapabilities;
|
|
350
|
+
}
|
|
351
|
+
/**
|
|
352
|
+
* What a lead may do, for the whole session: one key per lead command it allows, each stated by
|
|
353
|
+
* presence. Switching the team feature (`lead-features`) and leaving a call (`leave`) are every
|
|
354
|
+
* lead's and are not listed. At least one is stated: a session with none leads nobody.
|
|
355
|
+
*/
|
|
356
|
+
export interface LeadCapabilities {
|
|
357
|
+
join?: true;
|
|
358
|
+
decline?: true;
|
|
359
|
+
listen?: true;
|
|
360
|
+
coach?: true;
|
|
361
|
+
joinCall?: true;
|
|
362
|
+
takeOverCall?: true;
|
|
363
|
+
decideBreakRequest?: true;
|
|
364
|
+
setBreakPolicy?: true;
|
|
365
|
+
forceBreak?: true;
|
|
366
|
+
endForcedBreak?: true;
|
|
367
|
+
setPolicy?: true;
|
|
368
|
+
}
|
|
369
|
+
/** The lead capability each lead command needs; `lead-features` and `leave` need none. */
|
|
370
|
+
export declare const LEAD_COMMAND_CAPABILITY: {
|
|
371
|
+
readonly join: "join";
|
|
372
|
+
readonly decline: "decline";
|
|
373
|
+
readonly listen: "listen";
|
|
374
|
+
readonly coach: "coach";
|
|
375
|
+
readonly "join-call": "joinCall";
|
|
376
|
+
readonly "take-over-call": "takeOverCall";
|
|
377
|
+
readonly "decide-break-request": "decideBreakRequest";
|
|
378
|
+
readonly "set-break-policy": "setBreakPolicy";
|
|
379
|
+
readonly "force-break": "forceBreak";
|
|
380
|
+
readonly "end-forced-break": "endForcedBreak";
|
|
381
|
+
readonly "set-policy": "setPolicy";
|
|
382
|
+
};
|
|
350
383
|
/**
|
|
351
384
|
* Only `authenticated` and `refreshing` know who the agent is and what they may do, and only
|
|
352
385
|
* `authenticated` has something to expire. A state carrying more than it knows is a state Omni
|
|
@@ -477,7 +510,7 @@ export declare const MUTED_BY: readonly ["host", "station"];
|
|
|
477
510
|
* What pressing Mute does on this host. `stream`: the host stops the audio it sends, and the
|
|
478
511
|
* microphone keeps capturing. `station`: the host mutes the microphone itself at the operating
|
|
479
512
|
* system, which every application on the machine then shares. A browser can only do the first;
|
|
480
|
-
* a native host says which it does. Stated by the host on a softphone
|
|
513
|
+
* a native host says which it does. Stated by the host on a softphone session, never inferred
|
|
481
514
|
* from what kind of application it is.
|
|
482
515
|
*/
|
|
483
516
|
export type HostMute = "stream" | "station";
|
|
@@ -649,13 +682,13 @@ export interface HostGuarantees {
|
|
|
649
682
|
/**
|
|
650
683
|
* The host's Mute is its own control on any call and is never offered while the task is
|
|
651
684
|
* `paused`; a mute standing when a hold begins stands through it. Required of a softphone
|
|
652
|
-
*
|
|
685
|
+
* session's host and refused of any other, since a hardphone's mute is the handset's.
|
|
653
686
|
*/
|
|
654
687
|
muteUnavailableOnHold?: true;
|
|
655
688
|
}
|
|
656
689
|
export interface ProviderTimeScope {
|
|
657
690
|
providerId: string;
|
|
658
|
-
|
|
691
|
+
sessionId: string;
|
|
659
692
|
}
|
|
660
693
|
/** Best-effort host estimate, never a provider observation or accuracy guarantee. The provider may ignore it and timestamp receipt itself. */
|
|
661
694
|
export interface ProviderTimeEstimate extends ProviderTimeScope {
|
|
@@ -670,7 +703,7 @@ export interface Host {
|
|
|
670
703
|
/** Voice softphone recording support; policy and destination remain per task. */
|
|
671
704
|
recording?: HostRecording;
|
|
672
705
|
guarantees: HostGuarantees;
|
|
673
|
-
/** What pressing Mute does on this host. Stated on a softphone
|
|
706
|
+
/** What pressing Mute does on this host. Stated on a softphone session, where the host holds the microphone; absent on a hardphone and off voice. */
|
|
674
707
|
mute?: HostMute;
|
|
675
708
|
report(): HostReport;
|
|
676
709
|
subscribe(listener: (report: HostReport) => void): Unsubscribe;
|
|
@@ -678,7 +711,7 @@ export interface Host {
|
|
|
678
711
|
export type ConnectContext = {
|
|
679
712
|
protocolVersion: number;
|
|
680
713
|
/** The session that authenticated this connection. */
|
|
681
|
-
|
|
714
|
+
sessionId: string;
|
|
682
715
|
/** Omni-side policy: whether the agent's tasks are accepted without asking them. Stated, never assumed: a host says which. */
|
|
683
716
|
autoAcceptTasks: boolean;
|
|
684
717
|
/**
|
|
@@ -689,9 +722,9 @@ export type ConnectContext = {
|
|
|
689
722
|
timeZone: TimeZone;
|
|
690
723
|
/** The same value passed as `AuthenticationContext.languages`: what the agent reads, most preferred first. */
|
|
691
724
|
languages: readonly LanguageTag[];
|
|
692
|
-
/** Where the adapter keeps this
|
|
693
|
-
store:
|
|
694
|
-
/** The same value passed as `AuthenticationContext.phone`: how this
|
|
725
|
+
/** Where the adapter keeps this session's operational state across a reload of the host. */
|
|
726
|
+
store: SessionStore;
|
|
727
|
+
/** The same value passed as `AuthenticationContext.phone`: how this session hears its calls. Narrowed by the arms below. */
|
|
695
728
|
phone?: Phone;
|
|
696
729
|
/**
|
|
697
730
|
* The host's report of the agent's station, to consult before declaring the agent ready to the
|
|
@@ -731,11 +764,11 @@ export type ConnectContext = {
|
|
|
731
764
|
});
|
|
732
765
|
export type TransportStatus = "connecting" | "active" | "error";
|
|
733
766
|
/**
|
|
734
|
-
* What revives a connection that reported `error`: `reconnect` -- the
|
|
767
|
+
* What revives a connection that reported `error`: `reconnect` -- the session is good, dispose this
|
|
735
768
|
* connection and call `connect()` again -- or `reauthenticate` -- run the authentication flow
|
|
736
769
|
* first. The adapter knows which; the host acts on its word.
|
|
737
770
|
*/
|
|
738
|
-
/** What revives an errored connection: `displaced` says another client took the
|
|
771
|
+
/** What revives an errored connection: `displaced` says another client took the session, and nothing revives this one until the agent takes it back. */
|
|
739
772
|
export type TransportRecovery = "reconnect" | "reauthenticate" | "displaced";
|
|
740
773
|
/** Every field is optional: a provider sends what it knows and omits what it does not. */
|
|
741
774
|
export interface Contact {
|
|
@@ -746,6 +779,15 @@ export interface Contact {
|
|
|
746
779
|
email?: Lockable<string>;
|
|
747
780
|
attributes?: Attribute[];
|
|
748
781
|
}
|
|
782
|
+
/**
|
|
783
|
+
* One entry of the provider's contacts, the agent computer's directory: a unique `id`, which is how
|
|
784
|
+
* the wire names this contact on a call, in its history and on a dial's outcome, with the name and
|
|
785
|
+
* the number, either of which may be absent or withheld. The agent computer shows the name it holds
|
|
786
|
+
* for an id.
|
|
787
|
+
*/
|
|
788
|
+
export interface ContactEntry extends Contact {
|
|
789
|
+
id: string;
|
|
790
|
+
}
|
|
749
791
|
export interface ScheduledActivity {
|
|
750
792
|
id: string;
|
|
751
793
|
title: string;
|
|
@@ -766,17 +808,15 @@ export interface OutcomeRules {
|
|
|
766
808
|
codes?: OutcomeCode[];
|
|
767
809
|
}
|
|
768
810
|
/**
|
|
769
|
-
*
|
|
770
|
-
*
|
|
771
|
-
*
|
|
811
|
+
* Whom the agent may add to the call, in the dialpad's own words: `contacts-only`, an entry of
|
|
812
|
+
* this provider's contacts, named by its `id`; or `any-number`, a number the agent types as well.
|
|
813
|
+
* `contactIds` narrows the contacts this task offers to those ids -- a billing call offering the
|
|
814
|
+
* billing specialist and the translator line -- and omitted, every contact is offered. Ids only: the names are the
|
|
815
|
+
* agent computer's, from the contacts.
|
|
772
816
|
*/
|
|
773
|
-
export interface
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
}
|
|
777
|
-
/** The items a conference control offers. Nothing is typed; the agent picks one. */
|
|
778
|
-
export interface DestinationDirectory {
|
|
779
|
-
destinations: Destination[];
|
|
817
|
+
export interface AddToCallCapability {
|
|
818
|
+
destinations: DialDestinations;
|
|
819
|
+
contactIds?: string[];
|
|
780
820
|
}
|
|
781
821
|
export interface CustomCapability {
|
|
782
822
|
id: string;
|
|
@@ -814,7 +854,7 @@ export type TaskCapabilities<C extends Channel = Channel> = C extends "voice" ?
|
|
|
814
854
|
schedule?: Lockable<true>;
|
|
815
855
|
/** Ask a lead to join this call, with a note. The lead's decision arrives on `Task.leadAssist`. */
|
|
816
856
|
leadAssist?: Lockable<true>;
|
|
817
|
-
|
|
857
|
+
addToCall?: Lockable<AddToCallCapability>;
|
|
818
858
|
recording?: Lockable<TaskRecordingPolicy>;
|
|
819
859
|
} : C extends "chat" ? SharedTaskCapabilities & {
|
|
820
860
|
decline?: Lockable<true>;
|
|
@@ -848,19 +888,19 @@ export interface Browser {
|
|
|
848
888
|
}
|
|
849
889
|
/**
|
|
850
890
|
* A tab the task brought: fixed at the task's definition -- count and details -- with why it is
|
|
851
|
-
* there, whether its
|
|
891
|
+
* there, whether its profile is shared across tasks, and whether the agent may read its URL. The
|
|
852
892
|
* union is what makes a reusing browser with no scheme fail to compile rather than inherit a
|
|
853
|
-
* default -- which is how two tasks end up sharing a
|
|
893
|
+
* default -- which is how two tasks end up sharing a profile nobody intended.
|
|
854
894
|
*/
|
|
855
895
|
export type TaskBrowser = Browser & {
|
|
856
896
|
purpose: string;
|
|
857
897
|
/** Hide this tab's URL from the agent in Omni's chrome. Omitted, the URL shows as any browser's does; a provider says `hidden` where the URL carries what the agent may not read. */
|
|
858
898
|
urlVisibility?: UrlVisibility;
|
|
859
899
|
} & ({
|
|
860
|
-
|
|
900
|
+
sharedProfile: false;
|
|
861
901
|
isolationScheme?: never;
|
|
862
902
|
} | {
|
|
863
|
-
|
|
903
|
+
sharedProfile: true;
|
|
864
904
|
isolationScheme: BrowserIsolationScheme;
|
|
865
905
|
});
|
|
866
906
|
/** A tab the agent opened in the personal workspace: theirs, as many as they like, and never on the wire. */
|
|
@@ -903,7 +943,7 @@ export type TaskAttribute = TaskAttributeBase & ({
|
|
|
903
943
|
type: "timestamp";
|
|
904
944
|
at: IsoTimestamp;
|
|
905
945
|
});
|
|
906
|
-
export type HistoryStep = "arrived" | "self-service" | "queued" | "offered" | "answered" | "held" | "muted" | "transferred" | "
|
|
946
|
+
export type HistoryStep = "arrived" | "self-service" | "queued" | "offered" | "answered" | "held" | "muted" | "transferred" | "added" | "unanswered" | "callback-requested";
|
|
907
947
|
/**
|
|
908
948
|
* The call record: the steps that brought the task here, one entry per occurrence and oldest
|
|
909
949
|
* first, and what they add up to before this agent -- stated by the provider from its own record,
|
|
@@ -926,11 +966,12 @@ export interface TaskHistoryStep {
|
|
|
926
966
|
step: HistoryStep;
|
|
927
967
|
at: IsoTimestamp;
|
|
928
968
|
/**
|
|
929
|
-
* On a step that dialled -- `transferred`, `
|
|
930
|
-
* that dial when a host placed it, and the
|
|
969
|
+
* On a step that dialled -- `transferred`, `added`, `unanswered` -- the host's identity for
|
|
970
|
+
* that dial when a host placed it, and the contact it went to, by the contacts entry's `id`. Neither
|
|
971
|
+
* belongs on any other step.
|
|
931
972
|
*/
|
|
932
973
|
dialId?: DialId;
|
|
933
|
-
|
|
974
|
+
contactId?: string;
|
|
934
975
|
/**
|
|
935
976
|
* Reported, never derived. An entry may be written while its leg is still running, so there is
|
|
936
977
|
* no end to subtract from -- and omitted is the honest report of that, where nought would
|
|
@@ -961,18 +1002,20 @@ export type TaskCompletion = {
|
|
|
961
1002
|
completionMode: "provider-automatic";
|
|
962
1003
|
wrapAllowance: DurationSeconds;
|
|
963
1004
|
};
|
|
964
|
-
export type OnCallRole = "party" | "agent" | "
|
|
1005
|
+
export type OnCallRole = "party" | "agent" | "added";
|
|
965
1006
|
/** Where a dialled entry stands: `ringing` until its dial is answered, `joined` after. */
|
|
966
1007
|
export type OnCallStage = "ringing" | "joined";
|
|
967
|
-
export declare const ON_CALL_ROLES: readonly ["party", "agent", "
|
|
1008
|
+
export declare const ON_CALL_ROLES: readonly ["party", "agent", "added"];
|
|
968
1009
|
/**
|
|
969
1010
|
* Somebody on the call, or being brought onto it, as the provider states it: who, since when, and
|
|
970
|
-
* whether they are held aside. `party` is the customer; `agent` a person, by user id; `
|
|
1011
|
+
* whether they are held aside. `party` is the customer; `agent` a person, by user id; `added`
|
|
971
1012
|
* someone a dial is bringing in -- listed from the moment the dial is placed, so the agent can call
|
|
972
|
-
* it off while it rings -- carrying the dial when a host placed it, the
|
|
1013
|
+
* it off while it rings -- carrying the dial when a host placed it, the contact either way (the
|
|
1014
|
+
* `contactId` of its entry in the provider's contacts, a typed number included), and the
|
|
973
1015
|
* `stage` it has reached: `ringing` until the dial is answered, `joined` after, stated so a snapshot
|
|
974
1016
|
* says who is present without anyone having seen the outcome. Nobody ringing is held. `label` names
|
|
975
|
-
* a
|
|
1017
|
+
* a person or a line -- not a phrase. `coaching` marks a lead the agent alone hears,
|
|
1018
|
+
* present while they coach and gone when they stop. At most one `party`. The `party`
|
|
976
1019
|
* carries a `stage` while being dialled -- by any host dial, a dialpad call, a preview Call or a
|
|
977
1020
|
* connect-back, carrying its `dialId`, or by a callback the platform places itself, carrying none --
|
|
978
1021
|
* `ringing` from the moment the dial is placed, `joined` on the publication that follows its
|
|
@@ -994,9 +1037,10 @@ export type OnCall = {
|
|
|
994
1037
|
} | {
|
|
995
1038
|
role: "agent";
|
|
996
1039
|
userId: UserId;
|
|
1040
|
+
coaching?: true;
|
|
997
1041
|
} | {
|
|
998
|
-
role: "
|
|
999
|
-
|
|
1042
|
+
role: "added";
|
|
1043
|
+
contactId: string;
|
|
1000
1044
|
stage: OnCallStage;
|
|
1001
1045
|
dialId?: DialId;
|
|
1002
1046
|
label?: string;
|
|
@@ -1158,7 +1202,7 @@ export type TaskOutcome = {
|
|
|
1158
1202
|
failure: ProtocolFailure;
|
|
1159
1203
|
};
|
|
1160
1204
|
export declare const TASK_COMMAND_NAMES: {
|
|
1161
|
-
readonly voice: readonly ["answer", "decline", "dial", "hold", "resume", "end-call", "terminate-call", "connect-back", "lead-assist", "
|
|
1205
|
+
readonly voice: readonly ["answer", "decline", "dial", "hold", "resume", "end-call", "terminate-call", "connect-back", "lead-assist", "add-to-call", "remove-from-call", "recording", "schedule", "complete"];
|
|
1162
1206
|
readonly chat: readonly ["accept", "decline", "pause", "resume", "schedule", "complete"];
|
|
1163
1207
|
readonly email: readonly ["accept", "decline", "schedule", "complete"];
|
|
1164
1208
|
};
|
|
@@ -1208,29 +1252,36 @@ export type VoiceTaskCommand = {
|
|
|
1208
1252
|
type: "lead-assist";
|
|
1209
1253
|
action: "cancel";
|
|
1210
1254
|
}
|
|
1211
|
-
/**
|
|
1255
|
+
/**
|
|
1256
|
+
* Dial a contact into the call: an entry of the provider's contacts by `contactId`, or, where the
|
|
1257
|
+
* capability allows `any-number`, a `number` the agent typed, which the provider enters in its
|
|
1258
|
+
* contacts under an id of its own. Gated by `addToCall`.
|
|
1259
|
+
*/
|
|
1212
1260
|
| {
|
|
1213
|
-
type: "
|
|
1214
|
-
|
|
1261
|
+
type: "add-to-call";
|
|
1262
|
+
dialId: DialId;
|
|
1263
|
+
contactId: string;
|
|
1264
|
+
number?: never;
|
|
1265
|
+
} | {
|
|
1266
|
+
type: "add-to-call";
|
|
1215
1267
|
dialId: DialId;
|
|
1216
|
-
|
|
1268
|
+
number: string;
|
|
1269
|
+
contactId?: never;
|
|
1217
1270
|
}
|
|
1218
1271
|
/**
|
|
1219
1272
|
* Remove one person from the call, named as `onCall` names them, and the call goes on for the
|
|
1220
|
-
* rest: a `
|
|
1273
|
+
* rest: a `added` entry by its `contactId`, which while it still rings calls the dial
|
|
1221
1274
|
* off, or the `party`, leaving the agent with the colleague. A remove that would leave the agent
|
|
1222
1275
|
* alone is `end-call`, and a provider answers it `failed`.
|
|
1223
1276
|
*/
|
|
1224
1277
|
| {
|
|
1225
|
-
type: "
|
|
1226
|
-
|
|
1227
|
-
destinationId: string;
|
|
1278
|
+
type: "remove-from-call";
|
|
1279
|
+
contactId: string;
|
|
1228
1280
|
party?: never;
|
|
1229
1281
|
} | {
|
|
1230
|
-
type: "
|
|
1231
|
-
action: "remove";
|
|
1282
|
+
type: "remove-from-call";
|
|
1232
1283
|
party: true;
|
|
1233
|
-
|
|
1284
|
+
contactId?: never;
|
|
1234
1285
|
} | (RecordingCommand & {
|
|
1235
1286
|
source: "provider";
|
|
1236
1287
|
}) | ({
|
|
@@ -1547,7 +1598,7 @@ export interface Shift {
|
|
|
1547
1598
|
events?: ShiftEvent[];
|
|
1548
1599
|
}
|
|
1549
1600
|
/**
|
|
1550
|
-
* The lead's view of their team: published to a
|
|
1601
|
+
* The lead's view of their team: published to a user whose capabilities include `lead` while the
|
|
1551
1602
|
* lead has the team feature on, and to nobody else. Whole on `team-updated` -- after the switch,
|
|
1552
1603
|
* and on any snapshot -- and from then on one member at a time: `team-member-updated` carries the
|
|
1553
1604
|
* member whole, so applying it twice changes nothing, and `team-member-removed` takes one off.
|
|
@@ -1761,7 +1812,7 @@ export type PreferenceResult = {
|
|
|
1761
1812
|
};
|
|
1762
1813
|
export interface Snapshot<C extends Channel = Channel> {
|
|
1763
1814
|
transport: TransportStatus;
|
|
1764
|
-
|
|
1815
|
+
sessionId: string;
|
|
1765
1816
|
/**
|
|
1766
1817
|
* The provider's own instant of this read, required of a provider that declares `timeCheck`:
|
|
1767
1818
|
* every duration the agent computer renders off the active call is counted from the provider's clock, and
|
|
@@ -1773,7 +1824,7 @@ export interface Snapshot<C extends Channel = Channel> {
|
|
|
1773
1824
|
tasks: Task<C>[];
|
|
1774
1825
|
/** The provider's own count of those tasks, stated rather than inferred: it must equal `tasks.length`, so a blank or unanswered state can never pass as a confirmed empty. */
|
|
1775
1826
|
taskCount: number;
|
|
1776
|
-
contacts?:
|
|
1827
|
+
contacts?: ContactEntry[];
|
|
1777
1828
|
calendar?: ScheduledActivity[];
|
|
1778
1829
|
/** The agent's own day so far, as the provider counts it; replaced whole by `shift-updated`. Omitted where the provider cannot say. */
|
|
1779
1830
|
shift?: Shift;
|
|
@@ -1858,7 +1909,7 @@ export type ProviderEvent<C extends Channel = Channel> = {
|
|
|
1858
1909
|
dialId: DialId;
|
|
1859
1910
|
outcome: DialOutcome;
|
|
1860
1911
|
assignmentId?: AssignmentId;
|
|
1861
|
-
|
|
1912
|
+
contactId?: string;
|
|
1862
1913
|
reason?: string;
|
|
1863
1914
|
} | {
|
|
1864
1915
|
type: "announcement";
|
|
@@ -1892,7 +1943,7 @@ export type ProviderEvent<C extends Channel = Channel> = {
|
|
|
1892
1943
|
policies: TeamPolicies;
|
|
1893
1944
|
} | {
|
|
1894
1945
|
type: "contacts-updated";
|
|
1895
|
-
contacts:
|
|
1946
|
+
contacts: ContactEntry[];
|
|
1896
1947
|
} | {
|
|
1897
1948
|
type: "calendar-updated";
|
|
1898
1949
|
calendar: ScheduledActivity[];
|
|
@@ -1929,8 +1980,8 @@ export type ProviderEvent<C extends Channel = Channel> = {
|
|
|
1929
1980
|
*/
|
|
1930
1981
|
export interface ProviderEventEnvelope<C extends Channel = Channel> {
|
|
1931
1982
|
id: string;
|
|
1932
|
-
/** The
|
|
1933
|
-
|
|
1983
|
+
/** The session this belongs to. */
|
|
1984
|
+
sessionId: string;
|
|
1934
1985
|
occurredAt: IsoTimestamp;
|
|
1935
1986
|
event: ProviderEvent<C>;
|
|
1936
1987
|
}
|
|
@@ -1961,7 +2012,7 @@ export interface ProviderTimeCheckRequest {
|
|
|
1961
2012
|
}
|
|
1962
2013
|
export interface ProviderTimeCheckResult {
|
|
1963
2014
|
requestId: string;
|
|
1964
|
-
|
|
2015
|
+
sessionId: string;
|
|
1965
2016
|
/** Provider clock domain/incarnation; changes on clock discontinuity or authority replacement. */
|
|
1966
2017
|
clockId: string;
|
|
1967
2018
|
/** Provider-domain ISO instant sampled after this request arrived, before its response leaves. */
|
|
@@ -1984,7 +2035,7 @@ export interface Connection<C extends Channel = Channel> {
|
|
|
1984
2035
|
/** Required when the manifest declares `idleCapabilities.dial`. */
|
|
1985
2036
|
dial?(request: DialRequest): Promise<DialResult>;
|
|
1986
2037
|
/**
|
|
1987
|
-
* The four break methods stand or fall together. Declaring `capabilities.breaks` at
|
|
2038
|
+
* The four break methods stand or fall together. Declaring `capabilities.breaks` at sign-in and
|
|
1988
2039
|
* implementing `requestBreak` without `commitBreak` leaves an agent granted a break that can
|
|
1989
2040
|
* never start, and the two-phase coordination has no way to report it.
|
|
1990
2041
|
*/
|
|
@@ -2000,13 +2051,13 @@ export interface Connection<C extends Channel = Channel> {
|
|
|
2000
2051
|
requestNextCall?(): Promise<NextCallResult>;
|
|
2001
2052
|
cancelNextCall?(): Promise<NextCallCancelResult>;
|
|
2002
2053
|
releaseLinedUp?(): Promise<LinedUpReleaseResult>;
|
|
2003
|
-
/** Required when the
|
|
2054
|
+
/** Required when the user's capabilities include `lead`: every lead act, on the team surface and nowhere else. */
|
|
2004
2055
|
executeTeam?(request: TeamCommandRequest): Promise<TeamCommandResult>;
|
|
2005
2056
|
/** Required of a voice adapter whose manifest lists `softphone`: on one, the call's audio lands in Omni. */
|
|
2006
2057
|
openAudio?(request: OpenAudioRequest): Promise<OpenAudioResult>;
|
|
2007
|
-
/** Required when the
|
|
2058
|
+
/** Required when the user's capabilities include `preferences`: the person's own choice, kept by the provider and republished as `authenticated`. */
|
|
2008
2059
|
setPreference?(request: SetPreferenceRequest): Promise<PreferenceResult>;
|
|
2009
|
-
/** Records an interaction leg the host performed. Required of a softphone
|
|
2060
|
+
/** Records an interaction leg the host performed. Required of a softphone session's connection: the host mutes its microphone on any call, and the record is the provider's. */
|
|
2010
2061
|
recordStep?(report: HistoryReport): Promise<HistoryReportResult>;
|
|
2011
2062
|
}
|
|
2012
2063
|
export interface Adapter<C extends Channel = Channel> {
|
|
@@ -2071,7 +2122,7 @@ export declare const DEFAULT_HISTORY_STEP_LABELS: {
|
|
|
2071
2122
|
readonly held: "On hold";
|
|
2072
2123
|
readonly muted: "Muted";
|
|
2073
2124
|
readonly transferred: "Transferred";
|
|
2074
|
-
readonly
|
|
2125
|
+
readonly added: "Added";
|
|
2075
2126
|
readonly unanswered: "Unanswered";
|
|
2076
2127
|
readonly "callback-requested": "Callback requested";
|
|
2077
2128
|
};
|
|
@@ -2102,9 +2153,9 @@ export declare const userKey: (providerId: string, userId: UserId) => string;
|
|
|
2102
2153
|
* `queued` are the ones nobody does, and `callback-requested` is the caller's choice unless an agent arranged it, so none
|
|
2103
2154
|
* of them is here.
|
|
2104
2155
|
*/
|
|
2105
|
-
export declare const HISTORY_STEPS_WITH_A_PERSON: readonly ["offered", "answered", "held", "muted", "transferred", "
|
|
2106
|
-
/** The steps a dial writes, and so the only ones that carry a `dialId` and a `
|
|
2107
|
-
export declare const HISTORY_STEPS_THAT_DIAL: readonly ["transferred", "
|
|
2156
|
+
export declare const HISTORY_STEPS_WITH_A_PERSON: readonly ["offered", "answered", "held", "muted", "transferred", "added", "unanswered"];
|
|
2157
|
+
/** The steps a dial writes, and so the only ones that carry a `dialId` and a `contactId`. */
|
|
2158
|
+
export declare const HISTORY_STEPS_THAT_DIAL: readonly ["transferred", "added", "unanswered"];
|
|
2108
2159
|
export declare const historyStepDials: (step: HistoryStep) => boolean;
|
|
2109
2160
|
/**
|
|
2110
2161
|
* Consecutive entries of one step, shown as one span. The record keeps an entry per occurrence --
|
|
@@ -2122,7 +2173,7 @@ export interface HistorySpan {
|
|
|
2122
2173
|
export declare function historySpans(steps: readonly TaskHistoryStep[]): HistorySpan[];
|
|
2123
2174
|
/** Whether an absent `by` means "could not attribute" rather than "nobody was involved". */
|
|
2124
2175
|
export declare function historyStepExpectsAPerson(step: HistoryStep): boolean;
|
|
2125
|
-
export interface
|
|
2176
|
+
export interface BrowserProfileKeyInput {
|
|
2126
2177
|
/** `Manifest.id`, never `displayName`: only the id is unique across an installation and stable. */
|
|
2127
2178
|
providerId: string;
|
|
2128
2179
|
/** The task's assignment: a task-scoped session lives one assignment, never the next customer's. */
|
|
@@ -2132,7 +2183,7 @@ export interface BrowserSessionKeyInput {
|
|
|
2132
2183
|
browser: TaskBrowser;
|
|
2133
2184
|
}
|
|
2134
2185
|
/**
|
|
2135
|
-
* Whether two
|
|
2186
|
+
* Whether two sessions declare the same capabilities, field by field. The comparison an adapter
|
|
2136
2187
|
* makes before republishing `authenticated`: capabilities are current, not fixed, and the natural
|
|
2137
2188
|
* guard -- comparing the identity -- never fires on a demotion, because the thing that changed is
|
|
2138
2189
|
* not the thing being compared. Key order does not matter, and a withdrawn `lead` is a change.
|
|
@@ -2141,13 +2192,13 @@ export declare function sameCapabilities(a: UserCapabilities, b: UserCapabilitie
|
|
|
2141
2192
|
/**
|
|
2142
2193
|
* The storage-profile key a reusing browser shares, or `undefined` where it shares nothing.
|
|
2143
2194
|
*
|
|
2144
|
-
* Fails closed. A browser with `
|
|
2195
|
+
* Fails closed. A browser with `sharedProfile: false` has no key; nor does a reusing one whose scheme is
|
|
2145
2196
|
* missing or unknown -- the type forbids that, but an adapter compiled against another version can
|
|
2146
2197
|
* still send it, and the safe reading is "do not share", never "share with everyone named the
|
|
2147
2198
|
* same". Every part is encoded, separator included, before joining, so a tab called `a.b`
|
|
2148
2199
|
* cannot collide with a provider called `a` and a tab called `b`.
|
|
2149
2200
|
*/
|
|
2150
|
-
export declare function
|
|
2201
|
+
export declare function browserProfileKey(input: BrowserProfileKeyInput): string | undefined;
|
|
2151
2202
|
/**
|
|
2152
2203
|
* The comparison key for a contact number. Never for display: keep the original value for that.
|
|
2153
2204
|
*
|