@falconix/messager

English | 中文

English

Features

• 🎨 Customizable bubble button (color, size, position)
• 📱 Responsive iframe chat window
• 🔒 Type-safe with TypeScript
• 🌐 Cross-browser compatibility
• 🚀 Easy integration with any website
• 📦 Zero dependencies (vanilla JS)
• 🌍 Support for multi-language (language parameter)

Installation

npm install @falconix/messager

Usage

Basic Usage

import { createMessenger } from "@falconix/messager";

const appEl = document.getElementById("app");

async function createApi() {
  const result = await createMessenger({
    version: 1.0.0, // Required: API version (default: 1.0.0)
    widgetKey: "a1b2c3d4", // Required: widget key
    token: "your-token-here", // Required: authentication token
    language: "en", // Required: language code (e.g., "en", "zh-CN")
  });

  if (result.kind === "error") throw new Error(result.error);

  const { api } = result.value;

  if (api === null) {
    throw new Error(
      "api reached end-of-life, please check documentation and upgrade.",
    );
  }

  return api;
}

async function mount(api) {
  const result = await api.mount();
  if (result.kind === "error") throw new Error(result.error);
  return api;
}

async function run() {
  const api = await createApi();
  const subscription = api.mount().subscribe((result) => {
    if (result.kind === "error") {
      const message = `Failed to mount messenger: ${result.error}`;
      console.error(message);
      appEl.innerHTML = message;
      return;
    }
    if (result.value === null) {
      const message = `Not mounting messenger: ${result.reason}`;
      appEl.innerHTML = message;
      return;
    }

    const messenger = result.value;
    console.log("Mounted messenger:", messenger);
    appEl.innerHTML = "Falconix messenger mounted";
  });

  return subscription;
}

run()
  .then((subscription) => {
    // To unmount the messenger when you need to, just unsubscribe.
    // subscription.unsubscribe();
  })
  .catch(console.error);

Advanced Configuration

const result = await createMessenger({
  version: 1.0.0, // Required: API version (default: 1.0.0)
  widgetKey: "a1b2c3d4",  // Required: widget key
  token: "your-token-here", // Required: authentication token
  language: "zh-CN", // Required: language code (e.g., "en", "zh-CN")
  bubbleColor: "#4F46E5", // Optional: bubble color (hex)
  bubbleImage: "path/to/image.png", // Optional: bubble image URL
  bubblePosition: "bottom-right", // Optional: "bottom-right" or "bottom-left"
  bubbleSize: 60, // Optional: bubble size in pixels (40-100)
  zIndex: 9999, // Optional: z-index value
});

API Reference

createMessenger(config)

Creates a new messenger instance.

Parameters:

• config (Object):
  • version (number, optional): API version (default: 1.0.0)
  • widgetKey (string, required): Your unique widget key (default: "a1b2c3d4")
  • token (string, optional): Authentication token for the chat service
  • language (string, optional): Language code (e.g., "en", "zh-CN", "ja")
  • bubbleColor (string, optional): Bubble button color in hex format
  • bubbleImage (string, optional): Bubble image URL (default: "assets/bubble.png")
  • bubblePosition (string, optional): Position of bubble ("bottom-right" or "bottom-left")
  • bubbleSize (number, optional): Size of bubble in pixels (40-100, default: 50)
  • zIndex (number, optional): CSS z-index value

Returns: Promise<CreateMessengerResult>

MessengerAPI

The main API interface returned by createMessenger.

Methods:

• mount(): Mounts the messenger widget to the DOM
• unmount(): Removes the messenger widget from the DOM
• open(): Opens the chat window
• close(): Closes the chat window
• isOpen(): Returns whether the chat window is currently open

Types

interface MessengerConfig {
  version?: number;
  widgetKey: string;
  token?: string;
  language?: string;
  bubbleColor?: string;
  bubbleImage?: string;
  bubblePosition?: 'bottom-right' | 'bottom-left';
  bubbleSize?: number;
  zIndex?: number;
}

interface CreateMessengerResult {
  kind: "success" | "error";
  value?: { api: MessengerAPI | null };
  error?: string;
}

interface MountResult {
  kind: "success" | "error";
  value: Messenger | null;
  error?: string;
  reason?: string;
}

Browser Compatibility

• Chrome/Edge (latest)
• Firefox (latest)
• Safari (latest)
• Opera (latest)

License

MIT

Support

For support and questions, please contact Falconix support team.

中文

特性

• 🎨 可自定义气泡按钮（颜色、大小、位置）
• 📱 响应式 iframe 聊天窗口
• 🔒 TypeScript 类型安全
• 🌐 跨浏览器兼容性
• 🚀 轻松集成到任何网站
• 📦 零依赖（原生 JavaScript）
• 🌍 支持多语言（language 参数）

