Sulla

Sulla 是一个 JavaScript 库，提供对 WhatsApp 的高级 API 控制，可以轻松配置以自动化回复或处理通过 WhatsApp 传输的任何数据。

它基于 Puppeteer 构建。

Sulla 当前状态

截至 2.3.5 版本，Sulla 已经具备非常丰富且稳定的功能和架构。 尽管我非常希望继续维护这个项目，但我目前无法投入大量时间。因此，建议您查看 Sulla 的分支版本，这些版本由其他开发者维护，能够获得更好的支持。

推荐的活跃维护的基于 Sulla 的项目：

venom

wppconnect

open-wa/wa-automate

安装

> npm i sulla --save

快速入门

// 支持 ES6
// import { create, Whatsapp } from 'sulla';
const sulla = require('sulla');

sulla.create().then((client) => start(client));

function start(client) {
  client.onMessage((message) => {
    if (message.body === 'Hi') {
      client.sendText(message.from, '👋 Hello from sulla!');
    }
  });
}

执行 create() 函数后，Sulla 将创建一个 WhatsApp Web 实例。如果您尚未登录，终端会显示一个二维码。使用手机扫描该二维码即可开始使用！

Sulla 会记住会话，因此无需每次都重新验证。

您可以通过向 create() 函数传递会话名称来同时创建多个会话：

// 初始化销售 WhatsApp 机器人
sulla.create('sales').then((salesClient) => {...});

// 初始化客服 WhatsApp 机器人
sulla.create('support').then((supportClient) => {...});

可选的 create 参数

Sulla 的 create() 方法第三个参数可以包含以下可选配置：

create('sessionName', qrCallback, {
  headless: true, // 无头模式
  devtools: false, // 默认不打开开发者工具
  useChrome: true, // 如果为 false，则使用 Chromium 实例
  debug: false, // 是否开启调试模式
  logQR: true // 自动在终端中记录二维码
  browserArgs: [''] // 要添加到 Chrome 浏览器实例中的参数
  refreshQR: 15000, // 每 15 秒刷新一次二维码，0 表示只加载一次，默认为 30 秒
});

类型定义可以在以下文件中找到：CreateConfig.ts

导出二维码

默认情况下，二维码会显示在终端中。如果您需要将二维码传递到其他地方，可以这样做：

const fs = require('fs');

// create() 的第二个参数是二维码回调函数
sulla.create('session-marketing', (base64Qr, asciiQR) => {
  // 在终端中记录二维码
  console.log(asciiQR);

  // 将其写入文件
  exportQR(base64Qr, 'marketing-qr.png');
});

// 将二维码写入指定路径
function exportQR(qrCode, path) {
  qrCode = qrCode.replace('data:image/png;base64,', '');
  const imageBuffer = Buffer.from(qrCode, 'base64');

  // 创建 'marketing-qr.png' 文件
  fs.writeFileSync(path, imageBuffer);
}

下载文件

Puppeteer 负责处理文件下载。解密过程尽可能快速（比原生方法更快）。支持大文件！

import fs = require('fs');
import mime = require('mime-types');

client.onMessage(async (message) => {
  if (message.isMedia) {
    const buffer = await client.downloadFile(message);
    // 此时您可以对缓冲区执行任何操作
    // 最常见的是将其写入文件
    const fileName = `some-file-name.${mime.extension(message.mimetype)}`;
    fs.writeFile(fileName, buffer, function (err) {
      ...
    });
  }
});

基本功能（用法）

并非所有可用功能都列在此处，如需更多信息，请参阅 这里 和 这里 中的所有可用函数。

聊天

在这里，chatId 可以是 <phoneNumber>@c.us 或 <phoneNumber>-<groupId>@c.us

// 发送基础文本
await client.sendText(chatId, '👋 Sulla 发来的问候！');

// 发送图片
await client.sendImage(
  chatId,
  'path/to/img.jpg',
  'image-name.jpg',
  '图片说明文字'
);

// 发送带 @ 标记的消息
await client.sendMentioned(chatId, '你好 @5218113130740 和 @5218243160777！', [
  '5218113130740',
  '5218243160777',
]);

// 回复消息
await client.reply(chatId, '这是一条回复！', message.id.toString());

// 发送文件（Sulla 会自动处理 MIME 类型，只需提供文件路径）
await client.sendFile(chatId, 'path/to/file.pdf', 'cv.pdf', '简历');

// 发送 GIF 动图
await client.sendVideoAsGif(
  chatId,
  'path/to/video.mp4',
  'video.gif',
  'GIF 图片文件'
);

// 发送联系人
// contactId: 52155334634@c.us
await client.sendContact(chatId, contactId);

// 转发消息
await client.forwardMessages(chatId, [message.id.toString()], true);

// 发送贴纸
await client.sendImageAsSticker(chatId, 'path/to/image.jpg');

// 发送位置信息
await client.sendLocation(
  chatId,
  25.6801987,
  -100.4060626,
  '华盛顿特区某地址',
  '副标题'
);

// 标记消息已读 ✔️✔️
await client.sendSeen(chatId);

// 开始输入...
await client.startTyping(chatId);

// 停止输入
await client.stopTyping(chatId);

// 设置聊天状态（0：正在输入，1：录制中，2：暂停）
await client.setChatState(chatId, 0 | 1 | 2);

数据获取

// 获取联系人列表
const contacts = await client.getAllContacts();

// 获取聊天中的所有消息
const allMessages = await client.loadAndGetAllMessagesInChat(chatId);

// 获取联系人状态
const status = await client.getStatus(contactId);

// 获取用户个人资料
const user = await client.getNumberProfile(contactId);

