evolution-api

Evolution API

开源的 WhatsApp 集成 API，支持 Baileys（WhatsApp Web）和官方 WhatsApp Business API（Cloud API）。基于 Node.js + TypeScript + Express.js + Prisma 构建。

身份验证

所有请求都使用 apikey 标头。密钥分为两个级别：

• 全局 API 密钥：通过 AUTHENTICATION_API_KEY 环境变量设置。可完全访问所有实例。
• 实例令牌：创建实例时返回的实例专属密钥。仅限访问对应实例。

apikey: YOUR_API_KEY

所有请求都遵循以下模式：

curl --request <METHOD> \
  --url https://<SERVER_URL>/<path>/{instanceName} \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --data '<json-body>'

实例生命周期

创建实例

POST /instance/create

{
  "instanceName": "my-instance",
  "integration": "WHATSAPP-BAILEYS",
  "token": "optional-custom-token",
  "qrcode": true,
  "number": "5511999999999",
  "rejectCall": true,
  "msgCall": "I can't answer calls",
  "groupsIgnore": true,
  "alwaysOnline": true,
  "readMessages": true,
  "readStatus": true,
  "syncFullHistory": true,
  "webhook": {
    "url": "https://your-server.com/webhook",
    "byEvents": false,
    "base64": true,
    "headers": { "authorization": "Bearer token" },
    "events": ["MESSAGES_UPSERT", "CONNECTION_UPDATE"]
  }
}

响应（201）：

{
  "instance": {
    "instanceName": "my-instance",
    "instanceId": "af6c5b7c-ee27-4f94-9ea8-192393746ddd",
    "status": "created"
  },
  "hash": { "apikey": "generated-instance-token" },
  "qrcode": { "base64": "data:image/png;base64,..." }
}

integration 字段接受以下值：

• WHATSAPP-BAILEYS — 免费，基于 WhatsApp Web（Baileys 库）
• WHATSAPP-BUSINESS — 官方 Meta Cloud API（需要设置 Facebook App）

连接实例（获取 QR 码）

GET /instance/connect/{instanceName}

返回 base64 格式的 QR 码，可使用 WhatsApp 移动应用扫描。

检查连接状态

GET /instance/connectionState/{instanceName}

返回：open、close 或 connecting。

其他实例操作

方法	端点	说明
GET	/instance/fetchInstances	列出所有实例
PUT	/instance/restart/{instance}	重启实例
DELETE	/instance/logout/{instance}	登出（保留实例）
DELETE	/instance/delete/{instance}	完全删除实例
POST	/instance/setPresence/{instance}	设置在线／离线状态

发送消息

文本消息

POST /message/sendText/{instanceName}

{
  "number": "5511999999999",
  "text": "Hello from Evolution API!",
  "delay": 1200,
  "linkPreview": true,
  "mentionsEveryOne": false,
  "mentioned": ["[email protected]"]
}

响应（201）：

{
  "key": {
    "remoteJid": "[email protected]",
    "fromMe": true,
    "id": "BAE594145F4C59B4"
  },
  "message": { "extendedTextMessage": { "text": "Hello from Evolution API!" } },
  "messageTimestamp": "1717689097",
  "status": "PENDING"
}

号码格式：使用完整的国际格式，不带 + 号。对于群组，请使用群组 JID（例如，[email protected]）。

回复／引用消息

在任意发送请求负载中添加 quoted：

{
  "number": "5511999999999",
  "text": "This is a reply",
  "quoted": {
    "key": { "id": "ORIGINAL_MESSAGE_ID" },
    "message": { "conversation": "Original message text" }
  }
}

媒体消息

POST /message/sendMedia/{instanceName}

{
  "number": "5511999999999",
  "mediatype": "image",
  "mimetype": "image/png",
  "caption": "Check this out",
  "media": "https://example.com/image.png"
}

mediatype 可选值：image、video、document。 media 接受 URL 或 base64 编码的字符串。

音频消息

POST /message/sendWhatsAppAudio/{instanceName}

{
  "number": "5511999999999",
  "audio": "https://example.com/audio.mp3"
}

音频会自动转换为 WhatsApp PTT（按键通话）格式。

其他消息类型

端点	请求体字段	备注
POST /message/sendLocation/{instance}	number、latitude、longitude、name、address
POST /message/sendContact/{instance}	number、contact: [{fullName, wuid, phoneNumber}]
POST /message/sendReaction/{instance}	key: {remoteJid, fromMe, id}、reaction	使用空字符串移除
POST /message/sendPoll/{instance}	number、name、values[]、selectableCount
POST /message/sendList/{instance}	number、title、description、buttonText、footerText、sections[]
POST /message/sendButtons/{instance}	number、title、description、buttons[]、footer
POST /message/sendSticker/{instance}	number、sticker（URL 或 base64）
POST /message/sendStatus/{instance}	type、content、statusJidList[]、caption	发布到 WhatsApp 状态

