@avaya/infinity-elements-api v1.3.1

@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
• Features
• Quick Start
  • Basic Setup
  • React Example
• Core Concepts
• API Families
• Development
• License
• Related Packages
• API Documentation

Installation

npm install @avaya/infinity-elements-api

Features

• 🔌 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:

Workflow → Element communication pattern:

Workflows communicate results back to elements through the shared interaction object rather than a direct return channel:

1. Element calls triggerWorkflow({ workflowId, inputData })
2. Workflow executes (may be short or long-running)
3. Workflow writes results via an Update Interaction action, then signals completion with an Interaction Data Reload action
4. Element receives onInteractionDataReload and reads updated data via getInteraction()

// 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

API Families

The ElementAPI methods and event subscriptions are organized into API families.
The generated API reference below is grouped by these same families:

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 lint

License

This package is proprietary and licensed under the Avaya SDK License Agreement.
Use is subject to that agreement — see the LICENSE file included in this package and the
Avaya SDK License Agreement.
It is not open-source software.

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.origin returns "null" (the literal string "null")
• document.referrer may 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

• ElementAPIEvents

Constructors

Constructor

new ElementAPI(options: ElementAPIOptions): ElementAPI;

Defined in: api/ElementAPI.ts:728

Creates a new ElementAPI instance

Parameters

Returns

ElementAPI

Example

const api = new ElementAPI({
  elementId: 'my-custom-element',
  timeout: 10000,
  debug: true
});

Overrides

ElementAPIEvents.constructor

Methods

Interaction API

getInteraction()

getInteraction(options?: InteractionContextOptions): Promise<InteractionInfo>;

Defined in: api/ElementAPI.ts:822

Get information about the current active interaction

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);

getUserInteractions()

getUserInteractions(params?: GetUserInteractionsParams): Promise<GetUserInteractionsResponse>;

Defined in: api/ElementAPI.ts:929

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

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);

viewerRemoveInteraction()

viewerRemoveInteraction(options?: InteractionContextOptions): Promise<{
  message: string;
}>;

Defined in: api/ElementAPI.ts:1016

Remove the current interaction from the viewer

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:1046

End the current interaction

Terminates the active interaction and disconnects the call.

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:1073

Start a voice call for the current interaction

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:1100

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

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:1144

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

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:1212

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

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:1294

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

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 (API v1)

• External URLs: Not allowed. to must 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: to is capped at 200 characters.
• Semantics: Imperative — the agent cannot opt out; navigation runs
  immediately after the host validates the URL.
• Admin gating: None in API v1. 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:1324

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

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:1348

Resumes a voice interaction from hold, restoring audio between agent and customer.

Counterpart to holdInteraction().

Parameters

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:1373

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

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:1397

Restores the agent's microphone during an active voice interaction.

Counterpart to muteInteraction().

Parameters

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:1427

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

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:1455

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

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:1496

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

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:1526

Complete a blind transfer

Transfers the call to another agent or number without consultation.

Parameters

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:1547

Perform a single-step transfer

Transfers the interaction directly to the specified target.

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:1595

Initiate a consult call

Starts a consultation with another agent, phone number, or queue while keeping
the original caller on hold.

Parameters

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:1638

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

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:1668

Complete an attended transfer

Finalizes the attended transfer after consulting with the target party.

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:1698

Complete the interaction as a conference

Merges all parties into a conference call instead of completing a transfer.

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:1727

Perform a warm attended transfer

Introduces the caller to the transfer target before completing the transfer.

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:1756

Cancel an attended transfer

Cancels the ongoing attended transfer and returns to the original call.

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:1790

Accept an incoming interaction

Accepts a queued or alerting interaction.

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' });

onInteractionStatusChanged()

onInteractionStatusChanged(callback: InteractionStatusChangedCallback): () => void;

Defined in: api/ElementAPIEvents.ts:418

Subscribe to interaction status changes

