npm package: @machengji/chatwoot-sdk
Description: SDK for JS/Typescript for Chatwoot.
Author: Figuro
Latest version: 1.0.5

# @machengji/chatwoot-sdk

[![npm (scoped)](https://img.shields.io/npm/v/@machengji/chatwoot-sdk)](https://www.npmjs.com/package/@machengji/chatwoot-sdk) [![NPM](https://img.shields.io/npm/l/@machengji/chatwoot-sdk)](https://opensource.org/licenses/MIT)

一个功能完整的 JavaScript/TypeScript Chatwoot API 客户端库，提供完整的类型支持和易于使用的接口来与 Chatwoot 平台进行交互。

## 特性

- ✅ **完整的 TypeScript 支持** - 提供完整的类型定义和智能提示
- ✅ **轻量级设计** - 仅依赖 Axios，无其他外部依赖
- ✅ **功能丰富** - 支持消息、对话、联系人、客服等所有主要功能
- ✅ **文件上传支持** - 支持附件上传功能
- ✅ **错误处理** - 完善的错误处理机制
- ✅ **请求取消** - 支持请求取消功能
- ✅ **多种认证方式** - 支持 Bearer Token 和 Basic Auth
- ✅ **多租户架构** - 支持多商家账户管理和客户消息处理
- ✅ **Public API 支持** - 支持客户身份标识和消息发送

## 安装

### 使用 npm
```bash
npm install @machengji/chatwoot-sdk
```

### 使用 yarn
```bash
yarn add @machengji/chatwoot-sdk
```

### 使用 pnpm
```bash
pnpm add @machengji/chatwoot-sdk
```

## 快速开始

### 基本配置

```typescript
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"
    }
});
```

### 发送消息

```typescript
// 发送文本消息
const message = await client.messages.create({
    accountId: 1,
    conversationId: 8,
    data: {
        content: "Hello, World!",
        message_type: "outgoing"
    }
});

console.log("消息已发送:", message);
```

### 发送带附件的消息

```typescript
// 发送带附件的消息
const messageWithAttachment = await client.messages.create({
    accountId: 1,
    conversationId: 8,
    data: {
        content: "请查看附件",
        message_type: "outgoing",
        attachments: [
            {
                content: "iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAABmJLR0QA/...", // base64 编码
                encoding: "base64",
                filename: "document.pdf"
            }
        ]
    }
});
```

### 获取对话列表

```typescript
// 获取所有对话
const conversations = await client.conversations.list({
    accountId: 1,
    status: "open", // 可选: "open", "resolved", "pending"
    page: 1
});

console.log("对话列表:", conversations);
```

### 管理联系人

```typescript
// 创建新联系人
const newContact = await client.contacts.create({
    accountId: 1,
    data: {
        name: "张三",
        email: "zhangsan@example.com",
        phone_number: "+86 138 0013 8000",
        custom_attributes: {
            company: "示例公司",
            position: "产品经理"
        }
    }
});

// 获取联系人列表
const contacts = await client.contacts.list({
    accountId: 1,
    page: 1,
    sort: "last_activity_at"
});
```

### 多租户架构支持

```typescript
// 创建商家账户
const account = await client.multiTenant.accounts.createAccount({
    data: {
        name: "商家A",
        domain: "merchant-a.com",
        support_email: "support@merchant-a.com"
    }
});

// 为商家创建管理员
const admin = await client.multiTenant.accounts.createAccountAdmin({
    accountId: account.id,
    data: {
        name: "商家A管理员",
        email: "admin@merchant-a.com",
        password: "secure_password_123",
        role: "administrator"
    }
});

// 使用Public API处理客户消息
const contact = await client.publicAPI.createContact({
    inboxIdentifier: "inbox_identifier",
    data: {
        name: "客户姓名",
        email: "client@example.com",
        identifier: "user_12345"
    }
});
```

## 主要功能

### 消息管理
- 发送文本消息和附件
- 获取消息列表
- 更新和删除消息

### 对话管理
- 获取对话列表和详情
- 更新对话状态
- 分配对话给客服

### 联系人管理
- 创建、更新、删除联系人
- 获取联系人列表和详情
- 管理自定义属性

### 客服管理
- 管理客服账户
- 分配对话
- 查看客服指标

### 收件箱管理
- 创建和管理收件箱
- 配置不同渠道

### 团队管理
- 创建和管理团队
- 分配客服到团队

### 预设回复
- 创建和管理预设回复
- 快速回复功能

## 错误处理

```typescript
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);
    }
}
```

## 环境变量配置

```typescript
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 应用

```typescript
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](./USAGE.md) 获取完整的使用文档，包括：

- 详细的 API 参考
- 更多使用示例
- 错误处理指南
- 最佳实践
- 常见问题解答

## 支持的 Chatwoot 版本

此 SDK 与 Chatwoot API v1 兼容，支持 Chatwoot 平台的最新功能。

## 许可证

MIT License

## 支持

如果您在使用过程中遇到问题：

1. 查看 [详细使用文档](./USAGE.md)
2. 参考 [Chatwoot 官方 API 文档](https://www.chatwoot.com/developers/api/)
3. 检查您的 API 令牌和权限设置
4. 确认网络连接和 Chatwoot 实例状态

---

**注意**: 请确保在生产环境中妥善保管您的 API 令牌，不要将其提交到版本控制系统中。