// 获取所有未读消息
const messages = await client.getAllUnreadMessages();

// 获取所有聊天
const chats = await client.getAllChats();

// 获取所有群组
const groups = await client.getAllGroups();

// 获取个人资料图片（作为 URL）
const url = await client.getProfilePicFromServer(chatId);

// 获取聊天/对话详情
const chat = await client.getChat(chatId);

群组功能

// groupId 或 chatId：leaveGroup 52123123-323235@g.us

// 退出群组
await client.leaveGroup(groupId);

// 获取群组成员
await client.getGroupMembers(groupId);

// 获取群组成员 ID
await client.getGroupMembersIds(groupId);

// 生成群组邀请链接
await client.getGroupInviteLink(groupId);

// 创建群组（名称、要添加的参与者）
await client.createGroup('群组名称', ['123123@c.us', '45456456@c.us']);

// 移除成员
await client.removeParticipant(groupId, '123123@c.us');

// 添加成员
await client.addParticipant(groupId, '123123@c.us');

// 提升成员权限（授予管理员权限）
await client.promoteParticipant(groupId, '123123@c.us');

// 降低成员权限（撤销管理员权限）
await client.demoteParticipant(groupId, '123123@c.us');

// 获取群组管理员
await client.getGroupAdmins(groupId);

个人资料功能

// 设置客户端状态
await client.setProfileStatus('度假中！✈️');

// 设置客户端昵称
await client.setProfileName('Sulla 机器人');

设备功能

// 获取设备信息
await client.getHostDevice();

// 获取连接状态
await client.getConnectionState();

// 获取电池电量
await client.getBatteryLevel();

// 检查是否已连接
await client.isConnected();

// 获取 WhatsApp Web 版本
await client.getWAVersion();

事件监听

// 监听消息
client.onMessage(message => {
  ...
})

// 监听状态变化
client.onStateChange(state => {
  ...
});

// 监听消息确认
client.onAck(ack => {
  ...
});

// 监听实时位置
// chatId：'phone@c.us'
client.onLiveLocation(chatId, (liveLocation) => {
  ...
});

// chatId 的格式为：'5518156745634-1516512045@g.us'
// 事件接口请参见：https://github.com/danielcardeenas/sulla/blob/master/src/api/model/participant-event.ts
client.onParticipantsChanged(chatId, (event) => {
  ...
});

// 监听客户端被加入群组的事件
client.onAddedToGroup(chatEvent => {
  ...
});

其他功能

// 删除聊天
await client.deleteChat(chatId);

// 清空聊天记录
await client.clearChat(chatId);

// 删除单条消息（最后一个参数表示仅在本地删除）
await client.deleteMessage(chatId, message.id.toString(), false);

// 获取号码个人资料 / 检查联系人是否为有效的 WhatsApp 号码
const profile = await client.getNumberProfile('0000000@c.us');

杂项

有一些技巧可以帮助更好地使用 Sulla。

保持会话活跃：

// 如果从 WhatsApp Web 登出
// 强制保持当前会话
// 状态变化
client.onStateChange((state) => {
  console.log(state);
  const conflits = [
    sulla.SocketState.CONFLICT,
    sulla.SocketState.UNPAIRED,
    sulla.SocketState.UNLAUNCHED,
  ];
  if (conflits.includes(state)) {
    client.useHere();
  }
});

向新联系人发送消息（未添加）

另请参阅 WhatsApp 链接。请注意，这可能会导致 WhatsApp 封禁账号，因此务必保持联系人列表的更新！

await client.sendMessageToId('5212234234@c.us', 'Sulla 发来的问候！👋');

多个会话

如果需要同时运行多个会话，只需在 create() 方法中传入会话名称即可。

async () => {
  const marketingClient = await sulla.create('marketing');
  const salesClient = await sulla.create('sales');
  const supportClient = await sulla.create('support');
};

正确关闭（保存）会话

正确关闭会话以确保下次登录时会话能够被保存（这样就不需要再次扫描二维码）。因此，不要直接按 CTRL+C，

// 捕获 CTRL+C
process.on('SIGINT', function() {
  client.close();
});

// 使用 try-catch 关闭
try {
   ...
} catch (error) {
   client.close();
}

调试

开发

构建 Sulla 非常简单，尽管它内部包含三个主要项目：

1. Wapi 项目

> npm run build:wapi

2. 中间件

> npm run build:build:middleware
> npm run build:jsQR

3. Sulla

> npm run build:sulla

要构建整个项目，只需运行：

> npm run build

维护者

我们需要更多的维护者，我一个人无法跟上所有的更新。如果您感兴趣，请提交一个 Pull Request。

贡献

欢迎提交 Pull Request。对于重大更改，请先打开一个议题讨论您想要进行的修改。

Sulla 快速上手指南

环境准备

• 系统要求：Node.js v12 或更高版本
• 前置依赖：已安装 Node.js 和 npm（无需额外安装 Chrome，puppeteer 会自动处理）

安装步骤

使用 npm 安装 Sulla（推荐使用淘宝镜像加速）：

npm install sulla --save -registry=https://registry.npmmirror.com

基本使用

以下是最简示例，实现自动回复 "Hi" 消息：

const sulla = require('sulla');

sulla.create().then((client) => {
  client.onMessage((message) => {
    if (message.body === 'Hi') {
      client.sendText(message.from, '👋 Hello from sulla!');
    }
  });
});

执行脚本后：

1. 终端将显示 WhatsApp 登录二维码
2. 用手机扫描二维码完成登录
3. 会话自动保存，无需重复登录
4. 当收到 "Hi" 消息时，自动回复 "👋 Hello from sulla!"