Fires when the status of an interaction changes (e.g., alerting, connected, held)

Parameters

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:442

Subscribe to interaction accepted events

Fires when an agent accepts an incoming interaction

Parameters

Returns

Unsubscribe function

(): void;

Returns

void

Example

api.onInteractionAccepted((interactionId) => {
  console.log('Accepted interaction:', interactionId);
  // Load customer data, show interaction UI, etc.
});

Inherited from

ElementAPIEvents.onInteractionAccepted

onInteractionEnded()

onInteractionEnded(callback: InteractionEndedCallback): () => void;

Defined in: api/ElementAPIEvents.ts:464

Subscribe to interaction ended events

Fires when an interaction is ended or disconnected

Parameters

Returns

Unsubscribe function

(): void;

Returns

void

Example

api.onInteractionEnded((interactionId) => {
  console.log('Interaction ended:', interactionId);
  // Clean up UI, save data, etc.
});

Inherited from

ElementAPIEvents.onInteractionEnded

onInteractionUpdated()

onInteractionUpdated(callback: InteractionUpdatedCallback): () => void;

Defined in: api/ElementAPIEvents.ts:486

Subscribe to interaction updated events

Fires when an interaction is updated with new information

Parameters

Returns

Unsubscribe function

(): void;

Returns

void

Example

api.onInteractionUpdated(({ interactionId, payload }) => {
  console.log('Interaction updated:', interactionId);
  console.log('New data:', payload);
});

Inherited from

ElementAPIEvents.onInteractionUpdated

onInteractionDataReload()

onInteractionDataReload(callback: InteractionDataReloadCallback): () => void;

Defined in: api/ElementAPIEvents.ts:511

Subscribe to interaction data reload events.

Fires after a successful updateInteraction() call, signalling the element
to refresh its local copy of the interaction data from its own backend or
re-fetch fields it cares about.

Parameters

Returns

Unsubscribe function

(): void;

Returns

void

Example

const unsubscribe = api.onInteractionDataReload((interactionId) => {
  console.log('Reload data for:', interactionId);
  // Re-fetch interaction details from your backend
});

Inherited from

ElementAPIEvents.onInteractionDataReload

onConsultStatusChanged()

onConsultStatusChanged(callback: ConsultStatusChangedCallback): () => void;

Defined in: api/ElementAPIEvents.ts:532

Subscribe to consult status changes

Fires when the status of a consultation changes

Parameters

Returns

Unsubscribe function

(): void;

Returns

void

Example

api.onConsultStatusChanged(({ interactionId, consultStatus, consultParty }) => {
  console.log(`Consult ${consultStatus} with ${consultParty}`);
});

Inherited from

ElementAPIEvents.onConsultStatusChanged

onCompleteAsConference()

onCompleteAsConference(callback: CompleteAsConferenceCallback): () => void;

Defined in: api/ElementAPIEvents.ts:553

Subscribe to complete as conference events

Fires when an interaction is completed as a conference

Parameters

Returns

Unsubscribe function

(): void;

Returns

void

Example

api.onCompleteAsConference(({ interactionId }) => {
  console.log(`Interaction ${interactionId} completed as conference`);
});

Inherited from

ElementAPIEvents.onCompleteAsConference

onInteractionFocusChanged()

onInteractionFocusChanged(callback: InteractionFocusChangedCallback): () => void;

Defined in: api/ElementAPIEvents.ts:678

Subscribe to interaction focus changed events.

Fires when the agent switches to a different interaction tab,
delivering the focused interactionId. Fires with null when the
agent navigates away from all interactions (e.g. Home, Analytics).

Also fires on email and SMS interaction accept even when createInteraction()
was called with navigateTo: false — digital channel accept always triggers
a focus change regardless of the navigateTo flag.

App-level elements should store the received interactionId and pass
it explicitly to getInteraction({interactionId}) to avoid relying
on URL context.

