@8x8/pui-partner-comm

npm package designed to be used by 8x8 partners for a simpler integration with 8x8 products.

Install

The package is available on npmjs and also as an umd library.

using npm

npm install @8x8/pui-partner-comm

using yarn

yarn add @8x8/pui-partner-comm

UMD bundle

If you don't use a package manager, you can add it using the script tag (from v0.4.0). You can choose between unpkg.com and jsdelivr.net

unpkg.com

<script src="https://www.unpkg.com/@8x8/pui-partner-comm@latest/dist/umd/pui-partner-comm.min.js"></script>

The above example will include the latest version of the package. If you want a specific version replace latest with the desired version, example:

<script src="https://www.unpkg.com/@8x8/[email protected]/dist/umd/pui-partner-comm.min.js"></script>

jsdelivr.net

<script src="https://cdn.jsdelivr.net/npm/@8x8/pui-partner-comm@latest/dist/umd/pui-partner-comm.min.js"></script>

The above example will include the latest version of the package. If you want a specific version replace latest with the desired version, example:

<script src="https://cdn.jsdelivr.net/npm/@8x8/[email protected]/dist/umd/pui-partner-comm.min.js"></script>

Integration

To set up the integration you will need to use the initialise function.

using ESM library

import * as partnerSDK from '@8x8/pui-partner-comm';
import { type MessageData } from '@8x8/pui-partner-comm';

const onMessage = (data: MessageData) => {
  // write what do you want to do with the data received
}

partnerSDK.system.initialise({
  appName: 'partner-application-name',
  appVersion: '1.0.0',
  vendor: '8x8',
  onMessage,
});

using UDM library

<script src="https://www.unpkg.com/@8x8/pui-partner-comm@latest/dist/umd/pui-partner-comm.min.js"></script>
<script>
  function onMessage(data) {
    // write what do you want to do with the data received
    console.log("Received onMessage", data);
  }

  window.partnerSDK.system.initialise({
    appName: 'partner-application-name',
    appVersion: '1.0.0',
    vendor: '8x8',
    onMessage,
  });
</script>

available namespaces

auth

The auth namespace exposes

login

If you want to login the user, you can call this function. The functionality will open a popup for the user to login. This function receives one optional parameter as an object that has the following properties:

• username - (string) the username

example:

import * as partnerSDK from '@8x8/pui-partner-comm';

// if you have the username
partnerSDK.auth.login({
  username: 'username'
});

// or if you do not have the username
partnerSDK.auth.login();

activity

The activity namespace exposes

idle

If you want to notify the 8x8 Application that there is no activity, you can call this function.

example:

import * as partnerSDK from '@8x8/pui-partner-comm';

partnerSDK.activity.idle();

signal

If you want to notify the 8x8 Application that there is activity, you can call this function.

example:

import * as partnerSDK from '@8x8/pui-partner-comm';

partnerSDK.activity.signal();

logging

The logging namespace exposes functions to control SDK internal logging for debugging purposes. Logging is disabled by default.

activate

Enables internal SDK logging to help with debugging and troubleshooting.

example:

import * as partnerSDK from '@8x8/pui-partner-comm';

partnerSDK.logging.activate();

deactivate

Disables internal SDK logging.

example:

import * as partnerSDK from '@8x8/pui-partner-comm';

partnerSDK.logging.deactivate();

getStatus

Returns the current logging status (true if enabled, false if disabled).

example:

import * as partnerSDK from '@8x8/pui-partner-comm';

const isLoggingEnabled = partnerSDK.logging.getStatus();
console.log('Logging enabled:', isLoggingEnabled);

files

The files namespace exposes functions to send files to 8x8 applications and access completed file transfers.

send

Sends a file to the 8x8 application with optional progress tracking, completion, and error handling callbacks.

example:

import * as partnerSDK from '@8x8/pui-partner-comm';

// Basic file send
const fileInput = document.getElementById('file-input') as HTMLInputElement;
const file = fileInput.files[0];

