@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.

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({
  elementId: "my-element",
  timeout: 5000,
  debug: true,
});

// Get user information
const userInfo = await api.getUserInfo();
console.log("Agent:", userInfo.displayName);
console.log("Status:", userInfo.agentStatus);

// 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 [api] = useState(
    () =>
      new ElementAPI({
        elementId: "my-element",
        debug: true,
      })
  );
  const [userInfo, setUserInfo] = useState(null);

  useEffect(() => {
    // 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 BroadcastChannel

Event Subscriptions

Subscribe to real-time events from core-agent-ui:

// Interaction accepted
api.onInteractionAccepted((interactionId) => {
  /* ... */
});

// Interaction ended
api.onInteractionEnded((interactionId) => {
  /* ... */
});

// Interaction status changed
api.onInteractionStatusChanged(({ interactionId, status }) => {
  /* ... */
});

// Interaction updated (full interaction object)
api.onInteractionUpdated(({ interactionId, payload }) => {
  /* ... */
});

// Consult status changed
api.onConsultStatusChanged(({ interactionId, consultStatus }) => {
  /* ... */
});

// Feed message received
api.onReceivedFeedMessage((message) => {
  /* ... */
});

// Error occurred
api.onError((error) => {
  /* ... */
});

Agent Status Management

// Get current user info
const userInfo = await api.getUserInfo();

// Set agent status to Available
await api.setAgentStatus(userInfo.id, "Available");

// Set agent status to Away with reason
await api.setAgentStatus(userInfo.id, "Away", {
  id: "lunch",
  name: "Lunch Break",
});

// Get available reason codes
const reasonCodes = await api.getReasonCodes({ type: "away" });

Call Management

// Get active interaction
const interaction = await api.getInteraction();

// Accept interaction
await api.acceptInteraction();

// End interaction
await api.endInteraction();

// Single step transfer
await api.singleStepTransfer({
  interactionId: interaction.interactionId,
  transferTo: "[email protected]",
});

// Consult call
await api.consultCall({
  transferTo: "[email protected]",
  transferToName: "Supervisor",
});

// Complete attended transfer
await api.completeAttendedTransfer();

API Documentation

For complete API documentation with detailed method signatures, parameters, and return types, see:

📚 Full API Reference

Available Methods

User & Agent

• getUserInfo() - Get current user/agent information
• setAgentStatus() - Set agent status (Available, Away, Busy, etc.)
• getReasonCodes() - Get available reason codes for status changes

Interaction Management

• getInteraction() - Get current interaction details
• acceptInteraction() - Accept an incoming interaction
• endInteraction() - End the current interaction
• viewerRemoveInteraction() - Remove interaction from viewer

Call Control

• startVoiceCall() - Start a voice call
• singleStepTransfer() - Transfer to another agent/number
• completeBlindTransfer() - Complete a blind transfer
• consultCall() - Initiate a consult call
• completeAttendedTransfer() - Complete an attended transfer
• attendedTransferWarm() - Warm transfer
• attendedTransferCancel() - Cancel transfer
• sendDialpadDigit() - Send DTMF tones

Queue Management

• getInteractionQueues() - Get queues for the current interaction
• getUserQueues() - Get all queues for the user

Messaging

• insertTextIntoFeedInput() - Insert text into the chat feed input
• sendRichMediaMessage() - Send rich media messages (images, files) (deprecated)

Inter-Element Communication

• sendInterElementMessage() - Send messages to other elements
• onInterElementMessage() - Listen for messages from other elements

TypeScript Support

This package is written in TypeScript and includes comprehensive type definitions:

import type {
  ElementAPI,
  ElementAPIOptions,
  InteractionInfo,
  UserInfo,
  AgentStatus,
  KeycloakConfig,
  InteractionStatusChangedCallback,
  InteractionEndedCallback,
  InteractionAcceptedCallback,
  // ... and many more
} from "@avaya/infinity-elements-api";

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

Documentation Generation

This package uses TypeDoc to automatically generate documentation from source code:

# Generate docs (output to docs/api/)
npm run docs

# Watch mode for live documentation updates
npm run docs:watch

The documentation is automatically generated from JSDoc comments in the source code, ensuring it stays in sync with the implementation.

License

MIT

Related Packages

• @avaya/infinity-elements-sdk - CLI tool for scaffolding InfinityElement projects

Support

For more detailed usage examples and guides, see the API Reference.