clairton/unoapi-cloud

Unoapi Cloud

镜像概述和主要用途

Unoapi Cloud是基于Baileys（https://github.com/WhiskeySockets/Baileys）实现的RESTful API服务，支持多设备连接，兼容*** Cloud API格式（https://developers.facebook.com/docs/whatsapp/cloud-api）。该服务可将媒体文件存储在文件系统（data目录）、S3兼容存储或Redis中，提供消息收发、状态管理、联系人验证等功能，适用于构建基于的自动化消息系统、客户服务平台等应用。

核心功能和特性

• 多设备支持：同时管理多个***设备连接
• API兼容性：遵循*** Cloud API格式，降低集成成本
• 媒体存储灵活：支持文件系统、S3兼容存储或Redis存储媒体文件
• QR码管理：通过HTTP端点或WebSocket获取QR码进行设备认证
• Webhook集成：支持事件推送，包含消息收发、状态更新等事件
• 消息类型丰富：支持文本、联系人、媒体（图片、音频等）等多种消息类型
• 配置灵活：通过环境变量或Redis进行详细配置，支持按会话自定义

使用场景和适用范围

• 构建***客户服务机器人
• 实现企业级消息通知系统
• 集成CRM或客服平台（如Chatwoot）
• 开发自动化消息收发应用
• 多设备***账号统一管理

使用方法和配置说明

读取QR码或配置会话

1. 访问 http://localhost:9876/session/XXX（XXX为手机号，如http://localhost:9876/session/5549988290955）
2. 断开连接时，页面显示QR码，扫描后获取认证令牌并保存
3. 已连接状态下，显示Redis中保存的号码配置，可使用认证令牌更新配置

QR码也会发送到配置的Webhook，可在Chatwoot等收件箱中查看。

通过WebSocket获取QR码

使用 /ws 端点并监听 broadcast 事件，qrcode 类型事件的 content 属性包含QR码的base64 URL：

js
import { io } from 'socket.io-client';
const socket = io('http://localhost:9876/ws', { path: '/ws' });
socket.on('broadcast', data => {
  console.log('broadcast', data);
});

发送消息

消息 payload 基于*** Cloud API格式，支持多种消息类型：

发送文本消息

sh
curl -i -X POST \
http://localhost:9876/v15.0/554931978550/messages \
-H 'Content-Type: application/json' \
-H 'Authorization: 1' \
-d '{
  "messaging_product": "whatsapp",
  "to": "5549988290955",
  "type": "text",
  "text": {
    "body": "hello"
  } 
}'

发送联系人

sh
curl -i -X POST \
http://localhost:9876/v15.0/5549988290955/messages \
-H 'Content-Type: application/json' \
-H 'Authorization: 1' \
-d '{
  "messaging_product": "whatsapp",
  "to": "5549999621461",
  "type": "contacts",
  "contacts": [
    {
      "name": {
        "formatted_name": "Clairton - Faça um pix nessa chave e contribua com a unoapi"
      },
      "phones": [
        {
          "wa_id": "554988290955",
          "phone": "+5549988290955"
        }
      ]
    }
  ]
}'

发送群组消息

sh
curl -i -X POST \
http://localhost:9876/v15.0/5549988290955/messages \
-H 'Content-Type: application/json' \
-d '{
  "messaging_product": "whatsapp",
  "to": "120363040468224422@g.us",
  "type": "text",
  "text": {
    "body": "hello"
  }
}'

标记消息为已读

sh
curl -i -X POST \
http://localhost:9876/v15.0/5549988290955/messages \
-H 'Content-Type: application/json' \
-H 'Authorization: 1' \
-d '{
  "messaging_product": "whatsapp",
  "status": "read",
  "message_id": "MESSAGE_ID"
}'

媒体文件处理

获取媒体文件

sh
curl -i -X GET \
http://localhost:9876/v15.0/5549988290955/3EB005A626251D50D4E4 \
-H 'Content-Type: application/json'

返回的URL可用于下载媒体：

sh
curl -i -X GET \
http://locahost:9876/download/v13/5549988290955/5549988290955@s.whatsapp.net/48e6bcd09a9111eda528c117789f8b62.png \
-H 'Content-Type: application/json'

发送媒体文件

sh
curl -i -X POST \
http://localhost:9876/v15.0/5549988290955/messages \
-H 'Content-Type: application/json' \
-d '{
  "messaging_product": "whatsapp",
  "to": "5549988290955",
  "type": "image",
  "image": {
    "link" : "https://github.githubassets.com/favicons/favicon-dark.png"
  }
}'

Webhook事件

Webhook事件格式兼容*** Cloud API，并扩展了群组相关字段（group_id、group_subject、group_picture）和个人资料图片字段（picture）：