if (file) {
  const control = partnerSDK.files.send(file);
  
  if (control) {
    console.log('File send started with ID:', control.fileId);
    
    // Wait for completion or handle errors
    try {
      await control.promise;
      console.log('File sent successfully');
    } catch (error) {
      console.error('File send failed:', error);
    }
  }
}

// File send with progress tracking and callbacks
const control = partnerSDK.files.send(file, {
  onProgress: (progress) => {
    console.log(`Upload progress: ${progress.progress}% (${progress.transferredBytes}/${progress.totalBytes} bytes)`);
  },
  onComplete: (result) => {
    console.log('File sent successfully:', result.fileName);
    console.log('Transfer took:', result.duration, 'ms');
  },
  onError: (error) => {
    console.error('File send error:', error.error);
  },
  timeout: 60000 // 60 second timeout
});

// Cancel the transfer if needed
if (control) {
  // Later, if you need to cancel:
  await control.cancel();
}

The send method accepts two parameters:

• file (File) - The file object to send
• options (FileTransferOptions, optional) - Configuration object with the following optional properties:
  • fileId (string) - Optional custom file ID. If not provided, a unique ID will be auto-generated. Must be unique among active transfers.
  • onProgress (function) - Called periodically with transfer progress information
  • onComplete (function) - Called when the file transfer completes successfully
  • onError (function) - Called if an error occurs during transfer
  • timeout (number) - Transfer timeout in milliseconds (default: 30 seconds)

The method returns a FileTransferControl object containing:

• fileId (string) - Unique identifier for this transfer
• cancel (function) - Async function to cancel the transfer
• promise (Promise) - Promise that resolves when transfer completes or rejects on error

Returns undefined if the file sender is not available (e.g., if system.initialise was not called first).

Using Custom File IDs

You can optionally provide a custom file ID for better tracking and management of file transfers:

import * as partnerSDK from '@8x8/pui-partner-comm';

// Using custom file ID for better tracking
const customFileId = `document-${Date.now()}`;

try {
  const control = partnerSDK.files.send(file, {
    fileId: customFileId,
    onComplete: (result) => {
      console.log(`File with custom ID ${customFileId} sent successfully`);
      // Store the custom ID for later reference
      localStorage.setItem('lastUploadedFileId', customFileId);
    }
  });
  
  console.log('Started transfer with custom ID:', control.fileId); // Will be your custom ID
} catch (error) {
  if (error.message.includes('already in progress')) {
    console.error(`Transfer with ID ${customFileId} is already active`);
    // Handle duplicate ID error - perhaps generate a new ID or wait
  } else {
    console.error('Transfer failed:', error);
  }
}

// Auto-generated ID (default behavior)
const autoControl = partnerSDK.files.send(file); // fileId will be auto-generated
console.log('Auto-generated file ID:', autoControl?.fileId);

Important notes about custom file IDs:

• File IDs must be unique among active transfers
• If you provide a fileId that's already in use by an active transfer, an error will be thrown
• Custom IDs are useful for tracking specific files or implementing retry logic
• Auto-generated IDs are guaranteed to be unique and follow the format: file_${timestamp}_${randomString}

get

Retrieves a completed file by its key, or the latest completed file if no key is provided.

example:

import * as partnerSDK from '@8x8/pui-partner-comm';

// Get a specific file by key
const fileWithKey = partnerSDK.files.get('file-123');
if (fileWithKey) {
  console.log('File:', fileWithKey.fileName, fileWithKey.blob);
}

// Get the latest completed file
const latestFile = partnerSDK.files.get();
if (latestFile) {
  console.log('Latest file:', latestFile.fileName, latestFile.blob);
}

The function returns a CompletedFileWithKey object containing:

• fileName (string) - The name of the file
• blob (Blob) - The file content as a Blob object
• fileKey (string) - The unique key identifying the file

Returns undefined if no file is found for the specified key or if no files exist when no key is provided.

Handling Files as They Are Received

You can also listen for files as they complete transfer by handling the "file-transfer-complete" type in your onMessage callback:

import * as partnerSDK from '@8x8/pui-partner-comm';
import { type MessageData } from '@8x8/pui-partner-comm';

const onMessage = (data: MessageData) => {
  if (typeof data === 'object' && data.type === 'file-transfer-complete') {
    // Handle the file as soon as it's received
    console.log('File received:', data.message.fileName);
    console.log('File key:', data.message.fileKey);
    console.log('File blob:', data.message.blob);
    
    // process the file immediately
    // for example, create a download link:
    const url = URL.createObjectURL(data.message.blob);
    const link = document.createElement('a');
    link.href = url;
    link.download = data.message.fileName;
    link.click();
    URL.revokeObjectURL(url);
  }
};

partnerSDK.system.initialise({
  appName: 'partner-application-name',
  appVersion: '1.0.0',
  vendor: '8x8',
  onMessage,
});

This approach allows you to handle files immediately upon completion, while the files.get() function is useful for accessing files later or retrieving the most recent file.

resources

The resources namespace exposes functions that allow the partner to receive resources from 8x8 that can be used in the partner app.

getActivityScreen

Requests activity screen resources from the 8x8 application that can be used to display activity information in the partner app. This function can request customized activity screen data with optional parameters for heading, subheading, and active status.

This function receives one optional parameter as an object that has the following properties:

• heading - (string) the main heading text to display
• subheading - (string) the secondary text to display below the heading
• isActive - (boolean) whether the activity should be marked as active/highlighted

example:

import * as partnerSDK from '@8x8/pui-partner-comm';

// Request activity screen resources with specific parameters
partnerSDK.resources.getActivityScreen({
  heading: 'Customer Support Session',
  subheading: 'Active call with customer ID: 12345',
  isActive: true
});

// Request activity screen resources with activity status
partnerSDK.resources.getActivityScreen({
  isActive: false
});

// Request default activity screen resources
partnerSDK.resources.getActivityScreen();

The activity screen resources will be received asynchronously as part of the data for the onMessage function, which you can then use to display activity information in your partner app.

When isActive: true, the response will contain HTML resources like this sample (where HEADING and SUBHEADING are replaced with your provided values):