Parameters

Returns

Unsubscribe function

(): void;

Returns

void

Example

api.onInteractionFocusChanged((interactionId) => {
  if (!interactionId) return;
  api.getInteraction({ interactionId }).then(data => render(data));
});

Inherited from

ElementAPIEvents.onInteractionFocusChanged

Media API

sendDialpadDigit()

sendDialpadDigit(
   digit: DialpadDigit, 
   audioOutputDeviceId: string | null, 
   noSendDialTone: boolean, 
   audioContextOverride?: "none" | "standard" | "webkit", 
   options?: InteractionContextOptions): Promise<{
  message: string;
}>;

Defined in: api/ElementAPI.ts:1833

Send a DTMF dialpad digit during a call

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:1868

Insert text into the chat feed input field

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:1910

Send a rich media message (image, file, etc.) to the interaction

Parameters

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:2008

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

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'
});

onReceivedFeedMessage()

onReceivedFeedMessage(callback: FeedMessageCallback): () => void;

Defined in: api/ElementAPIEvents.ts:575

Subscribe to feed messages

Fires when a new message is received in the interaction feed

Parameters

Returns

Unsubscribe function

(): void;

Returns

void

Example

api.onReceivedFeedMessage((message, interactionId) => {
  console.log('New message:', message.text, 'for interaction:', interactionId);
});

Inherited from

ElementAPIEvents.onReceivedFeedMessage

Agent API

getUserInfo()

getUserInfo(): Promise<UserInfo>;

Defined in: api/ElementAPI.ts:845

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:856

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.

setAgentStatus()

setAgentStatus(
   userId: string, 
   status: AgentStatus, 
   reason?: {
  id: string;
  name: string;
}): Promise<{
  message: string;
}>;

Defined in: api/ElementAPI.ts:2062

Set the agent's status (Available, Away, Busy, etc.)

Parameters

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:2092

Get all queues available to the current user (App Level)

Returns a basic list of queues the agent has access to.

Parameters

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' });

getReasonCodes()

getReasonCodes(params?: GetReasonCodesParams): Promise<GetReasonCodesResponse>;

Defined in: api/ElementAPI.ts:2190

Get reason codes for agent status changes

Returns available reason codes that can be used when changing agent status.

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;

onChangedAgentState()

onChangedAgentState(callback: AgentStateChangedCallback): () => void;

Defined in: api/ElementAPIEvents.ts:623

Parameters

Returns

(): void;

Returns

void

Deprecated

Use onAgentStateChange instead for the full structured payload

Inherited from

ElementAPIEvents.onChangedAgentState

onAgentStateChange()

onAgentStateChange(callback: AgentStateChangeCallback): () => void;

Defined in: api/ElementAPIEvents.ts:646

Subscribe to agent state changed events

Fires when the agent's state changes (e.g. availability, CX login/logout, queue login/logout).
Supersedes onChangedAgentState with a fully structured payload including
isAID, queues, agentState, timestamp, agentId, and reasonCode.

Parameters

Returns

Unsubscribe function

(): void;

Returns

void

Example

const unsubscribe = api.onAgentStateChange(({ agentState, isAID, queues }) => {
  console.log(`State: ${agentState}, CX logged in: ${isAID}`);
});

Inherited from

ElementAPIEvents.onAgentStateChange

Admin API

getConfig()

getConfig(): Promise<IEFConfig>;

Defined in: api/ElementAPI.ts:895

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();
}

getUsers()

getUsers(params?: {
  interactionId?: string;
  filter?: string;
}): Promise<GetUsersResponse[]>;

Defined in: api/ElementAPI.ts:991

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 interactionId parameter
• Interaction Level (interaction widgets): Omit interactionId, uses interaction context automatically