json
{
  "object": "whatsapp_business_account",
  "entry": [{
      "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
      "changes": [{
          "value": {
              "messaging_product": "whatsapp",
              "metadata": {
                  "display_phone_number": PHONE_NUMBER,
                  "phone_number_id": PHONE_NUMBER_ID
              },
              "contacts": [{
                  "profile": {
                    "name": "NAME",
                    "picture": "图片URL" // WhatsApp Cloud API扩展字段
                  },
                  "group_id": "123345@g.us", // 群组ID，扩展字段
                  "group_subject": "Awesome Group", // 群组名称，扩展字段
                  "group_picture": "图片URL", // 群组头像，扩展字段
                  "wa_id": PHONE_NUMBER
                }],
              "messages": [{
                  "from": PHONE_NUMBER,
                  "id": "wamid.ID",
                  "timestamp": TIMESTAMP,
                  "text": {
                    "body": "MESSAGE_BODY"
                  },
                  "type": "text"
                }]
          },
          "field": "messages"
        }]
  }]
}

错误消息

自定义错误码（基于*** Cloud API错误码扩展）：

• 1: 未知错误，请查看日志获取详情
• 2: 接收方无***账号
• 3: 号码已断开连接，请扫描QR码重新连接
• 4: 未知的Baileys状态
• 5: 连接中，请稍候
• 6: QR码生成次数达到上限
• 7: 无效的电话号码
• 8: 消息不允许发送
• 9: 连接丢失
• 10: 无效的令牌值
• 11: 媒体链接HTTP Head请求失败
• 12: 会话离线，正在连接...
• 14: 会话待命，等待配置的时间
• 15: 会话已重载，请重新发送消息连接

验证联系人是否有***账号

仅在yarn standalone模式下可用：

sh
curl -i -X POST \
http://localhost:9876/5549988290955/contacts \
-H 'Content-Type: application/json' \
-H 'Authorization: 1' \
-d '{
  "blocking": "no_wait",
  "contacts": [
  	"16315551000"
  ],
  "force_check": true
}'

返回结果：

json
{
  "contacts": [ 
    {
      "wa_id": "16315551000",
      "input": "16315551000",
      "status": "valid"
    }
  ]
}

Docker部署示例

开发环境部署

yaml
# docker-compose.yml
version: '3'

services:
  app:
    image: clairton/unoapi-cloud:latest
    volumes:
      - ./data:/home/u/app/data
    ports:
      - 9876:9876
    environment:
      - NODE_ENV=development
    deploy:
      restart_policy:
        condition: on-failure

启动命令：docker compose up，访问http://localhost:9876/ping验证服务是否正常运行（返回"pong!"）。

生产环境部署

yaml
# docker-compose.yml
version: '3'

services:
  app:
    image: clairton/unoapi-cloud:latest
    volumes:
      - ./data:/home/u/app/data
    ports:
      - 9876:9876
    deploy:
      restart_policy:
        condition: on-failure

启动命令：docker compose up。

启动选项

• yarn start: 启动单服务器，会话和媒体文件存储在文件系统
• yarn cloud: 启动单服务器，消息存储在Redis和RabbitMQ
• yarn web 和 yarn worker: 启动Web和Worker服务，使用Redis和RabbitMQ
• yarn standalone: 根据环境变量选择存储方式（Redis/S3/文件系统）
• yarn waker: 将死信队列中的消息移回处理队列重试

配置选项

环境变量配置

创建.env文件自定义配置（默认值如无说明则为默认配置）：

通用环境变量

env
CONSUMER_TIMEOUT_MS=30000 # 任务消费超时时间（毫秒）
AVAILABLE_LOCALES=["en", "pt_BR", "pt"] # 支持的语言
DEFAULT_LOCALE=en # 默认语言
ONLY_HELLO_TEMPLATE=false # 是否仅启用hello模板
MAX_CONNECT_RETRY=3 # 最大连接重试次数
MAX_CONNECT_TIME=3000 # 最大连接时间间隔（毫秒）
CONNECTION_TYPE=qrcode # 连接类型（qrcode/pairing_code）
QR_TIMEOUT_MS=60000 # QR码超时时间（毫秒）
WEBHOOK_SESSION= # 接收状态和QR码事件的Webhook
BASE_URL= # 媒体下载基础URL
PORT=9876 # HTTP端口
BASE_STORE=./data # 数据存储目录
LOG_LEVEL=warn # 日志级别
UNO_LOG_LEVEL= # Unoapi日志级别（默认同LOG_LEVEL）
UNOAPI_RETRY_REQUEST_DELAY_MS=1000 # 解密失败重试延迟（毫秒）
UNOAPI_DELAY_AFTER_FIRST_MESSAGE_MS=0 # 首条消息后延迟（毫秒）
UNOAPI_DELAY_AFTER_FIRST_MESSAGE_WEBHOOK_MS=0 # 首条消息Webhook后延迟（毫秒）
UNOAPI_DELAY_BETWEEN_MESSAGES_MS=0 # 消息间延迟（毫秒）
CLEAN_CONFIG_ON_DISCONNECT=false # 断开连接时清理Redis配置
CONFIG_SESSION_PHONE_CLIENT=Unoapi # 客户端名称
CONFIG_SESSION_PHONE_NAME=Chrome # 浏览器名称
WHATSAPP_VERSION= # WhatsApp版本（默认使用Baileys版本）
VALIDATE_SESSION_NUMBER=true # 验证会话号码是否匹配
OPENAI_API_KEY= # OpenAI API密钥（用于音频转文字）