<div class="eght-activity-container" style="text-align: center; max-width: 400px; padding: 40px 20px; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;">
    <div class="eght-activity-svg" style="position: relative; display: inline-block; margin-bottom: 40px; width: 120px; height: auto;">
        <svg width="82" height="87" viewBox="0 0 82 87" fill="none" xmlns="http://www.w3.org/2000/svg">
        <path opacity="0.2" d="M14.5645 24H46.4512C53.6002 24.0001 59.5077 30.0775 59.5078 37.7158V59.4531C59.5078 67.0915 53.6003 73.1688 46.4512 73.1689H34.29C31.1126 73.1689 28.0791 74.4891 25.8535 76.8154L19.3057 83.6602C16.656 86.4298 11.9056 84.6141 11.9053 80.375V77.9297C11.9052 75.3639 9.89918 73.1689 7.28613 73.1689C4.15684 73.1689 1.50795 70.498 1.50781 67.0615V37.7158C1.50792 30.0775 7.41544 24.0001 14.5645 24Z" fill="#4A3DA4" stroke="#C4BAFF" stroke-width="3"/>
        <path fill-rule="evenodd" clip-rule="evenodd" d="M38.1172 40.1875C38.1172 44.1225 34.9272 47.3125 30.9922 47.3125C27.0572 47.3125 23.8672 44.1225 23.8672 40.1875C23.8672 36.2525 27.0572 33.0625 30.9922 33.0625C34.9272 33.0625 38.1172 36.2525 38.1172 40.1875ZM35.7422 40.1875C35.7422 42.8109 33.6155 44.9375 30.9922 44.9375C28.3688 44.9375 26.2422 42.8109 26.2422 40.1875C26.2422 37.5641 28.3688 35.4375 30.9922 35.4375C33.6155 35.4375 35.7422 37.5641 35.7422 40.1875Z" fill="#73348C"/>
        <path fill-rule="evenodd" clip-rule="evenodd" d="M42.8672 56.8125C42.8672 60.7475 37.5506 63.9375 30.9922 63.9375C24.4338 63.9375 19.1172 60.7475 19.1172 56.8125C19.1172 52.8775 24.4338 49.6875 30.9922 49.6875C37.5506 49.6875 42.8672 52.8775 42.8672 56.8125ZM40.4922 56.8125C40.4922 57.618 39.9356 58.753 38.1672 59.8141C36.446 60.8468 33.9149 61.5625 30.9922 61.5625C28.0694 61.5625 25.5384 60.8468 23.8172 59.8141C22.0488 58.753 21.4922 57.618 21.4922 56.8125C21.4922 56.007 22.0488 54.872 23.8172 53.8109C25.5384 52.7782 28.0694 52.0625 30.9922 52.0625C33.9149 52.0625 36.446 52.7782 38.1672 53.8109C39.9356 54.872 40.4922 56.007 40.4922 56.8125Z" fill="#73348C"/>
        <path d="M73.8482 6.51644L74.4544 4.95203C74.5487 4.7087 74.9043 4.7087 74.9986 4.95203L75.6048 6.51644C75.6343 6.5925 75.6963 6.65251 75.7749 6.68103L77.3915 7.26769C77.6429 7.35894 77.6429 7.70313 77.3915 7.79437L75.7749 8.38103C75.6963 8.40955 75.6343 8.46956 75.6048 8.54562L74.9986 10.11C74.9043 10.3534 74.5487 10.3534 74.4544 10.11L73.8482 8.54562C73.8187 8.46956 73.7567 8.40955 73.6781 8.38103L72.0615 7.79437C71.8101 7.70313 71.8101 7.35894 72.0615 7.26769L73.6781 6.68103C73.7567 6.65251 73.8187 6.5925 73.8482 6.51644Z" fill="#73348C"/>
        <path fill-rule="evenodd" clip-rule="evenodd" d="M65.4615 5.65343C65.1472 4.84233 63.9617 4.84233 63.6474 5.65343L61.2744 11.7772C61.1762 12.0308 60.9695 12.2308 60.7075 12.3259L54.3796 14.6223C53.5414 14.9265 53.5414 16.0738 54.3796 16.3779L60.7075 18.6743C60.9695 18.7694 61.1762 18.9695 61.2744 19.223L63.6474 25.3468C63.9617 26.1579 65.1472 26.1579 65.4615 25.3468L67.8345 19.223C67.9328 18.9695 68.1395 18.7694 68.4014 18.6743L74.7294 16.3779C75.5675 16.0738 75.5675 14.9265 74.7294 14.6223L68.4014 12.3259C68.1395 12.2308 67.9328 12.0308 67.8345 11.7772L65.4615 5.65343Z" fill="#73348C"/>
        <path d="M74.4544 20.8895L73.8482 22.4539C73.8187 22.53 73.7567 22.59 73.6781 22.6185L72.0615 23.2052C71.8101 23.2964 71.8101 23.6406 72.0615 23.7319L73.6781 24.3185C73.7567 24.3471 73.8187 24.4071 73.8482 24.4831L74.4544 26.0475C74.5487 26.2909 74.9043 26.2909 74.9986 26.0475L75.6048 24.4831C75.6343 24.4071 75.6963 24.3471 75.7749 24.3185L77.3915 23.7319C77.6429 23.6406 77.6429 23.2964 77.3915 23.2052L75.7749 22.6185C75.6963 22.59 75.6343 22.53 75.6048 22.4539L74.9986 20.8895C74.9043 20.6462 74.5487 20.6462 74.4544 20.8895Z" fill="#73348C"/>
        </svg>
    </div>

    <h1 class="eght-activity-heading" style="font-size: 28px; font-weight: 600; color: #2c3e50; margin: 0 0 16px 0; line-height: 1.3;">HEADING</h1>

    <p class="eght-activity-subheading" style="font-size: 16px; color: #6c757d; line-height: 1.4; margin: 0;">SUBHEADING</p>