Parameters

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}`);
});

getTransferQueues()

getTransferQueues(params: {
  interactionId: string;
  filter?: string;
}): Promise<InteractionQueueInfo[]>;

Defined in: api/ElementAPI.ts:2119

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

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:2158

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

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'
});

Inter-Element Communication

sendInterElementMessage()

sendInterElementMessage<T>(message: T): void;

Defined in: api/ElementAPI.ts:2725

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

Parameters

Returns

void

Example

api.sendInterElementMessage({ type: 'my-event', payload: { key: 'value' } });

onInterElementMessage()

onInterElementMessage<T>(callback: (message: T) => void): () => void;

Defined in: api/ElementAPI.ts:2765

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

Parameters

Returns

Unsubscribe function to stop listening

(): void;

Returns

void

Example

const unsubscribe = api.onInterElementMessage<MyMessageType>((message) => {
  console.log('Received:', message);
});

// Later, stop listening
unsubscribe();

Authentication

getAvayaJwt()

getAvayaJwt(options: {
  authorizationEndpoint?: string;
  tokenEndpoint?: string;
  clientId?: string;
  scopes?: string[];
  redirectUri?: string;
  popupOptions?: PopupOptions;
  forceRefresh?: boolean;
}): Promise<string>;

Defined in: api/ElementAPI.ts:2241

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

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:2357

Refresh the access token using the stored refresh token

Parameters

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:2417

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 flow

Events

onError()

onError(callback: ErrorCallback): () => void;

Defined in: api/ElementAPIEvents.ts:597

Subscribe to error events

Fires when an error occurs in the API

Parameters

Returns

Unsubscribe function

(): void;

Returns

void

Example

api.onError((error) => {
  console.error('API Error:', error.code, error.message);
  // Display error notification to user
});

Inherited from

ElementAPIEvents.onError

Lifecycle

destroy()

destroy(): void;

Defined in: api/ElementAPI.ts:770

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
  };
}, []);

ElementAPIEvents

Defined in: api/ElementAPIEvents.ts:127

ElementAPIEvents - Base class providing event subscription and dispatch for ElementAPI

Owns all event listener Sets, provides on* subscription methods,
and dispatches incoming window messages to the appropriate listeners.
ElementAPI extends this class to inherit all event functionality.

Extended by

• ElementAPI

Constructors

Constructor

new ElementAPIEvents(): ElementAPIEvents;

Returns

ElementAPIEvents

Methods

Interaction API

onInteractionStatusChanged()

onInteractionStatusChanged(callback: InteractionStatusChangedCallback): () => void;

Defined in: api/ElementAPIEvents.ts:418

Subscribe to interaction status changes

Fires when the status of an interaction changes (e.g., alerting, connected, held)

Parameters

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();

onInteractionAccepted()

onInteractionAccepted(callback: InteractionAcceptedCallback): () => void;

Defined in: api/ElementAPIEvents.ts:442

Subscribe to interaction accepted events

Fires when an agent accepts an incoming interaction

Parameters

Returns

Unsubscribe function

(): void;

Returns

void

Example

api.onInteractionAccepted((interactionId) => {
  console.log('Accepted interaction:', interactionId);
  // Load customer data, show interaction UI, etc.
});

onInteractionEnded()

onInteractionEnded(callback: InteractionEndedCallback): () => void;

Defined in: api/ElementAPIEvents.ts:464

Subscribe to interaction ended events

Fires when an interaction is ended or disconnected

Parameters

Returns

Unsubscribe function

(): void;

Returns

void

Example

api.onInteractionEnded((interactionId) => {
  console.log('Interaction ended:', interactionId);
  // Clean up UI, save data, etc.
});

onInteractionUpdated()

onInteractionUpdated(callback: InteractionUpdatedCallback): () => void;

Defined in: api/ElementAPIEvents.ts:486

Subscribe to interaction updated events

Fires when an interaction is updated with new information

Parameters

Returns

Unsubscribe function

(): void;

Returns

void

Example

api.onInteractionUpdated(({ interactionId, payload }) => {
  console.log('Interaction updated:', interactionId);
  console.log('New data:', payload);
});

onInteractionDataReload()

onInteractionDataReload(callback: InteractionDataReloadCallback): () => void;

Defined in: api/ElementAPIEvents.ts:511

Subscribe to interaction data reload events.

Fires after a successful updateInteraction() call, signalling the element
to refresh its local copy of the interaction data from its own backend or
re-fetch fields it cares about.

Parameters

Returns

Unsubscribe function

(): void;

Returns

void

Example

const unsubscribe = api.onInteractionDataReload((interactionId) => {
  console.log('Reload data for:', interactionId);
  // Re-fetch interaction details from your backend
});

onConsultStatusChanged()

onConsultStatusChanged(callback: ConsultStatusChangedCallback): () => void;

Defined in: api/ElementAPIEvents.ts:532

Subscribe to consult status changes

Fires when the status of a consultation changes

Parameters

Returns

Unsubscribe function

(): void;

Returns

void

Example

api.onConsultStatusChanged(({ interactionId, consultStatus, consultParty }) => {
  console.log(`Consult ${consultStatus} with ${consultParty}`);
});

onCompleteAsConference()

onCompleteAsConference(callback: CompleteAsConferenceCallback): () => void;

Defined in: api/ElementAPIEvents.ts:553

Subscribe to complete as conference events

Fires when an interaction is completed as a conference

Parameters

Returns

Unsubscribe function

(): void;

Returns

void

Example

api.onCompleteAsConference(({ interactionId }) => {
  console.log(`Interaction ${interactionId} completed as conference`);
});

onInteractionFocusChanged()

onInteractionFocusChanged(callback: InteractionFocusChangedCallback): () => void;

Defined in: api/ElementAPIEvents.ts:678

Subscribe to interaction focus changed events.

Fires when the agent switches to a different interaction tab,
delivering the focused interactionId. Fires with null when the
agent navigates away from all interactions (e.g. Home, Analytics).

Also fires on email and SMS interaction accept even when createInteraction()
was called with navigateTo: false — digital channel accept always triggers
a focus change regardless of the navigateTo flag.

App-level elements should store the received interactionId and pass
it explicitly to getInteraction({interactionId}) to avoid relying
on URL context.

Parameters

Returns

Unsubscribe function

(): void;

Returns

void

Example

api.onInteractionFocusChanged((interactionId) => {
  if (!interactionId) return;
  api.getInteraction({ interactionId }).then(data => render(data));
});

Media API

onReceivedFeedMessage()

onReceivedFeedMessage(callback: FeedMessageCallback): () => void;

Defined in: api/ElementAPIEvents.ts:575

Subscribe to feed messages

Fires when a new message is received in the interaction feed

Parameters

Returns

Unsubscribe function

(): void;

Returns

void

Example

api.onReceivedFeedMessage((message, interactionId) => {
  console.log('New message:', message.text, 'for interaction:', interactionId);
});

Agent API

onChangedAgentState()

onChangedAgentState(callback: AgentStateChangedCallback): () => void;

Defined in: api/ElementAPIEvents.ts:623

Parameters

Returns

(): void;

Returns

void

Deprecated

Use onAgentStateChange instead for the full structured payload

onAgentStateChange()

onAgentStateChange(callback: AgentStateChangeCallback): () => void;

Defined in: api/ElementAPIEvents.ts:646

Subscribe to agent state changed events

Fires when the agent's state changes (e.g. availability, CX login/logout, queue login/logout).
Supersedes onChangedAgentState with a fully structured payload including
isAID, queues, agentState, timestamp, agentId, and reasonCode.

Parameters

Returns

Unsubscribe function

(): void;

Returns

void

Example

const unsubscribe = api.onAgentStateChange(({ agentState, isAID, queues }) => {
  console.log(`State: ${agentState}, CX logged in: ${isAID}`);
});

Events

onError()

onError(callback: ErrorCallback): () => void;

Defined in: api/ElementAPIEvents.ts:597

Subscribe to error events

Fires when an error occurs in the API

Parameters

Returns

Unsubscribe function

(): void;

Returns

void

Example

api.onError((error) => {
  console.error('API Error:', error.code, error.message);
  // Display error notification to user
});

IframeSecurity

Defined in: security/IframeSecurity.ts:100

Static utility class for iframe security validation and monitoring.

Constructors

Constructor

new IframeSecurity(): IframeSecurity;

Returns

IframeSecurity

Methods

validateIframe()

static validateIframe(iframe: HTMLIFrameElement, options: IframeValidationOptions): IframeValidationResult;

Defined in: security/IframeSecurity.ts:104

Validates that an iframe element has the expected security configuration.

Parameters

Returns

IframeValidationResult

monitorIframe()

static monitorIframe(iframe: HTMLIFrameElement, options: IframeMonitorOptions): () => void;

Defined in: security/IframeSecurity.ts:205

Monitors an iframe for changes to security-critical attributes.

Parameters

Returns

(): void;

Returns

void

validateParentOrigins()

static validateParentOrigins(allowedOrigins: string[]): IframeValidationResult;

Defined in: security/IframeSecurity.ts:248

Validates the current window's parent environment by checking ancestor origins.

Parameters

Returns

IframeValidationResult

InteractionInfo

Defined in: api/ElementAPI.ts:38

Properties

InteractionUpdatePayload

Defined in: api/ElementAPI.ts:54

Properties

BlindTransferOptions

Defined in: api/ElementAPI.ts:107

Properties

SingleStepTransferParams

Defined in: api/ElementAPI.ts:114

Properties

CreateVoiceInteractionParams

Defined in: api/ElementAPI.ts:121

Properties

CreateInteractionOptions

Defined in: api/ElementAPI.ts:130

Options for creating a generic outbound interaction across any channel type.
Replaces channel-specific creation methods with a single unified API.

Properties

InteractionContextOptions

Defined in: api/ElementAPI.ts:206

Common options for interaction-context methods
Used to optionally specify an interaction ID for app-level widgets

Properties

SendRichMediaMessageOptions

Defined in: api/ElementAPI.ts:211

Properties

SendChatMessageOptions

Defined in: api/ElementAPI.ts:240

Properties

ConsultCallOptions

Defined in: api/ElementAPI.ts:264

Properties

TransferInteractionOptions

Defined in: api/ElementAPI.ts:279

Options for transferring an interaction to an agent, queue, or external address.
Works across all channel types. Digital channels support blind transfer only.
Voice additionally supports consult (attended) transfer.

Properties

AgentStatus

Defined in: api/ElementAPI.ts:295

Properties

WrapUpInteractionOptions

Defined in: api/ElementAPI.ts:304

Options for wrapping up a completed interaction.

Properties

NavigateToOptions

Defined in: api/ElementAPI.ts:326

Per-call options for navigateTo(). Mirrors react-router's NavigateOptions.

No fields ship in API v1 — replace and state below are reserved for
a future API version and are currently silently ignored by the host. They are
declared on the type so partners can opt into the planned shape early; their
values are not yet honored at runtime.

Properties

NavigateToResponse

Defined in: api/ElementAPI.ts:345

Response from a navigation request.

Properties

UpdateInteractionFieldsBase

Defined in: api/ElementAPI.ts:352

Properties

TriggerWorkflowParams

Defined in: api/ElementAPI.ts:414

Parameters for triggering an AXP workflow from an element.

Properties

TriggerWorkflowResponse

Defined in: api/ElementAPI.ts:434

Response returned after successfully triggering a workflow.

Properties

ReasonCode

Defined in: api/ElementAPI.ts:441

Properties

GetReasonCodesParams

Defined in: api/ElementAPI.ts:460

Properties

GetReasonCodesResponse

Defined in: api/ElementAPI.ts:464

Properties

GetUserInteractionsParams

Defined in: api/ElementAPI.ts:468

Properties

QueueLoggedIn

Defined in: api/ElementAPI.ts:473

Properties

QueueAccess

Defined in: api/ElementAPI.ts:483

Properties

UserInteractionsUser

Defined in: api/ElementAPI.ts:491

Properties

GetUserInteractionsResponse

Defined in: api/ElementAPI.ts:501

Properties

ElementAPIOptions

Defined in: api/ElementAPI.ts:515

Configuration options for ElementAPI initialization

Properties

CustomerHostedSecurityOptions

Defined in: api/ElementAPI.ts:549

Security configuration for customer-hosted bridge/adaptor integrations.

Properties

ElementAPISecurityOptions

Defined in: api/ElementAPI.ts:580

Backward-compatible security configuration from the earlier shell/child prototype.

Prefer customerHosted for adaptor/bridge integrations. This interface is kept
so the earlier prototype's option names can be accepted without rewriting callers.

Properties

InteractionQueueInfo

Defined in: api/ElementAPI.ts:613

Properties

UserQueueInfo

Defined in: api/ElementAPI.ts:628

Properties

KeycloakConfig

Defined in: auth/KeycloakAuth.ts:29

Keycloak OAuth 2.0 PKCE Authentication Module

Sandboxed Iframe Environment

IMPORTANT: Elements run in sandboxed iframes using srcdoc, which means:

• window.location.origin returns "null" (the literal string "null")
• document.referrer may be empty
• Direct fetch to external URLs may fail due to CORS
• BroadcastChannel doesn't work (requires valid origin)

Because of these limitations:

• Token refresh requests are delegated to the host via postMessage
• The host (with a valid origin) makes the actual HTTP request
• OAuth popup flow works because the popup opens redirect.html on the host's origin

OAuth Flow

Uses postMessage-based config exchange with redirect.html:

1. Component opens popup directly
2. redirect.html requests config via postMessage
3. Component responds with config + code verifier
4. redirect.html performs token exchange
5. redirect.html sends token back to component

No localStorage bridging needed - config stays in memory.

Properties

PopupOptions

Defined in: auth/KeycloakAuth.ts:38

Properties

TokenResponse

Defined in: auth/KeycloakAuth.ts:199

Properties

StoredTokenData

Defined in: auth/KeycloakAuth.ts:208

Properties

IframeValidationResult

Defined in: security/IframeSecurity.ts:9

Result of an iframe security validation check.

Properties

IframeValidationOptions

Defined in: security/IframeSecurity.ts:21

Options for validating an iframe element's security configuration.

Properties

TamperDetails

Defined in: security/IframeSecurity.ts:52

Callback details when iframe tampering is detected.

Properties

IframeMonitorOptions

Defined in: security/IframeSecurity.ts:68

Options for monitoring an iframe for security-critical attribute changes.

Uses a snapshot-and-compare model: all watched attribute values are captured
when monitorIframe() is called, and any subsequent change fires the
callback regardless of whether the new value is still "valid".

Properties

CrmConfig

Defined in: types/iefConfig.ts:19

Admin-configured CRM settings for the current user.

The known fields below come from the user object's crmConfigurations
record. Additional admin-defined keys may be present — read them via the
index signature, but do not assume any unlisted key is guaranteed to exist.

Indexable

[key: string]: unknown

Additional admin-defined keys.

Properties

IEFConfig

Defined in: types/iefConfig.ts:43

Snapshot of the element's context within the current session.
Returned by ElementAPI.getConfig().

Expandable shape: new properties may be added in future releases —
element implementations should not rely on an exhaustive shape, and the
object should be read by property name rather than by destructuring against
a fixed key set.

Properties

Interaction

Defined in: types/interaction.ts:7

Properties