@machengji/chatwoot-sdk

一个功能完整的 JavaScript/TypeScript Chatwoot API 客户端库，提供完整的类型支持和易于使用的接口来与 Chatwoot 平台进行交互。

特性

• ✅ 完整的 TypeScript 支持 - 提供完整的类型定义和智能提示
• ✅ 轻量级设计 - 仅依赖 Axios，无其他外部依赖
• ✅ 功能丰富 - 支持消息、对话、联系人、客服等所有主要功能
• ✅ 文件上传支持 - 支持附件上传功能
• ✅ 错误处理 - 完善的错误处理机制
• ✅ 请求取消 - 支持请求取消功能
• ✅ 多种认证方式 - 支持 Bearer Token 和 Basic Auth
• ✅ 多租户架构 - 支持多商家账户管理和客户消息处理
• ✅ Public API 支持 - 支持客户身份标识和消息发送

安装

使用 npm

npm install @machengji/chatwoot-sdk

使用 yarn

yarn add @machengji/chatwoot-sdk

使用 pnpm

pnpm add @machengji/chatwoot-sdk

快速开始

基本配置

import ChatwootClient from "@machengji/chatwoot-sdk";

const client = new ChatwootClient({
    config: {
        basePath: "https://app.chatwoot.com",
        with_credentials: true,
        credentials: "include",
        token: "YOUR_API_TOKEN_HERE"
    }
});

发送消息

// 发送文本消息
const message = await client.messages.create({
    accountId: 1,
    conversationId: 8,
    data: {
        content: "Hello, World!",
        message_type: "outgoing"
    }
});

console.log("消息已发送:", message);

发送带附件的消息

// 发送带附件的消息
const messageWithAttachment = await client.messages.create({
    accountId: 1,
    conversationId: 8,
    data: {
        content: "请查看附件",
        message_type: "outgoing",
        attachments: [
            {
                content: "iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAABmJLR0QA/...", // base64 编码
                encoding: "base64",
                filename: "document.pdf"
            }
        ]
    }
});

获取对话列表

// 获取所有对话
const conversations = await client.conversations.list({
    accountId: 1,
    status: "open", // 可选: "open", "resolved", "pending"
    page: 1
});

console.log("对话列表:", conversations);

管理联系人

// 创建新联系人
const newContact = await client.contacts.create({
    accountId: 1,
    data: {
        name: "张三",
        email: "[email protected]",
        phone_number: "+86 138 0013 8000",
        custom_attributes: {
            company: "示例公司",
            position: "产品经理"
        }
    }
});

// 获取联系人列表
const contacts = await client.contacts.list({
    accountId: 1,
    page: 1,
    sort: "last_activity_at"
});

多租户架构支持

// 创建商家账户
const account = await client.multiTenant.accounts.createAccount({
    data: {
        name: "商家A",
        domain: "merchant-a.com",
        support_email: "[email protected]"
    }
});

// 为商家创建管理员
const admin = await client.multiTenant.accounts.createAccountAdmin({
    accountId: account.id,
    data: {
        name: "商家A管理员",
        email: "[email protected]",
        password: "secure_password_123",
        role: "administrator"
    }
});

// 使用Public API处理客户消息
const contact = await client.publicAPI.createContact({
    inboxIdentifier: "inbox_identifier",
    data: {
        name: "客户姓名",
        email: "[email protected]",
        identifier: "user_12345"
    }
});

主要功能

消息管理

• 发送文本消息和附件
• 获取消息列表
• 更新和删除消息

对话管理

• 获取对话列表和详情
• 更新对话状态
• 分配对话给客服

联系人管理

• 创建、更新、删除联系人
• 获取联系人列表和详情
• 管理自定义属性

客服管理

• 管理客服账户
• 分配对话
• 查看客服指标

收件箱管理

• 创建和管理收件箱
• 配置不同渠道

团队管理

• 创建和管理团队
• 分配客服到团队

预设回复

• 创建和管理预设回复
• 快速回复功能

错误处理

import { ApiError } from "@machengji/chatwoot-sdk";

try {
    const message = await client.messages.create({
        accountId: 1,
        conversationId: 8,
        data: {
            content: "Hello, World!"
        }
    });
} catch (error) {
    if (error instanceof ApiError) {
        console.error("API 错误:", error.message);
        console.error("状态码:", error.status);
        console.error("响应:", error.body);
    } else {
        console.error("其他错误:", error);
    }
}

环境变量配置

const client = new ChatwootClient({
    config: {
        basePath: process.env.CHATWOOT_BASE_URL || "https://app.chatwoot.com",
        token: process.env.CHATWOOT_API_TOKEN,
        with_credentials: true,
        credentials: "include"
    }
});

完整示例

Node.js 应用

import ChatwootClient from "@machengji/chatwoot-sdk";

class ChatwootService {
    private client: ChatwootClient;

    constructor() {
        this.client = new ChatwootClient({
            config: {
                basePath: process.env.CHATWOOT_BASE_URL!,
                token: process.env.CHATWOOT_API_TOKEN!,
                with_credentials: true,
                credentials: "include"
            }
        });
    }

    async sendWelcomeMessage(conversationId: number, accountId: number) {
        try {
            const message = await this.client.messages.create({
                accountId,
                conversationId,
                data: {
                    content: "欢迎联系我们！我们很高兴为您服务。",
                    message_type: "outgoing"
                }
            });
            return message;
        } catch (error) {
            console.error("发送消息失败:", error);
            throw error;
        }
    }

    async getUnreadConversations(accountId: number) {
        try {
            const conversations = await this.client.conversations.list({
                accountId,
                status: "open"
            });
            return conversations.data.filter(conv => conv.unread_count > 0);
        } catch (error) {
            console.error("获取对话失败:", error);
            throw error;
        }
    }
}

// 使用示例
const chatwootService = new ChatwootService();
chatwootService.sendWelcomeMessage(8, 1)
    .then(message => console.log("消息已发送:", message))
    .catch(error => console.error("发送失败:", error));

详细文档

查看 USAGE.md 获取完整的使用文档，包括：

• 详细的 API 参考
• 更多使用示例
• 错误处理指南
• 最佳实践
• 常见问题解答

支持的 Chatwoot 版本

此 SDK 与 Chatwoot API v1 兼容，支持 Chatwoot 平台的最新功能。

许可证

MIT License

支持

如果您在使用过程中遇到问题：

1. 查看 详细使用文档
2. 参考 Chatwoot 官方 API 文档
3. 检查您的 API 令牌和权限设置
4. 确认网络连接和 Chatwoot 实例状态

注意: 请确保在生产环境中妥善保管您的 API 令牌，不要将其提交到版本控制系统中。