</div>

Note: If you provide a heading parameter, it will replace HEADING in the HTML. Similarly, if you provide a subheading parameter, it will replace SUBHEADING in the HTML.

example of receiving and using the activity screen resources:

import { type MessageData } from '@8x8/pui-partner-comm';

const onMessage = (data: MessageData) => {
  // ... 
  if (typeof data === 'object') {
    if (data.type === 'response') {
      // here you will handle all the responses
      if (data.message.request === 'getActivityScreen' && data.message.namespace === 'resources') {
        // you know that the response contains activity screen resources from 8x8
        const activityScreenHTML = data.message.value;
        console.log('Received activity screen resources from 8x8:', activityScreenHTML);
        
        // Use the received HTML resources to display in your partner app
        document.getElementById('activity-container').innerHTML = activityScreenHTML;
      }
    }
  }
  // ...
}

system

The system namespace exposes

initialise

It is required to call this function as part of the integration. This function receives one parameter as an object that has the following properties:

• appName - (string) the name of the application
• appVersion - (string) the version of the application
• vendor - (string) the name of the company that owns the integration
• onMessage - (function) a function where you will write the code specific on your needs based on the data received from 8x8

example:

import * as partnerSDK from '@8x8/pui-partner-comm';
import { type MessageData } from '@8x8/pui-partner-comm';

const onMessage = (data: MessageData) => {
  // write what do you want to do with the data received
}

partnerSDK.system.initialise({
  appName: 'partner-application-name',
  appVersion: '1.0.0',
  vendor: '8x8',
  onMessage,
});

getContext

This function should be called if you want to retrieve the theme and the locale.

example:

import * as partnerSDK from '@8x8/pui-partner-comm';

partnerSDK.system.getContext();

the response will be received asynchronously as part of the data for the onMessage function.

example of data:

{
  "type": "response",
  "message": {
    "namespace": "system",
    "request": "getContext",
    "value": {
      "locale": "en-US",
      "theme": "light"
    }
  }
}

example of interacting with the data:

import { type MessageData } from '@8x8/pui-partner-comm';

const onMessage = (data: MessageData) => {
  // ... 
  if (typeof data === 'object') {
    if (data.type === 'response') {
      // here you will handle all the responses
      if (data.message.request === 'getContext') {
        // you know that the response is for `getContext`
        console.log(`received theme is ${data.message.value.theme} and the locale is ${data.message.value.locale}`); 
      }
    }
  }
  // ...
}

getLocale

This function should be called if you want to retrieve the locale.

example:

import * as partnerSDK from '@8x8/pui-partner-comm';

partnerSDK.system.getLocale();

the response will be received asynchronously as part of the data for the onMessage function.

example of data:

{
  "type": "response",
  "message": {
    "namespace": "system",
    "request": "getLocale",
    "value": "en-US"
  }
}

example of interacting with the data:

import { type MessageData } from '@8x8/pui-partner-comm';

const onMessage = (data: MessageData) => {
  // ... 
  if (typeof data === 'object') {
    if (data.type === 'response') {
      // here you will handle all the responses
      if (data.message.request === 'getLocale') {
        // you know that the response is for `getLocale`
        console.log(`received locale is ${data.message.value}`); 
      }
    }
  }
  // ...
}

getTheme

This function should be called if you want to retrieve the theme.

example:

import * as partnerSDK from '@8x8/pui-partner-comm';

partnerSDK.system.getTheme();

the response will be received asynchronously as part of the data for the onMessage function.

example of data:

{
  "type": "response",
  "message": {
    "namespace": "system",
    "request": "getTheme",
    "value": "light"
  }
}

example of interacting with the data:

import { type MessageData } from '@8x8/pui-partner-comm';

