Omi SDK

A lightweight, customizable TypeScript SDK that can be embedded in any website. This SDK provides a simple API for integrating with your web applications and supports chat/call/video call for interactions.

Features

• Easy embedding via script tag or import
• Multiple UI modes (bubble and headless)
• chat/call/video call with event handling
• Customizable themes
• Event-driven architecture
• Small footprint with minimal dependencies
• Support for modern and legacy browsers

Installation

Using npm

npm install @mptransformation/omisdk

Using a script tag

<script src="./js/omisdk.iife.js"></script>

Usage

Basic Usage

<!-- Auto-initialization with data attributes -->
<script
  src="./js/omisdk.iife.js"
  data-auto-init="true"
  data-target-element-id="sdk-container"
  data-mode="bubble"
  data-debug="true"
></script>

<div id="sdk-container"></div>

Programmatic Initialization

// Import the SDK (ESM)
import { OmiSDK } from "@mptransformation/omisdk";

// Initialize the SDK
const sdk = new OmiSDK({
  targetElementId: "sdk-container",
  mode: "bubble", // 'bubble' or 'none'
  debug: true,
  theme: {
    primaryColor: "#4CAF50",
    secondaryColor: "#45a049",
    bubblePosition: "bottom-right",
  },
});

// Initialize the SDK
sdk.init();

// Listen for events
sdk.on("AppEvent", (event: AppEvent) => {
  console.log("appEvent received:", event);
});

sdk.on("CallEvent", (event: CallEvent) => {
  console.log("callEvent received:", event);
});

// Make a call
sdk.makeCall("1234567890").then((response) => {
  console.log("Call initiated:", response);
});

// Destroy the SDK when done
sdk.destroy();

API Reference

SDK Options

| Option | Type | Default | Description | | ----------------- | ------- | ------------------- | ----------------------------------------------- | | targetElementId | string | "omi-sdk-container" | ID of the element where the SDK will be mounted | | mode | string | "bubble" | UI mode: "bubble" or "none" | | socketUrl | string | null | WebSocket server URL | | debug | boolean | false | Enable debug logging | | theme | object | {} | Custom theme options |

Theme Options

| Option | Type | Description | | ----------------- | ------ | ------------------------------------------------------------------------------ | | primaryColor | string | Primary color for UI elements | | secondaryColor | string | Secondary color for UI elements | | textColor | string | Text color | | backgroundColor | string | Background color | | fontFamily | string | Font family for text | | borderRadius | string | Border radius for UI elements | | bubblePosition | string | Position of the bubble: "top-left", "top-right", "bottom-left", "bottom-right" |

Methods

| Method | Description | | --------------------------------------------- | ---------------------------------------- | | init(options?: SDKOptions) | Initialize the SDK with options | | destroy() | Clean up and remove the SDK from the DOM | | updateOptions(options: Partial<SDKOptions>) | Update SDK options | | getVersion() | Get the SDK version | | getOptions() | Get the current SDK options | | on(event: string, callback: Function) | Register an event listener | | off(event: string, callback: Function) | Remove an event listener | | connectSocket() | Connect to the WebSocket server | | disconnectSocket() | Disconnect from the WebSocket server | | sendSocketEvent(name: string, data: any) | Send an event to the socket server | | login(request: LoginRequest) | Login with username and password | | loginSSO(request: LoginSSORequest) | Login with SSO token | | logout() | Logout the current user | | makeCall(destination: string, options?) | Make a call to a destination | | hangup() | Hangup the current call | | answerCall(options?) | Answer an incoming call | | rejectCall() | Reject an incoming call | | hold() | Hold the current call | | unhold() | Resume the current call | | mute() | Mute the current call | | unmute() | Unmute the current call | | cameraOn() | Turn on the camera | | cameraOff() | Turn off the camera | | transfer(destination: string) | Transfer the current call | | changeAgentStatus(status: string) | Change the agent status | | getAgentStatus() | Get the agent status | | hideBubble() | Hide the bubble | | showBubble() | Show the bubble |

UI Modes

Bubble Mode

In bubble mode, the SDK displays a floating bubble in the corner of the screen that users can interact with. The bubble position can be customized using the theme options.

None Mode (Headless)

In none mode, the SDK operates without any visible UI elements, allowing you to build your own UI on top of the SDK's functionality.

Examples

Check out the examples directory for more detailed usage examples:

• Basic Usage - Shows basic SDK initialization and usage

To run the examples with the socket server:

# Build the SDK first
npm run build

# Run both the examples server and socket server
npm start

Then open http://localhost:3000/examples/socket-example.html in your browser.

Development

Prerequisites

• Node.js 16+
• npm or yarn

Setup

# Clone the repository
git clone https://github.com/MPG-MPTransformation/mptsdk.git
cd mptsdk

# Install dependencies
npm install

# Build the SDK
npm run build

# Serve examples
npm run serve-examples

Available Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm run test - Run tests
• npm run test:watch - Run tests in watch mode
• npm run test:coverage - Run tests with coverage
• npm run demo - Serve the demo page
• npm start - Run both the examples server and socket server

License

MIT

Using Types with ESLint in ReactJS Projects

This SDK provides TypeScript type definitions that can be used with ESLint in ReactJS projects. This helps with type checking and autocompletion when using the SDK in your React application.

Installation

npm install @mptransformation/omisdk

Basic Usage with TypeScript and ESLint

1. Import the types in your React component:

import React, { useEffect } from "react";
import omisdk from "@mptransformation/omisdk";
import type { SDKOptions, SDKTheme } from "@mptransformation/omisdk";

const MyComponent: React.FC = () => {
  useEffect(() => {
    // Configure the SDK with proper typing
    const options: SDKOptions = {
      targetElementId: "sdk-container",
      mode: "bubble",
      theme: {
        primaryColor: "#007bff",
        textColor: "#333333",
      },
    };

    // Initialize the SDK
    omisdk.init(options);

    // Clean up on unmount
    return () => {
      omisdk.destroy();
    };
  }, []);

  return <div id="sdk-container">{/* SDK will be mounted here */}</div>;
};

export default MyComponent;

2. For ESLint configuration, add the following to your .eslintrc.js file:

module.exports = {
  // ... your existing ESLint config
  settings: {
    "import/resolver": {
      typescript: {
        alwaysTryTypes: true,
      },
    },
  },
  rules: {
    // ... your existing rules
  },
};

3. If you need to access the global instance in a non-TypeScript file, you can use the global type:

// The window.omisdk type is already defined in the SDK's type definitions
window.omisdk.init({
  targetElementId: "sdk-container",
  mode: "bubble",
});

Advanced Type Usage

For more advanced type usage, you can import specific types:

import type {
  SDKOptions,
  SDKTheme,
  SocketEvent,
  CallEventType,
  CallEvent,
} from "@mptransformation/omisdk";

// Use the types in your code
const handleCallEvent = (event: CallEvent) => {
  if (event.type === CallEventType.CALL_INCOMING) {
    console.log("Incoming call from:", event.senderId);
  }
};

// Subscribe to events with proper typing
omisdk.on("call", handleCallEvent);