Twilio Flex Utils UI Library

Overview

This library provides utility methods for interacting with the Twilio Flex UI. Below are examples demonstrating how to use the library to fetch workers in a Flex TaskRouter workspace and manage locale strings in a Flex plugin.

Usage

Installation

npm install @twilio/flex-plugins-library-utils-ui

Example

The following example shows how to set up a TaskRouterService class to fetch all workers in a Flex TaskRouter workspace using the ApiService and ErrorManager utilities.

import { ApiService, ErrorManager } from '@twilio/flex-plugins-library-utils-ui';
import packageJSON from 'path-to-package.json';

const errorManagerInstance = new ErrorManager({ 
  name: packageJSON.name, 
  version: packageJSON.version 
});

class TaskRouterService extends ApiService {
  constructor() {
    super({
      serverlessDomain: 'my-serverless-domain.twil.io',
      retryConfig: {
        maxAttempts: 5,
        maxRetryDelay: 8000,
        retryInterval: 1000,
      },
      errorManager: errorManagerInstance,
    });
  }

  // ... rest of TaskRouterService implementation
}

Explanation

• ApiService: Base class for making API calls to the TaskRouter service.
• ErrorManager: Initialize an error manager with the plugin's name and version from package.json.
• Configuration: The serverlessDomain and retryConfig are used to configure the API service for reliable requests.

Managing Locale Strings in a Flex Plugin

This example demonstrates how to integrate locale strings into a Flex plugin, supporting both default and dynamic locale loading for Flex UI versions 2.7 and above.

import * as Flex from '@twilio/flex-ui';
import { getLocaleStrings, FlexPluginLibrary } from '@twilio/flex-plugins-library-utils-ui';
import packageJSON from 'path-to-package.json';
import enUS from 'path-to-en-US';

export default async (flex: typeof Flex, manager: Flex.Manager) => {
  const localeUrl = getLocaleUrl(FlexPluginLibrary.ActivityReservationHandler, packageJSON.version);
  const pluginStrings = enUS;

  // Add default plugin strings to the manager
  manager.strings = {
    ...pluginStrings,
    ...manager.strings,
  };

  // manager.localization is only defined from Flex UI 2.7 onwards
  if ((manager as any).localization) {
    const { localeTag } = (manager as any).localization;

    const fetchStrings = async () => {
      const remoteData = await getLocaleStrings(localeUrl, localeTag);
      if (remoteData) {
        manager.strings = {
          ...manager.strings,
          ...remoteData.strings,
        };
      }
    };
    await fetchStrings();
  }
};

Explanation

• Default Strings: The en-US strings are merged with the manager's existing strings to provide default localization.
• Dynamic Locale Loading: For Flex UI 2.7+, the getLocaleStrings function fetches remote strings based on the localeTag and updates the manager's strings.

Requirements

• Twilio Flex UI (version 2.7+ for dynamic locale support) @twilio/flex-plugins-library-utils-ui package A valid package.json file with name and version fields Locale files (e.g., en-US) for default strings

Setup

Install the required library:

npm install @twilio/flex-plugins-library-utils-ui

• Ensure your package.json is configured with the correct name and version. Import and use the utilities as shown in the examples above.

⚠️ Note

Always validate the serverlessDomain and localeUrl to avoid runtime errors.