安装

npm install @falconix/messager

使用方法

基础用法

import { createMessenger } from "@falconix/messager";

const appEl = document.getElementById("app");

async function createApi() {
  const result = await createMessenger({
    version: 1.0.0, // 必须：API 版本（默认：1.0.0）
    widgetKey: "a1b2c3d4", // 必须：小部件密钥
    token: "your-token-here", // 必须：认证令牌
    language: "en", // 必须：语言代码（如 "en"、"zh-CN"、"ja"）
  });

  if (result.kind === "error") throw new Error(result.error);

  const { api } = result.value;

  if (api === null) {
    throw new Error(
      "api reached end-of-life, please check documentation and upgrade.",
    );
  }

  return api;
}

async function mount(api) {
  const result = await api.mount();
  if (result.kind === "error") throw new Error(result.error);
  return api;
}

async function run() {
  const api = await createApi();
  const subscription = api.mount().subscribe((result) => {
    if (result.kind === "error") {
      const message = `Failed to mount messenger: ${result.error}`;
      console.error(message);
      appEl.innerHTML = message;
      return;
    }
    if (result.value === null) {
      const message = `Not mounting messenger: ${result.reason}`;
      appEl.innerHTML = message;
      return;
    }

    const messenger = result.value;
    console.log("Mounted messenger:", messenger);
    appEl.innerHTML = "Falconix messenger mounted";
  });

  return subscription;
}

run()
  .then((subscription) => {
    // 如需卸载信使，只需取消订阅
    // subscription.unsubscribe();
  })
  .catch(console.error);

高级配置

const result = await createMessenger({
  version: 1.0.0, // 必须：API 版本（默认：1.0.0）
  widgetKey: "a1b2c3d4", // 必须：小部件密钥
  token: "your-token-here", // 必须：认证令牌
  language: "zh-CN", // 必须：语言代码（如 "en"、"zh-CN"、"ja"）
  bubbleColor: "#4F46E5", // 可选：气泡颜色（十六进制）
  bubbleImage: "path/to/image.png", // 可选：气泡图片 URL
  bubblePosition: "bottom-right", // 可选："bottom-right" 或 "bottom-left"
  bubbleSize: 60, // 可选：气泡大小（40-100像素）
  zIndex: 9999, // 可选：z-index 值
});

API 参考

createMessenger(config)

创建新的信使实例。

参数：

• config (Object):
  • version (number, 可选): API 版本（默认：1.0.0）
  • widgetKey (string, 必填): 您的唯一小部件密钥（默认："a1b2c3d4"）
  • token (string, 可选): 聊天服务的认证令牌
  • language (string, 可选): 语言代码（如 "en"、"zh-CN"、"ja"）
  • bubbleColor (string, 可选): 气泡按钮颜色（十六进制格式）
  • bubbleImage (string, 可选): 气泡图片 URL（默认："src/assets/bubble.png"）
  • bubblePosition (string, 可选): 气泡位置（"bottom-right" 或 "bottom-left"）
  • bubbleSize (number, 可选): 气泡大小（40-100像素，默认：50）
  • zIndex (number, 可选): CSS z-index 值

返回： Promise<CreateMessengerResult>

MessengerAPI

由 createMessenger 返回的主要 API 接口。

方法：

• mount(): 将信使小部件挂载到 DOM
• unmount(): 从 DOM 中移除信使小部件
• open(): 打开聊天窗口
• close(): 关闭聊天窗口
• isOpen(): 返回聊天窗口是否当前打开

类型定义

interface MessengerConfig {
  version?: number;
  widgetKey: string;
  token?: string;
  language?: string;
  bubbleColor?: string;
  bubbleImage?: string;
  bubblePosition?: 'bottom-right' | 'bottom-left';
  bubbleSize?: number;
  zIndex?: number;
}

interface CreateMessengerResult {
  kind: "success" | "error";
  value?: { api: MessengerAPI | null };
  error?: string;
}

interface MountResult {
  kind: "success" | "error";
  value: Messenger | null;
  error?: string;
  reason?: string;
}

PostMessage API

聊天窗口会监听来自 iframe 的 postMessage 事件。要从 iframe 内部关闭聊天窗口，请发送类型为 'close' 的消息：

// 在 iframe 内部（您的聊天页面）
window.parent.postMessage({ type: "close" }, "*");

收到此消息后，聊天窗口将关闭，气泡按钮将重新显示。

浏览器兼容性

• Chrome/Edge（最新版本）
• Firefox（最新版本）
• Safari（最新版本）
• Opera（最新版本）

许可证

MIT

支持

如需支持和问题解答，请联系 Falconix 支持团队。