Webhook 配置

通过 API 设置 Webhook

POST /webhook/set/{instanceName}

{
  "webhook": {
    "enabled": true,
    "url": "https://your-server.com/webhook",
    "webhookByEvents": false,
    "webhookBase64": true,
    "events": [
      "MESSAGES_UPSERT",
      "MESSAGES_UPDATE",
      "CONNECTION_UPDATE",
      "SEND_MESSAGE"
    ]
  }
}

当 webhookByEvents 为 true 时，事件会发送到 {url}/{EVENT_NAME}（例如，/webhook/MESSAGES_UPSERT）。

获取 Webhook 配置

GET /webhook/find/{instanceName}

完整的可用事件列表请参阅 references/events.md。

聊天操作

方法	端点	请求体	说明
POST	/chat/checkIsWhatsApp/{instance}	numbers: ["5511..."]	验证号码是否在 WhatsApp 上
POST	/chat/findMessages/{instance}	where: {key: {remoteJid}}	搜索消息
POST	/chat/findChats/{instance}	{}	列出所有聊天
POST	/chat/findContacts/{instance}	where: {id}	搜索联系人
POST	/chat/markMessageAsRead/{instance}	readMessages: [{remoteJid, id}]	标记为已读
POST	/chat/archiveChat/{instance}	chat, archive: true	归档/取消归档聊天
DELETE	/chat/deleteMessageForEveryone/{instance}	key: {remoteJid, fromMe, id}	为所有人删除
POST	/chat/updateMessage/{instance}	number, text, key: {id}	编辑已发送的消息
POST	/chat/sendPresence/{instance}	number, presence	显示正在输入/录音
POST	/chat/getBase64/{instance}	message: {key}	获取 Base64 格式的媒体

presence 的取值：composing、recording、paused。

群组管理

方法	端点	请求体/参数	说明
POST	/group/create/{instance}	subject, participants[]	创建群组
GET	/group/fetchAllGroups/{instance}	查询参数：getParticipants=true	列出所有群组
GET	/group/findGroupInfos/{instance}?groupJid=	查询参数	群组详情
GET	/group/inviteCode/{instance}?groupJid=	查询参数	获取邀请链接
GET	/group/participants/{instance}?groupJid=	查询参数	列出成员
POST	/group/updateParticipant/{instance}	groupJid, action, participants[]	添加/移除/提升/降级成员
POST	/group/updateSetting/{instance}	groupJid, action	锁定/解锁群组设置
POST	/group/toggleEphemeral/{instance}	groupJid, expiration	设置消息自动消失
DELETE	/group/leaveGroup/{instance}	groupJid	退出群组

action 的成员操作取值：add、remove、promote、demote。

个人资料设置

方法	端点	说明
POST	/profile/fetchProfile/{instance}	获取个人资料信息
POST	/profile/updateProfileName/{instance}	更新显示名称
POST	/profile/updateProfileStatus/{instance}	更新状态文本
POST	/profile/updateProfilePicture/{instance}	更新头像
DELETE	/profile/removeProfilePicture/{instance}	移除头像
GET	/profile/fetchPrivacySettings/{instance}	获取隐私设置
POST	/profile/updatePrivacySettings/{instance}	更新隐私设置

集成

Evolution API 支持按实例配置聊天机器人集成：

集成	端点前缀	描述
Typebot	/typebot/	对话式机器人流程
Chatwoot	/chatwoot/	服务台 / CRM
OpenAI	/openai/	AI 驱动的机器人 + 音频转录
Dify	/dify/	AI Agent 平台
n8n	/n8n/	工作流自动化
Flowise	/flowise/	大模型流程构建器
EvoAI	/evoai/	Evolution 自有的 AI 机器人

每种集成都遵循 CRUD 模式：create、find、update、delete、settings、change-status、fetch-session。

事件传递渠道

除了 Webhook，Evolution API 还可以通过以下渠道传递事件：

• RabbitMQ — POST /rabbitmq/set/{instance}
• Amazon SQS — POST /sqs/set/{instance}
• WebSocket (Socket.io) — POST /websocket/set/{instance}
• Apache Kafka — 通过环境变量

高级参考

• 完整端点表：参见 references/api-endpoints.md
• 环境变量（可自托管）：参见 references/environment-variables.md
• Webhook 事件目录：参见 references/events.md