const onMessage = (data: MessageData) => {
  // ... 
  if (typeof data === 'object') {
    if (data.type === 'response') {
      // here you will handle all the responses
      if (data.message.request === 'getTheme') {
        // you know that the response is for `getTheme`
        console.log(`received theme is ${data.message.value.theme}`); 
      }
    }
  }
  // ...
}

getVersion

This function should be called if you want to retrieve the versions of the SDK components.

Available from version 0.6.0

example:

import * as partnerSDK from '@8x8/pui-partner-comm';

partnerSDK.system.getVersion();

the response will be received asynchronously as part of the data for the onMessage function.

example of data:

{
  "type": "response",
  "message": {
    "namespace": "system",
    "request": "getVersion",
    "value": {
      "mfeVersion": "1.3.1+21a7e27",
      "parentVersion": "0.23.0+32e8f38",
      "partnerVersion": "0.5.0+7e765ef"
    }
  }
}

example of interacting with the data:

import { type MessageData } from '@8x8/pui-partner-comm';

const onMessage = (data: MessageData) => {
  // ... 
  if (typeof data === 'object') {
    if (data.type === 'response') {
      // here you will handle all the responses
      if (data.message.request === 'getVersion' &&  data.message.namespace === 'system') {
        // you know that the response is for `getVersion` from the `system` namespace
        console.log('received versions are: ', data.message.value); 
      }
    }
  }
  // ...
}

getEvents

This function should be called if you want to retrieve the events that can be received.

Available from version 0.7.0

example:

import * as partnerSDK from '@8x8/pui-partner-comm';

partnerSDK.system.getEvents();

the response will be received asynchronously as part of the data for the onMessage function.

example of data:

{
  "type": "response",
  "message": {
    "namespace": "system",
    "request": "getEvents",
    "value": {
      "global-user-details-v1": [
        "1.0.0"
      ],
      "aw-interaction-mute-v1": [
        "1.0.0"
      ],
      "aw-interaction-unmute-v1": [
        "1.0.0"
      ],
      "aw-interaction-hold-v1": [
        "1.0.0"
      ],
      "aw-close-agent-assist-v1": [
        "1.0.0"
      ],
      "aw-interaction-focus-v1": [
        "1.0.0"
      ],
      "aw-interaction-resume-v1": [
        "1.0.0"
      ],
      "aw-interaction-wrap-up-codes-v1": [
        "1.0.0"
      ]
    }
  }
}

example of interacting with the data:

import { type MessageData } from '@8x8/pui-partner-comm';

const onMessage = (data: MessageData) => {
  // ... 
  if (typeof data === 'object') {
    if (data.type === 'response') {
      // here you will handle all the responses
      if (data.message.request === 'getEvents' &&  data.message.namespace === 'system') {
        // you know that the response is for `getEvents` from the `system` namespace
        console.log('received events are: ', data.message.value); 
      }
    }
  }
  // ...
}

sendMessage

This function should be called if you want to send message. This function takes the argument of the type String.

example:

import * as partnerSDK from '@8x8/pui-partner-comm';

partnerSDK.system.sendMessage("Hello World");

In case the data sent is invalid, an error will be received asynchronously as part of the data for the onMessage function.

example of data:

{
  "type": "error",
  "message": {
    "original": {}, // original message sent
    "error": "Invalid message"
  }
}

sendEvent

This function should be called if you want to send a custom event to 8x8 applications. This function takes two parameters: name (string) - the event name, and data (unknown) - the event data payload.

example:

import * as partnerSDK from '@8x8/pui-partner-comm';

// Send a chat message received event
partnerSDK.system.sendEvent("aw-chat-message-received-v1", {
  interactionId: "INTERACTION_ID",
  message: "something relevant",
  schemaVersion: "1.0.0"
});

In case the event data sent is invalid, an error will be received asynchronously as part of the data for the onMessage function, similar to the sendMessage function error handling.

Events

For a comprehensive list of events that partners can receive or send, please consult the Partner SDK Events documentation.

Types

For the types used please see TYPES.md or TYPES.md on unpkg.com or TYPES.md on jsdelivr.net