S3兼容存储配置

env
STORAGE_BUCKET_NAME= # 存储桶名称
STORAGE_ACCESS_KEY_ID= # 访问密钥
STORAGE_SECRET_ACCESS_KEY= # 密钥
STORAGE_REGION= # 区域
STORAGE_ENDPOINT= # 端点URL
STORAGE_FORCE_PATH_STYLE= # 是否强制路径样式
STORAGE_TIMEOUT_MS= # 超时时间（毫秒）

Redis和消息队列配置

env
AMQP_URL= # RabbitMQ连接URL
REDIS_URL= # Redis连接URL

会话相关环境变量（可按会话配置）

env
WEBHOOK_URL_ABSOLUTE= # Webhook完整URL
WEBHOOK_URL= # Webhook URL（自动追加电话号码）
WEBHOOK_TOKEN= # Webhook令牌
WEBHOOK_HEADER= # Webhook令牌头名称
WEBHOOK_TIMEOUT_MS=5000 # Webhook超时时间（毫秒）
WEBHOOK_SEND_NEW_MESSAGES=false # 是否发送新消息到Webhook
WEBHOOK_SEND_GROUP_MESSAGES=true # 是否发送群组消息到Webhook
WEBHOOK_SEND_OUTGOING_MESSAGES=true # 是否发送 outgoing消息到Webhook
WEBHOOK_SEND_INCOMING_MESSAGES=true # 是否发送 incoming消息到Webhook
WEBHOOK_SEND_TRANSCRIBE_AUDIO=false # 是否发送音频转文字结果
WEBHOOK_SEND_UPDATE_MESSAGES=true # 是否发送消息状态更新
IGNORE_GROUP_MESSAGES=true # 是否忽略群组消息
IGNORE_BROADCAST_STATUSES=true # 是否忽略广播状态
IGNORE_NEWSLETTER_MESSAGES=false # 是否忽略新闻通讯消息
IGNORE_STATUS_MESSAGE=true # 是否忽略状态消息
READ_ON_RECEIPT=false # 是否接收后标记为已读
IGNORE_BROADCAST_MESSAGES=false # 是否忽略广播消息
IGNORE_HISTORY_MESSAGES=true # 是否忽略历史消息
IGNORE_OWN_MESSAGES=true # 是否忽略自己的消息
IGNORE_YOURSELF_MESSAGES=true # 是否忽略发给自己的消息
COMPOSING_MESSAGE=false # 是否在发送前显示"正在输入"
REJECT_CALLS= # 拒接电话时发送的消息
REJECT_CALLS_WEBHOOK= # 拒接电话时发送到Webhook的消息（已弃用）
MESSAGE_CALLS_WEBHOOK= # 接收到电话时发送到Webhook的消息
SEND_CONNECTION_STATUS=true # 是否发送连接状态到Webhook
IGNORE_DATA_STORE= # 是否忽略数据存储
AUTO_CONNECT=true # 是否自动连接
AUTO_RESTART_MS=0 # 自动重启间隔（毫秒，0为不自动重启）
THROW_WEBHOOK_ERROR=false # Webhook错误是否抛出异常
NOTIFY_FAILED_MESSAGES=true # 消息失败时通知自己
SEND_REACTION_AS_REPLY=false # 是否将反应作为回复发送
SEND_PROFILE_PICTURE=true # 是否发送个人资料图片
PROXY_URL= # SOCKS代理URL
WEBHOOK_FORWARD_PHONE_NUMBER_ID= # 转发到WhatsApp Cloud API的号码ID
WEBHOOK_FORWARD_BUSINESS_ACCOUNT_ID= # 转发的商业账户ID
WEBHOOK_FORWARD_TOKEN= # 转发的令牌
WEBHOOK_FORWARD_VERSION=v17.0 # 转发的API版本
WEBHOOK_FORWARD_URL=https://graph.facebook.com # 转发的API URL
WEBHOOK_FORWARD_TIMEOUT_MS=360000 # 转发超时时间（毫秒）

Redis会话配置

按会话存储配置（键格式：unoapi-config:PHONE_NUMBER）：

json
{
  "authToken": "令牌",
  "rejectCalls": "拒接电话消息",
  "ignoreGroupMessages": true,
  "ignoreBroadcastStatuses": true,
  "ignoreBroadcastMessages": false,
  "ignoreHistoryMessages": true,
  "ignoreOwnMessages": true,
  "ignoreYourselfMessages": true,
  "sendConnectionStatus": true,
  "composingMessage": false,
  "sessionWebhook": "",
  "autoConnect": false,
  "autoRestartMs": 3600000,
  "retryRequestDelayMs": 1000,
  "throwWebhookError": false,
  "webhooks": [
    {
      "url": "http://localhost:3000/***/webhook",
      "token