@avaya/infinity-elements-api
v1.3.0
Published
InfinityElement API for web components to interact with the Infinity Extensibility Framework
Readme
@avaya/infinity-elements-api v1.3.0
@avaya/infinity-elements-api
Element API for InfinityElements to interact with the Infinity Extensibility Framework. This library provides a robust interface for communication between web components and the Infinity Agent Desktop.
Table of Contents
Installation
npm install @avaya/infinity-elements-apiFeatures
- 🔌 Easy Integration - Simple API for web components to interact with core-agent-ui
- 📡 Event-Driven - Subscribe to interaction events (accepted, ended, status changes)
- 🎯 Type-Safe - Full TypeScript support with comprehensive type definitions
- 📞 Call Management - Complete call control (transfer, consult, hold, mute, etc.)
- 👤 Agent Management - Get/set agent status, access user information
- 💬 Messaging - Send rich media messages and interact with the chat feed
Quick Start
Basic Setup
import { ElementAPI } from "@avaya/infinity-elements-api";
// Create API instance
const api = new ElementAPI();
// Get user information
const userInfo = await api.getUserInfo();
console.log("Agent:", userInfo.firstName, userInfo.lastName);
console.log("Email:", userInfo.email);
// Listen for interaction events
api.onInteractionAccepted((interactionId) => {
console.log("Interaction accepted:", interactionId);
});
api.onInteractionEnded((interactionId) => {
console.log("Interaction ended:", interactionId);
});
// Don't forget to clean up!
// In React: useEffect cleanup, in plain JS: on element unmount
api.destroy();React Example
import { ElementAPI } from "@avaya/infinity-elements-api";
import { useEffect, useState } from "react";
function MyElement() {
const [userInfo, setUserInfo] = useState(null);
useEffect(() => {
const api = new ElementAPI();
// Fetch user info on mount
api.getUserInfo().then(setUserInfo);
// Subscribe to interaction events
const unsubscribe = api.onInteractionAccepted((interactionId) => {
console.log("Interaction accepted:", interactionId);
});
// Cleanup on unmount
return () => {
unsubscribe();
api.destroy();
};
}, [api]);
return (
<div>
<h1>Agent: {userInfo?.displayName}</h1>
<p>Status: {userInfo?.agentStatus}</p>
</div>
);
}Core Concepts
ElementAPI
The main class for interacting with the Infinity Extensibility Framework. It handles:
- API requests to core-agent-ui via
window.postMessage - Event subscriptions for interaction lifecycle
- Inter-element communication via the host (postMessage)
Triggering Workflows
Elements can programmatically trigger AXP workflows using triggerWorkflow(). The host (agent UI) executes the call so credentials are never exposed to the element.
// Trigger a workflow with input parameters
const result = await api.triggerWorkflow({
workflowId: "wf-refund-process",
inputData: { orderId: "ORD-123", amount: 49.99 },
});
console.log("Workflow started:", result.workflowSessionId);Parameters:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| workflowId | string | Yes | ID of the workflow to execute |
| workflowVersion | string | No | Workflow version (host defaults to "latest" when omitted) |
| interactionId | string | No | Interaction context override (auto-attached for interaction-level widgets) |
| inputData | Record<string, unknown> | No | Key/value data forwarded to the workflow as inputs |
Workflow → Element communication pattern:
Workflows communicate results back to elements through the shared interaction object rather than a direct return channel:
- Element calls
triggerWorkflow({ workflowId, inputData }) - Workflow executes (may be short or long-running)
- Workflow writes results via an Update Interaction action, then signals completion with an Interaction Data Reload action
- Element receives
onInteractionDataReloadand reads updated data viagetInteraction()
// Listen for workflow results before triggering
const unsubscribe = api.onInteractionDataReload(async (interactionId) => {
const updated = await api.getInteraction({ interactionId });
console.log("Workflow result:", updated.metadata);
});
// Trigger the workflow
await api.triggerWorkflow({
workflowId: "wf-refund-process",
inputData: { orderId: "ORD-123", amount: 49.99 },
});Notes:
- Any workflow can be triggered — no tagging or pre-registration in IEF is required
- Rate limiting and permissions are enforced by the workflow engine, not by IEF
- Error handling: if the workflow cannot be started (invalid ID, parameters, or permissions), the promise rejects with a structured error
Development
# Install dependencies
npm install
# Build the library
npm run build
# Run tests
npm test
# Watch mode for tests
npm run test:watch
# Generate documentation
npm run docs
# Lint
npm run lintLicense
MIT
Related Packages
@avaya/infinity-elements-sdk- CLI tool for scaffolding InfinityElement projects
API Documentation
DialpadDigit
Defined in: api/ElementAPI.ts:84
DTMF dialpad digits (0-9) for sending tones during calls
Example
import { DialpadDigit } from '@avaya/infinity-elements-api';
await api.sendDialpadDigit(DialpadDigit.Five, null, false);ElementAPI
Defined in: api/ElementAPI.ts:694
ElementAPI - Main API for web components to interact with the Infinity Extensibility Framework
This is the primary interface that elements use to communicate with core-agent-ui. Uses window.postMessage for API requests/responses and events.
Sandboxed Iframe Environment
IMPORTANT: Elements run in sandboxed iframes using srcdoc, which means:
window.location.originreturns"null"(the literal string "null")document.referrermay be empty- Direct access to parent window properties is blocked
- BroadcastChannel doesn't work (requires valid origin for message scoping)
All communication with the host (core-agent-ui) must go through window.postMessage.
The host has a valid origin and can make HTTP requests, handle OAuth, etc.
Examples
import { ElementAPI } from '@avaya/infinity-elements-api';
const api = new ElementAPI({
elementId: 'my-element',
timeout: 5000,
debug: true
});const userInfo = await api.getUserInfo();
console.log('Agent name:', userInfo.firstName, userInfo.lastName);
console.log('Email:', userInfo.email);api.onInteractionAccepted((interactionId) => {
console.log('Interaction accepted:', interactionId);
});
api.onInteractionEnded((interactionId) => {
console.log('Interaction ended:', interactionId);
});Extends
Constructors
Constructor
new ElementAPI(options: ElementAPIOptions): ElementAPI;Defined in: api/ElementAPI.ts:728
Creates a new ElementAPI instance
Parameters
| Parameter | Type |
| ------ | ------ |
| options | ElementAPIOptions |
Returns
Example
const api = new ElementAPI({
elementId: 'my-custom-element',
timeout: 10000,
debug: true
});Overrides
Methods
destroy()
destroy(): void;Defined in: api/ElementAPI.ts:769
Clean up resources when the React component is unmounted or no longer needed
Removes all event listeners, closes channels, and clears pending requests. Call this method in your React component's cleanup/unmount lifecycle.
Returns
void
Example
// In a React component
useEffect(() => {
const api = new ElementAPI();
return () => {
api.destroy(); // Cleanup on unmount
};
}, []);getInteraction()
getInteraction(options?: InteractionContextOptions): Promise<InteractionInfo>;Defined in: api/ElementAPI.ts:820
Get information about the current active interaction
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| options? | InteractionContextOptions | Optional parameters |
Returns
Promise<InteractionInfo>
Promise resolving to the interaction information
Throws
Error if no active interaction exists
Examples
try {
const interaction = await api.getInteraction();
console.log('Interaction ID:', interaction.interactionId);
console.log('Customer:', interaction.customer?.name);
console.log('Status:', interaction.status);
} catch (error) {
console.error('No active interaction');
}const interaction = await api.getInteraction({ interactionId: 'int-123' });
console.log('Status:', interaction.status);getUserInfo()
getUserInfo(): Promise<UserInfo>;Defined in: api/ElementAPI.ts:842
Get information about the current logged-in user/agent
Returns
Promise<UserInfo>
Promise resolving to the user information including agent status, queues, and profile
Example
const userInfo = await api.getUserInfo();
console.log('Agent:', userInfo.firstName, userInfo.lastName);
console.log('Queues:', userInfo.queues);
console.log('Email:', userInfo.email);getAgentState()
getAgentState(): Promise<GetAgentStateResponse>;Defined in: api/ElementAPI.ts:852
Get current agent state from the Agent Desktop cache (RTK / active user).
Does not call the backend; safe to call on element load before any agent-state-changed event.
Returns
Promise<GetAgentStateResponse>
Promise resolving to availability, CX login (isAID), agent id, queues with login flags, etc.
getConfig()
getConfig(): Promise<IEFConfig>;Defined in: api/ElementAPI.ts:890
Get a snapshot of the element's IEF context — the interaction that spawned it (if any), the current user id, the workflow session's engagement id (if active), and the user's CRM configuration.
Safe to call as soon as the element loads — no event waiting required. Returns a point-in-time snapshot; does not subscribe to updates.
The returned object is expandable — future releases may add new properties without breaking existing consumers. Read by property name rather than destructuring against a fixed key set.
Returns
Promise<IEFConfig>
Promise resolving to the IEF context snapshot
Example
const config = await api.getConfig();
// Identity — who the agent is and which customer session this belongs to
console.log('Agent:', config.userId);
console.log('Session:', config.engagementId);
// Interaction context — which interaction spawned this element
if (config.originalInteraction) {
console.log('Channel:', config.originalInteraction.commType);
console.log('Interaction ID:', config.originalInteraction.id);
}
// CRM-aware behaviour — act on admin-configured settings
if (config.crmConfig?.clickToDial) {
enableClickToDial();
}getUserInteractions()
getUserInteractions(params?: GetUserInteractionsParams): Promise<GetUserInteractionsResponse>;Defined in: api/ElementAPI.ts:923
Get user interactions including owned and viewing interactions
Retrieves all active interactions for the current or specified user, including interactions they own and ones they are viewing. Optionally includes queue and user details.
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| params? | GetUserInteractionsParams | Optional parameters |
Returns
Promise<GetUserInteractionsResponse>
Promise resolving to user interactions data
Examples
// Get current user's interactions with full details
const result = await api.getUserInteractions({ details: true });
console.log('Owned interactions:', result.interactions);
console.log('Viewing interactions:', result.viewing);
console.log('Logged in queues:', result.queue.loggedIn);// Get interactions without queue/user details for better performance
const result = await api.getUserInteractions({ details: false });
const totalCount = result.interactions.length + result.viewing.length;
console.log('Total active interactions:', totalCount);getUsers()
getUsers(params?: {
interactionId?: string;
filter?: string;
}): Promise<GetUsersResponse[]>;Defined in: api/ElementAPI.ts:984
Get a list of users in Infinity
Returns users available for transfer or consult operations. Returns up to 100 users.
- App Level (sidebar widgets): Provide
interactionIdparameter - Interaction Level (interaction widgets): Omit
interactionId, uses interaction context automatically
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| params? | { interactionId?: string; filter?: string; } | Optional parameters |
| params.interactionId? | string | Required for app-level widgets, optional for interaction-level widgets |
| params.filter? | string | Optional substring search against user name fields |
Returns
Promise<GetUsersResponse[]>
Promise resolving to array of user information
Examples
const users = await api.getUsers();
users.forEach(user => {
console.log(`${user.fullName} - ${user.cxStatus.status} - ${user.presence}`);
});const users = await api.getUsers({ filter: 'john' });
console.log('Found users:', users.map(u => u.fullName));const users = await api.getUsers({ interactionId: 'int-123' });
users.forEach(user => {
console.log(`${user.fullName} - ${user.cxStatus.status} - ${user.presence}`);
});const users = await api.getUsers({
interactionId: 'int-123',
filter: 'john'
});const users = await api.getUsers({ filter: searchInput });
const eligibleUsers = users.filter(u => u.eligible);
eligibleUsers.forEach(user => {
console.log(`${user.fullName} (${user.extension}) - ${user.cxStatus.status}`);
});viewerRemoveInteraction()
viewerRemoveInteraction(options?: InteractionContextOptions): Promise<{
message: string;
}>;Defined in: api/ElementAPI.ts:1008
Remove the current interaction from the viewer
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| options? | InteractionContextOptions | Optional parameters |
Returns
Promise<{
message: string;
}>
Promise resolving to a success message
Examples
await api.viewerRemoveInteraction();await api.viewerRemoveInteraction({ interactionId: 'int-123' });endInteraction()
endInteraction(options?: InteractionContextOptions): Promise<{
message: string;
}>;Defined in: api/ElementAPI.ts:1037
End the current interaction
Terminates the active interaction and disconnects the call.
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| options? | InteractionContextOptions | Optional parameters |
Returns
Promise<{
message: string;
}>
Promise resolving to a success message
Examples
await api.endInteraction();
console.log('Interaction ended');await api.endInteraction({ interactionId: 'int-123' });startVoiceCall()
startVoiceCall(options?: InteractionContextOptions): Promise<{
message: string;
}>;Defined in: api/ElementAPI.ts:1063
Start a voice call for the current interaction
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| options? | InteractionContextOptions | Optional parameters |
Returns
Promise<{
message: string;
}>
Promise resolving to a success message
Examples
await api.startVoiceCall();await api.startVoiceCall({ interactionId: 'int-123' });createVoiceInteraction()
createVoiceInteraction(params: CreateVoiceInteractionParams): Promise<{
message: string;
}>;Defined in: api/ElementAPI.ts:1089
Create a new voice interaction with a Queue ID and Phone Number
Creates a new outbound voice call interaction to the specified phone number and assigns it to the specified queue.
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| params | CreateVoiceInteractionParams | Voice interaction parameters |
Returns
Promise<{
message: string;
}>
Promise resolving to a success message
Example
await api.createVoiceInteraction({
phoneNumber: '+1234567890',
queueId: '003'
});createInteraction()
createInteraction(options: CreateInteractionOptions): Promise<{
interactionId: string;
}>;Defined in: api/ElementAPI.ts:1132
Entry point for all outbound channel creation — email, SMS, chat, task, voice.
Generic replacement for channel-specific creation methods. The Agent UI validates the request, opens the appropriate composition window pre-populated with the provided values, and returns the new interaction ID.
createVoiceInteraction() remains available as a thin wrapper and is not deprecated. No new channel-specific methods will be added — use commType instead.
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| options | CreateInteractionOptions | Channel type, recipient, and content parameters |
Returns
Promise<{
interactionId: string;
}>
Object containing the newly created interaction ID
Throws
INVALID_COMM_TYPE if commType is not a supported value
Throws
AGENT_NOT_LOGGED_IN if the agent is not in CX logged-in state
Examples
const { interactionId } = await api.createInteraction({
commType: "email",
to: "[email protected]",
subject: "Follow-up",
body: "Dear customer...",
});const { interactionId } = await api.createInteraction({
commType: "task",
subject: "Follow-up callback",
navigateTo: false,
});triggerWorkflow()
triggerWorkflow(params: TriggerWorkflowParams): Promise<TriggerWorkflowResponse>;Defined in: api/ElementAPI.ts:1199
Trigger an AXP workflow by ID.
Wraps the platform startWorkflowSession API. The host (agent UI) executes
the actual call so credentials are never exposed to the element. When
interactionId is omitted the host automatically attaches the current
interaction context.
Workflow → element communication pattern: Results flow back through the interaction object rather than a direct return channel. The workflow performs an Update Interaction action with the result data, then an Interaction Data Reload action. The element receives the update via onInteractionDataReload and reads the updated data via getInteraction.
Rate limiting and permissions are enforced by the workflow engine, not by IEF.
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| params | TriggerWorkflowParams | Workflow trigger parameters |
Returns
Promise<TriggerWorkflowResponse>
Confirmation with the workflow session ID
Throws
AGENT_NOT_LOGGED_IN if the agent is not in CX logged-in state
Throws
NO_INTERACTION_ID if no interaction ID can be resolved (provide via params or navigate to an interaction)
Throws
MISSING_REQUIRED_PARAMS if workflowId is not provided
Throws
Error if the workflow engine rejects the request (invalid ID, invalid parameters, permissions, or network failure)
Examples
const result = await api.triggerWorkflow({
workflowId: 'wf-refund-process',
});
console.log('Workflow started:', result.workflowSessionId);const result = await api.triggerWorkflow({
workflowId: 'wf-crm-update',
inputData: { orderId: 'ORD-123', amount: 49.99 },
});// 1. Listen for workflow results before triggering
api.onInteractionDataReload(async (interactionId) => {
const updated = await api.getInteraction({ interactionId });
console.log('Workflow result:', updated.metadata);
});
// 2. Trigger the workflow
await api.triggerWorkflow({
workflowId: 'wf-refund-process',
inputData: { orderId: 'ORD-123', amount: 49.99 },
});navigateTo()
navigateTo(to: string, options?: NavigateToOptions): Promise<NavigateToResponse>;Defined in: api/ElementAPI.ts:1280
Navigate the agent desktop to a different view inside the agent app.
The element passes a fully-resolved relative URL as to; the host
validates the URL shape and consults a host-side blacklist before
forwarding to react-router. Because react-router is scoped to the agent
app's basename (/app/agent/), only paths inside the agent app are
reachable — external URLs, protocol-relative URLs, and javascript: /
data: schemes are rejected at the validator.
Signature mirrors react-router's navigate(to, options?) so partners
already familiar with react-router get the shape they expect.
Requirements: This method is part of the Infinity Extensibility
Framework and requires the fg_infinity_extensibility_framework feature
flag to be enabled in the agent desktop. When disabled, infinity elements
cannot load so this API is not available.
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| to | string | Relative path to navigate to (e.g. /interactions/abc/feed) |
| options? | NavigateToOptions | Reserved per-call options (replace, state); see NavigateToOptions. None are honored by the host in v1.0.0. |
Returns
Promise<NavigateToResponse>
Navigation confirmation with the resulting path
Throws
Error if the Infinity Extensibility Framework is not enabled (elements won't load)
Throws
NAVIGATION_BLOCKED if the URL is malformed, external, traverses paths, or is host-blacklisted
Throws
NAVIGATION_FAILED if navigation could not be completed
Examples
await api.navigateTo("/interactions");await api.navigateTo(`/interactions/${interactionId}/profile`);await api.navigateTo(
`/interactions/${interactionId}/email/${messageId}/reply`,
);await api.navigateTo(
`/interactions/${interactionId}/custom-tab/${tabId}`,
);await api.navigateTo("/interactions", { replace: true });Scope & Limits (v1.0.0)
- External URLs: Not allowed.
tomust be a relative path starting with/(and not//); render external content inside your own iframe. - Path traversal & unsafe characters: Rejected by the host validator.
Each path segment must contain at least one alphanumeric character and
only use
[a-zA-Z0-9._-]. - Length cap:
tois capped at 200 characters. - Semantics: Imperative — the agent cannot opt out; navigation runs immediately after the host validates the URL.
- Admin gating: None in v1.0.0. Any Element loaded under the IEF
feature flag may call
navigateTo. Runtime safeguards: rate limit (10 req/sec/source), URL shape validator, host-side blacklist. - Multi-panel: Route-level. The whole agent-desktop view changes; the active interaction is not disrupted (voice/audio and per-interaction state are independent of the routed view).
holdInteraction()
holdInteraction(interactionId: string): Promise<{
message: string;
}>;Defined in: api/ElementAPI.ts:1309
Places an active voice interaction on hold.
The customer hears hold music (if configured by the tenant). The agent desktop reflects the "On Hold" state once the backend confirms.
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| interactionId | string | The voice interaction to place on hold |
Returns
Promise<{
message: string;
}>
Confirmation message on success
Throws
AGENT_NOT_LOGGED_IN if the agent is not in CX logged-in state
Throws
NO_INTERACTION_ID if no interaction ID can be resolved
Throws
HOLD_MUTE_VOICE_ONLY if the interaction is not a voice channel
Throws
INTERACTION_NOT_CONNECTED if the interaction is not in connected state
Throws
INTERACTION_ALREADY_ON_HOLD if the interaction is already on hold
Example
await api.holdInteraction("interaction-id-123");resumeInteraction()
resumeInteraction(interactionId: string): Promise<{
message: string;
}>;Defined in: api/ElementAPI.ts:1332
Resumes a voice interaction from hold, restoring audio between agent and customer.
Counterpart to holdInteraction().
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| interactionId | string | The voice interaction to resume |
Returns
Promise<{
message: string;
}>
Confirmation message on success
Throws
AGENT_NOT_LOGGED_IN if the agent is not in CX logged-in state
Throws
NO_INTERACTION_ID if no interaction ID can be resolved
Throws
HOLD_MUTE_VOICE_ONLY if the interaction is not a voice channel
Throws
INTERACTION_NOT_ON_HOLD if the interaction is not currently on hold
Example
await api.resumeInteraction("interaction-id-123");muteInteraction()
muteInteraction(interactionId: string): Promise<{
message: string;
}>;Defined in: api/ElementAPI.ts:1356
Mutes the agent's microphone during an active voice interaction.
The customer can no longer hear the agent. The agent can still hear the customer.
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| interactionId | string | The voice interaction to mute |
Returns
Promise<{
message: string;
}>
Confirmation message on success
Throws
AGENT_NOT_LOGGED_IN if the agent is not in CX logged-in state
Throws
NO_INTERACTION_ID if no interaction ID can be resolved
Throws
HOLD_MUTE_VOICE_ONLY if the interaction is not a voice channel
Throws
INTERACTION_NOT_CONNECTED if the interaction is not in connected state
Throws
ALREADY_MUTED if the microphone is already muted
Example
await api.muteInteraction("interaction-id-123");unmuteInteraction()
unmuteInteraction(interactionId: string): Promise<{
message: string;
}>;Defined in: api/ElementAPI.ts:1379
Restores the agent's microphone during an active voice interaction.
Counterpart to muteInteraction().
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| interactionId | string | The voice interaction to unmute |
Returns
Promise<{
message: string;
}>
Confirmation message on success
Throws
AGENT_NOT_LOGGED_IN if the agent is not in CX logged-in state
Throws
NO_INTERACTION_ID if no interaction ID can be resolved
Throws
HOLD_MUTE_VOICE_ONLY if the interaction is not a voice channel
Throws
NOT_MUTED if the microphone is not currently muted
Example
await api.unmuteInteraction("interaction-id-123");wrapUpInteraction()
wrapUpInteraction(interactionId: string, options: WrapUpInteractionOptions): Promise<{
message: string;
}>;Defined in: api/ElementAPI.ts:1408
Wraps up a completed interaction with a disposition code.
Applies the disposition code and notes, then removes the interaction from the agent desktop. The interaction must no longer be in "Connected" state — call this after the customer has disconnected or the agent has ended the call.
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| interactionId | string | The interaction to wrap up |
| options | WrapUpInteractionOptions | Disposition code and optional notes |
Returns
Promise<{
message: string;
}>
Confirmation message on success
Throws
AGENT_NOT_LOGGED_IN if the agent is not in CX logged-in state
Throws
NO_INTERACTION_ID if no interaction ID can be resolved
Throws
INTERACTION_STILL_ACTIVE if the interaction is still in connected state
Throws
INVALID_DISPOSITION_CODE if the disposition code is not in the configured list
Example
await api.wrapUpInteraction("interaction-id-123", {
dispositionCode: "Resolved",
notes: "Customer issue resolved",
});closeUnresolved()
closeUnresolved(interactionId: string): Promise<{
message: string;
}>;Defined in: api/ElementAPI.ts:1435
Parks an interaction without marking it as complete.
Removes the interaction from the agent's active list. The interaction returns to the queue or remains available for re-assignment. No disposition code is required.
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| interactionId | string | The interaction to park |
Returns
Promise<{
message: string;
}>
Confirmation message on success
Throws
AGENT_NOT_LOGGED_IN if the agent is not in CX logged-in state
Throws
NO_INTERACTION_ID if no interaction ID can be resolved
Example
await api.closeUnresolved("interaction-id-123");updateInteraction()
updateInteraction(interactionId: string | undefined, fields: UpdateInteractionFields): Promise<{
message: string;
}>;Defined in: api/ElementAPI.ts:1475
Updates mutable fields on an active interaction.
Writes any combination of customer details (name, phone, email) and interaction
metadata (subject, body, notes, interactionType, endResult, routingPhone,
routingPhoneName, customerLanguageCode, fields). At least one field must be
provided. After a successful update the host broadcasts an onInteractionDataReload
event so all listening Elements can refresh their view.
Note: a single updateInteraction() call fires onInteractionDataReload twice in
immediate succession — consumers should debounce that event handler.
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| interactionId | string | undefined | The interaction to update (optional — uses current context if omitted) |
| fields | UpdateInteractionFields | Fields to update; at least one must be set |
Returns
Promise<{
message: string;
}>
Confirmation message on success
Throws
AGENT_NOT_LOGGED_IN if the agent is not in CX logged-in state
Throws
NO_INTERACTION_ID if no interaction ID can be resolved
Throws
NO_FIELDS_TO_UPDATE if all fields are omitted
Throws
ROUTING_PHONE_NAME_REQUIRED if routingPhone is provided without routingPhoneName
Example
await api.updateInteraction("interaction-id-123", {
name: "Jane Smith",
subject: "Billing enquiry",
notes: "Customer called about invoice #42",
routingPhone: "+1-555-0200",
routingPhoneName: "Main Queue",
customerLanguageCode: "fr-FR",
});completeBlindTransfer()
completeBlindTransfer(options: BlindTransferOptions): Promise<boolean>;Defined in: api/ElementAPI.ts:1504
Complete a blind transfer
Transfers the call to another agent or number without consultation.
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| options | BlindTransferOptions | Transfer configuration |
Returns
Promise<boolean>
Promise resolving to true if successful
Example
const interaction = await api.getInteraction();
await api.completeBlindTransfer({
interactionId: interaction.interactionId,
transferTo: '[email protected]',
transferToName: 'John Doe',
transferCallerIdType: 'internal'
});singleStepTransfer()
singleStepTransfer(params: SingleStepTransferParams): Promise<{
message: string;
}>;Defined in: api/ElementAPI.ts:1524
Perform a single-step transfer
Transfers the interaction directly to the specified target.
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| params | SingleStepTransferParams | Transfer parameters |
Returns
Promise<{
message: string;
}>
Promise resolving to a success message
Example
await api.singleStepTransfer({
targetId: 'user123',
targetName: 'Support Team'
});consultCall()
consultCall(options: ConsultCallOptions): Promise<{
message: string;
}>;Defined in: api/ElementAPI.ts:1571
Initiate a consult call
Starts a consultation with another agent, phone number, or queue while keeping the original caller on hold.
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| options | ConsultCallOptions | Consult call configuration |
Returns
Promise<{
message: string;
}>
Promise resolving to a success message
Examples
const interaction = await api.getInteraction();
await api.consultCall({
interactionId: interaction.interactionId,
transferTo: '[email protected]'
});await api.consultCall({
interactionId: interaction.interactionId,
phoneNumber: '+1234567890'
});// Get available queues first
const queues = await api.getTransferQueuesInteraction();
const targetQueue = queues.find(q => q.name === 'Support Queue');
await api.consultCall({
interactionId: interaction.interactionId,
queueId: targetQueue.id
});transferInteraction()
transferInteraction(options: TransferInteractionOptions): Promise<{
message: string;
}>;Defined in: api/ElementAPI.ts:1613
Generic transfer entry point for all channels — blind for all, consult for voice only.
Transfers an interaction to an agent, queue, or external address. Digital interactions (email, SMS, chat, task) support blind transfer only. Voice interactions additionally support consult (attended) transfer.
For consult transfers, this method only initiates the consult — the customer is placed on hold and the agent is connected to the target. Use completeAttendedTransfer() or attendedTransferCancel() to complete or cancel the transfer.
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| options | TransferInteractionOptions | Transfer parameters including target and transfer type |
Returns
Promise<{
message: string;
}>
Promise resolving to a success message
Throws
CONSULT_NOT_SUPPORTED if transferType is "consult" on a non-voice interaction
Throws
INVALID_TRANSFER_TARGET if the target user or queue does not exist or is disabled
Examples
await api.transferInteraction({
interactionId: 'int-123',
targetId: '[email protected]',
targetName: 'Support Agent',
transferType: 'blind',
});await api.transferInteraction({
interactionId: 'int-123',
targetId: '[email protected]',
targetName: 'Supervisor',
transferType: 'consult',
});
// Then complete or cancel:
await api.completeAttendedTransfer({ interactionId: 'int-123' });completeAttendedTransfer()
completeAttendedTransfer(options?: InteractionContextOptions): Promise<{
message: string;
}>;Defined in: api/ElementAPI.ts:1642
Complete an attended transfer
Finalizes the attended transfer after consulting with the target party.
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| options? | InteractionContextOptions | Optional parameters |
Returns
Promise<{
message: string;
}>
Promise resolving to a success message
Examples
// After consulting
await api.completeAttendedTransfer();await api.completeAttendedTransfer({ interactionId: 'int-123' });completeConference()
completeConference(options?: InteractionContextOptions): Promise<{
message: string;
}>;Defined in: api/ElementAPI.ts:1671
Complete the interaction as a conference
Merges all parties into a conference call instead of completing a transfer.
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| options? | InteractionContextOptions | Optional parameters |
Returns
Promise<{
message: string;
}>
Promise resolving to a success message
Examples
// After consulting
await api.completeConference();await api.completeConference({ interactionId: 'int-123' });attendedTransferWarm()
attendedTransferWarm(options?: InteractionContextOptions): Promise<{
message: string;
}>;Defined in: api/ElementAPI.ts:1699
Perform a warm attended transfer
Introduces the caller to the transfer target before completing the transfer.
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| options? | InteractionContextOptions | Optional parameters |
Returns
Promise<{
message: string;
}>
Promise resolving to a success message
Examples
await api.attendedTransferWarm();await api.attendedTransferWarm({ interactionId: 'int-123' });attendedTransferCancel()
attendedTransferCancel(options?: InteractionContextOptions): Promise<{
message: string;
}>;Defined in: api/ElementAPI.ts:1727
Cancel an attended transfer
Cancels the ongoing attended transfer and returns to the original call.
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| options? | InteractionContextOptions | Optional parameters |
Returns
Promise<{
message: string;
}>
Promise resolving to a success message
Examples
await api.attendedTransferCancel();await api.attendedTransferCancel({ interactionId: 'int-123' });acceptInteraction()
acceptInteraction(options?: InteractionContextOptions): Promise<{
message: string;
}>;Defined in: api/ElementAPI.ts:1760
Accept an incoming interaction
Accepts a queued or alerting interaction.
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| options? | InteractionContextOptions | Optional parameters |
Returns
Promise<{
message: string;
}>
Promise resolving to a success message
Examples
api.onInteractionAccepted(async (interactionId) => {
console.log('New interaction:', interactionId);
});
// When ready to accept
await api.acceptInteraction();await api.acceptInteraction({ interactionId: 'int-123' });sendDialpadDigit()
sendDialpadDigit(
digit: DialpadDigit,
audioOutputDeviceId: string | null,
noSendDialTone: boolean,
audioContextOverride?: "none" | "standard" | "webkit",
options?: InteractionContextOptions): Promise<{
message: string;
}>;Defined in: api/ElementAPI.ts:1802
Send a DTMF dialpad digit during a call
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| digit | DialpadDigit | The dialpad digit to send (0-9) |
| audioOutputDeviceId | string | null | Audio output device ID or null for default |
| noSendDialTone | boolean | Whether to suppress the dial tone sound |
| audioContextOverride? | "none" | "standard" | "webkit" | Audio context type override |
| options? | InteractionContextOptions | Optional parameters |
Returns
Promise<{
message: string;
}>
Promise resolving to a success message
Examples
import { DialpadDigit } from '@avaya/infinity-elements-api';
await api.sendDialpadDigit(
DialpadDigit.One,
null,
false
);await api.sendDialpadDigit(
DialpadDigit.One,
null,
false,
undefined,
{ interactionId: 'int-123' }
);insertTextIntoFeedInput()
insertTextIntoFeedInput(text: string, options?: InteractionContextOptions): Promise<{
message: string;
}>;Defined in: api/ElementAPI.ts:1836
Insert text into the chat feed input field
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| text | string | The text to insert |
| options? | InteractionContextOptions | Optional parameters |
Returns
Promise<{
message: string;
}>
Promise resolving to a success message
Examples
await api.insertTextIntoFeedInput('Hello, how can I help you today?');await api.insertTextIntoFeedInput('Hello!', { interactionId: 'int-123' });~~sendRichMediaMessage()~~
sendRichMediaMessage(options: SendRichMediaMessageOptions): Promise<{
message: string;
}>;Defined in: api/ElementAPI.ts:1877
Send a rich media message (image, file, etc.) to the interaction
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| options | SendRichMediaMessageOptions | Message options (must provide either mediaUrl or file) |
Returns
Promise<{
message: string;
}>
Promise resolving to a success message
Deprecated
This method is deprecated and will be removed in a future version.
Examples
await api.sendRichMediaMessage({
name: 'Product Image',
mediaUrl: 'https://example.com/image.jpg',
text: 'Here is the product you requested'
});const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];
await api.sendRichMediaMessage({
name: 'Document',
file: file,
text: 'Attached document',
interactionId: 'int-123'
});sendChatMessage()
sendChatMessage(options: SendChatMessageOptions): Promise<{
message: string;
}>;Defined in: api/ElementAPI.ts:1974
Send a chat message to the interaction
Supports sending text messages, media from URLs, or file uploads. At least one of text, mediaUrl, or file must be provided.
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| options | SendChatMessageOptions | Message options (must provide interactionId and at least one of text, mediaUrl, or file) |
Returns
Promise<{
message: string;
}>
Promise resolving to a success message
Examples
await api.sendChatMessage({
interactionId: 'int-123',
text: 'Hello, how can I help you today?'
});await api.sendChatMessage({
interactionId: 'int-123',
text: 'VIP customer — 3 open cases in CRM',
type: 'private'
});await api.sendChatMessage({
interactionId: 'int-123',
text: 'Suggested response: "I can help you with that refund."',
type: 'agentAssist'
});await api.sendChatMessage({
interactionId: 'int-123',
mediaUrl: 'https://example.com/image.jpg',
text: 'Here is the product you requested'
});const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];
await api.sendChatMessage({
interactionId: 'int-123',
file: file,
text: 'Attached document'
});await api.sendChatMessage({
interactionId: 'int-123',
text: 'Please review this document',
file: documentFile,
fileName: 'Important Document.pdf'
});setAgentStatus()
setAgentStatus(
userId: string,
status: AgentStatus,
reason?: {
id: string;
name: string;
}): Promise<{
message: string;
}>;Defined in: api/ElementAPI.ts:2027
Set the agent's status (Available, Away, Busy, etc.)
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| userId | string | The user ID of the agent |
| status | AgentStatus | The new agent status |
| reason? | { id: string; name: string; } | Optional reason for the status change (required for some statuses) |
| reason.id? | string | - |
| reason.name? | string | - |
Returns
Promise<{
message: string;
}>
Promise resolving to a success message
Examples
const userInfo = await api.getUserInfo();
await api.setAgentStatus(userInfo.userId, { id: 'available', name: 'Available', category: 'available' });const userInfo = await api.getUserInfo();
await api.setAgentStatus(userInfo.userId, { id: 'away', name: 'Away', category: 'away' }, {
id: 'lunch',
name: 'Lunch Break'
});getUserQueues()
getUserQueues(params?: {
filter?: string;
}): Promise<UserQueueInfo[]>;Defined in: api/ElementAPI.ts:2056
Get all queues available to the current user (App Level)
Returns a basic list of queues the agent has access to.
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| params? | { filter?: string; } | Optional filter parameters |
| params.filter? | string | - |
Returns
Promise<UserQueueInfo[]>
Promise resolving to array of user queue information
Example
const queues = await api.getUserQueues();
console.log('Available queues:', queues.map(q => q.name));
// With filter
const salesQueues = await api.getUserQueues({ filter: 'Sales' });getTransferQueues()
getTransferQueues(params: {
interactionId: string;
filter?: string;
}): Promise<InteractionQueueInfo[]>;Defined in: api/ElementAPI.ts:2082
Get transfer queues with real-time statistics (App Level)
Returns detailed queue information including waiting interactions, active agents, and average wait times. Requires explicit interactionId since this is used at app level where interaction context is not available.
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| params | { interactionId: string; filter?: string; } | Required interactionId and optional filter parameters |
| params.interactionId | string | - |
| params.filter? | string | - |
Returns
Promise<InteractionQueueInfo[]>
Promise resolving to array of queue information with statistics
Example
const queues = await api.getTransferQueues({
interactionId: 'int-123',
filter: 'support'
});
queues.forEach(queue => {
console.log(`${queue.name}: ${queue.waitingInteractions} waiting`);
console.log(`Active agents: ${queue.countActiveAgents}`);
});getTransferQueuesInteraction()
getTransferQueuesInteraction(params?: {
filter?: string;
interactionId?: string;
}): Promise<InteractionQueueInfo[]>;Defined in: api/ElementAPI.ts:2120
Get transfer queues with real-time statistics (Interaction Level)
Returns detailed queue information including waiting interactions, active agents, and average wait times. Uses interaction context automatically for interaction-level widgets.
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| params? | { filter?: string; interactionId?: string; } | Optional filter parameters |
| params.filter? | string | Optional substring search against queue names |
| params.interactionId? | string | Optional interaction ID (required for app-level widgets, auto-provided for interaction-level widgets) |
Returns
Promise<InteractionQueueInfo[]>
Promise resolving to array of queue information with statistics
Examples
const queues = await api.getTransferQueuesInteraction({ filter: 'support' });
queues.forEach(queue => {
console.log(`${queue.name}: ${queue.waitingInteractions} waiting`);
console.log(`Active agents: ${queue.countActiveAgents}`);
});const queues = await api.getTransferQueuesInteraction({
filter: 'support',
interactionId: 'int-123'
});getReasonCodes()
getReasonCodes(params?: GetReasonCodesParams): Promise<GetReasonCodesResponse>;Defined in: api/ElementAPI.ts:2151
Get reason codes for agent status changes
Returns available reason codes that can be used when changing agent status.
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| params? | GetReasonCodesParams | Optional parameters |
Returns
Promise<GetReasonCodesResponse>
Promise resolving to reason codes response
Examples
const response = await api.getReasonCodes();
console.log('Reason codes:', response.reasons);const response = await api.getReasonCodes({ type: 'away' });
const awayReasons = response.reasons;getAvayaJwt()
getAvayaJwt(options: {
authorizationEndpoint?: string;
tokenEndpoint?: string;
clientId?: string;
scopes?: string[];
redirectUri?: string;
popupOptions?: PopupOptions;
forceRefresh?: boolean;
}): Promise<string>;Defined in: api/ElementAPI.ts:2201
Get Avaya JWT token with multi-level request deduplication and automatic refresh
- Returns cached token from localStorage if available and not expired
- Automatically refreshes token if expired (using refresh token)
- Prevents duplicate concurrent fetch requests (instance-level)
- Prevents duplicate OAuth popups across iframes/elements (cross-iframe coordination)
- Initiates Keycloak OAuth flow if no token exists
Cross-iframe coordination ensures that if 10 iframes all call getAvayaJwt(), only ONE OAuth popup will appear, and all iframes will receive the same token.
Uses localStorage for coordination to ensure only one OAuth popup appears
GUARANTEE: This function ALWAYS either returns a JWT string or throws an error. There are no code paths that return undefined or hang indefinitely.
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| options | { authorizationEndpoint?: string; tokenEndpoint?: string; clientId?: string; scopes?: string[]; redirectUri?: string; popupOptions?: PopupOptions; forceRefresh?: boolean; } | Configuration options (all optional, uses defaults if not provided) |
| options.authorizationEndpoint? | string | Keycloak authorization endpoint URL |
| options.tokenEndpoint? | string | Keycloak token endpoint URL |
| options.clientId? | string | OAuth client ID |
| options.scopes? | string[] | OAuth scopes to request |
| options.redirectUri? | string | OAuth redirect URI (URL to redirect.html) |
| options.popupOptions? | PopupOptions | Popup window size/position (defaults to 500x600) |
| options.forceRefresh? | boolean | Force token refresh even if not expired (defaults to false) |
Returns
Promise<string>
Promise The JWT token (never returns undefined, always throws on error)
Example
// Use defaults
const jwt = await api.getAvayaJwt();
// With configuration
const jwt = await api.getAvayaJwt({
authorizationEndpoint: 'https://keycloak.example.com/auth/realms/xxx/protocol/openid-connect/auth',
tokenEndpoint: 'https://keycloak.example.com/auth/realms/xxx/protocol/openid-connect/token',
clientId: 'my-client-id',
redirectUri: 'https://myapp.com/redirect.html',
forceRefresh: true
});refreshToken()
refreshToken(options: {
tokenEndpoint?: string;
clientId?: string;
}): Promise<string>;Defined in: api/ElementAPI.ts:2316
Refresh the access token using the stored refresh token
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| options | { tokenEndpoint?: string; clientId?: string; } | Configuration options |
| options.tokenEndpoint? | string | Keycloak token endpoint URL (required) |
| options.clientId? | string | OAuth client ID (required) |
Returns
Promise<string>
Promise The new JWT access token
Throws
Error if refresh token is not available or refresh fails
Example
try {
const newJwt = await api.refreshToken({
tokenEndpoint: 'https://keycloak.example.com/auth/realms/xxx/protocol/openid-connect/token',
clientId: 'my-client-id'
});
console.log('Token refreshed successfully');
} catch (error) {
console.error('Token refresh failed:', error);
// May need to re-authenticate
}clearAvayaJwt()
clearAvayaJwt(): void;Defined in: api/ElementAPI.ts:2375
Clear the cached JWT token and force re-authentication on next getAvayaJwt call
Returns
void
Example
api.clearAvayaJwt();
const newJwt = await api.getAvayaJwt(); // Will trigger OAuth flowsendInterElementMessage()
sendInterElementMessage<T>(message: T): void;Defined in: api/ElementAPI.ts:2682
Send a message to other elements via the host (parent window)
Messages are routed through the host application which acts as a broker, relaying messages to all other element iframes. This approach works in sandboxed iframes where BroadcastChannel is not available.
Type Parameters
| Type Parameter | Description |
| ------ | ------ |
| T | The type of the message |
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| message | T | The message to send (can be any serializable type) |
Returns
void
Example
api.sendInterElementMessage({ type: 'my-event', payload: { key: 'value' } });onInterElementMessage()
onInterElementMessage<T>(callback: (message: T) => void): () => void;Defined in: api/ElementAPI.ts:2721
Subscribe to messages from other elements routed through the host
The host application receives inter-element messages and relays them to all element iframes. This works in sandboxed iframes where BroadcastChannel is not available.
Type Parameters
| Type Parameter | Description |
| ------ | ------ |
| T | The expected type of messages |
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| callback | (message: T) => void | Function called when a message is received |
Returns
Unsubscribe function to stop listening
(): void;Returns
void
Example
const unsubscribe = api.onInterElementMessage<MyMessageType>((message) => {
console.log('Received:', message);
});
// Later, stop listening
unsubscribe();log()
protected log(message: string, data?: unknown): void;Defined in: api/ElementAPI.ts:2923
Debug logging - no-op by default, overridden by ElementAPI subclass
Parameters
| Parameter | Type |
| ------ | ------ |
| message | string |
| data? | unknown |
Returns
void
Overrides
emitError()
protected emitError(error: {
code: string;
message: string;
details?: unknown;
}): void;Defined in: api/ElementAPIEvents.ts:193
Dispatch an error to all registered error listeners.
Parameters
| Parameter | Type |
| ------ | ------ |
| error | { code: string; message: string; details?: unknown; } |
| error.code | string |
| error.message | string |
| error.details? | unknown |
Returns
void
Inherited from
handleMessage()
protected handleMessage(data: Record<string, any>): boolean;Defined in: api/ElementAPIEvents.ts:212
Handle an incoming window message and dispatch to appropriate listeners.
Parameters
| Parameter | Type |
| ------ | ------ |
| data | Record<string, any> |
Returns
boolean
true if the message was handled as an event, false otherwise.
Inherited from
ElementAPIEvents.handleMessage
onInteractionStatusChanged()
onInteractionStatusChanged(callback: InteractionStatusChangedCallback): () => void;Defined in: api/ElementAPIEvents.ts:417
Subscribe to interaction status changes
Fires when the status of an interaction changes (e.g., alerting, connected, held)
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| callback | InteractionStatusChangedCallback | Function to call when interaction status changes |
Returns
Unsubscribe function
(): void;Returns
void
Example
const unsubscribe = api.onInteractionStatusChanged(({ interactionId, status }) => {
console.log(`Interaction ${interactionId} status changed to ${status}`);
});
// Later, to unsubscribe:
unsubscribe();Inherited from
ElementAPIEvents.onInteractionStatusChanged
onInteractionAccepted()
onInteractionAccepted(callback: InteractionAcceptedCallback): () => void;Defined in: api/ElementAPIEvents.ts:440
Subscribe to interaction accepted events
Fires when an agent accepts an incoming interaction
Parameters
| Parameter | Type | Description |
| ------ | ------ | ------ |
| callback | InteractionAcceptedCallback | Function to call when an interaction is accepted |
Returns
Unsubscribe function
(): void;Returns
void
Example
api.onInteractionAccepted((interactionId) => {
console.log('Accepted interaction:', interactionId);
// Load customer data, show interaction UI, etc.
});