Back to Details

evolution-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Evolution API

Evolution API

Open-source WhatsApp integration API supporting Baileys (WhatsApp Web) and official WhatsApp Business API (Cloud API). Built with Node.js + TypeScript + Express.js + Prisma.
开源WhatsApp集成API，支持Baileys（WhatsApp Web）和官方WhatsApp Business API（Cloud API）。基于Node.js + TypeScript + Express.js + Prisma构建。

Authentication

身份验证

All requests use the 
apikey
header. Two levels of keys exist:
  • Global API Key: Set via 
    AUTHENTICATION_API_KEY
    env var. Has full access to all instances.
  • Instance Token: Per-instance key returned on creation. Scoped to that instance only.
apikey: YOUR_API_KEY
Every request follows this pattern:
bash
curl --request <METHOD> \
  --url https://<SERVER_URL>/<path>/{instanceName} \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --data '<json-body>'
所有请求都使用
apikey
请求头，分为两种密钥等级：
  • 全局API密钥：通过
    AUTHENTICATION_API_KEY
    环境变量设置，拥有所有实例的完整访问权限。
  • 实例令牌：创建实例时返回的单实例专属密钥，仅作用于该实例。
apikey: YOUR_API_KEY
所有请求遵循以下格式：
bash
curl --request <METHOD> \
  --url https://<SERVER_URL>/<path>/{instanceName} \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --data '<json-body>'

Instance Lifecycle

实例生命周期

Create Instance

创建实例

bash
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"]
  }
}
Response (201):
json
{
  "instance": {
    "instanceName": "my-instance",
    "instanceId": "af6c5b7c-ee27-4f94-9ea8-192393746ddd",
    "status": "created"
  },
  "hash": { "apikey": "generated-instance-token" },
  "qrcode": { "base64": "data:image/png;base64,..." }
}
The 
integration
field accepts:
  • WHATSAPP-BAILEYS
    — Free, based on WhatsApp Web (Baileys library)
  • WHATSAPP-BUSINESS
    — Official Meta Cloud API (requires Facebook App setup)
bash
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）：
json
{
  "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应用）

Connect Instance (get QR code)

连接实例（获取二维码）

GET /instance/connect/{instanceName}
Returns QR code as base64 for scanning with WhatsApp mobile app.
GET /instance/connect/{instanceName}
返回base64格式的二维码，可使用WhatsApp移动端扫描登录。

Check Connection State

检查连接状态

GET /instance/connectionState/{instanceName}
Returns: 
open
, 
close
, or 
connecting
.
GET /instance/connectionState/{instanceName}
返回值：
open
（已连接）、
close
（未连接）或
connecting
（连接中）。

Other Instance Operations

其他实例操作

MethodEndpointDescription
GET
/instance/fetchInstances
List all instances
PUT
/instance/restart/{instance}
Restart instance
DELETE
/instance/logout/{instance}
Logout (keep instance)
DELETE
/instance/delete/{instance}
Delete instance entirely
POST
/instance/setPresence/{instance}
Set online/offline status
请求方法端点描述
GET
/instance/fetchInstances
列出所有实例
PUT
/instance/restart/{instance}
重启实例
DELETE
/instance/logout/{instance}
退出登录（保留实例）
DELETE
/instance/delete/{instance}
彻底删除实例
POST
/instance/setPresence/{instance}
设置在线/离线状态

Sending Messages

消息发送

Text Message

文本消息

bash
POST /message/sendText/{instanceName}

{
  "number": "5511999999999",
  "text": "Hello from Evolution API!",
  "delay": 1200,
  "linkPreview": true,
  "mentionsEveryOne": false,
  "mentioned": ["5511888888888@s.whatsapp.net"]
}
Response (201):
json
{
  "key": {
    "remoteJid": "5511999999999@s.whatsapp.net",
    "fromMe": true,
    "id": "BAE594145F4C59B4"
  },
  "message": { "extendedTextMessage": { "text": "Hello from Evolution API!" } },
  "messageTimestamp": "1717689097",
  "status": "PENDING"
}
Number format: Use full international format without 
+
sign. For groups, use the group JID (e.g., 
120363025486748009@g.us
).
bash
POST /message/sendText/{instanceName}

{
  "number": "5511999999999",
  "text": "Hello from Evolution API!",
  "delay": 1200,
  "linkPreview": true,
  "mentionsEveryOne": false,
  "mentioned": ["5511888888888@s.whatsapp.net"]
}
响应（201）：
json
{
  "key": {
    "remoteJid": "5511999999999@s.whatsapp.net",
    "fromMe": true,
    "id": "BAE594145F4C59B4"
  },
  "message": { "extendedTextMessage": { "text": "Hello from Evolution API!" } },
  "messageTimestamp": "1717689097",
  "status": "PENDING"
}
号码格式：使用不带
+
号的完整国际格式。群组请使用群组JID（例如：
120363025486748009@g.us
）。

Reply / Quote a Message

回复/引用消息

Add 
quoted
to any send payload:
json
{
  "number": "5511999999999",
  "text": "This is a reply",
  "quoted": {
    "key": { "id": "ORIGINAL_MESSAGE_ID" },
    "message": { "conversation": "Original message text" }
  }
}
在任意发送请求的payload中添加
quoted
字段即可：
json
{
  "number": "5511999999999",
  "text": "This is a reply",
  "quoted": {
    "key": { "id": "ORIGINAL_MESSAGE_ID" },
    "message": { "conversation": "Original message text" }
  }
}

Media Message

媒体消息

bash
POST /message/sendMedia/{instanceName}

{
  "number": "5511999999999",
  "mediatype": "image",
  "mimetype": "image/png",
  "caption": "Check this out",
  "media": "https://example.com/image.png"
}
mediatype
options: 
image
, 
video
, 
document
. 
media
accepts a URL or base64-encoded string.
bash
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编码字符串。

Audio Message

音频消息

bash
POST /message/sendWhatsAppAudio/{instanceName}

{
  "number": "5511999999999",
  "audio": "https://example.com/audio.mp3"
}
Audio is automatically converted to WhatsApp PTT (push-to-talk) format.
bash
POST /message/sendWhatsAppAudio/{instanceName}

{
  "number": "5511999999999",
  "audio": "https://example.com/audio.mp3"
}
音频会自动转换为WhatsApp PTT（一键对讲）格式。

Other Message Types

其他消息类型

EndpointBody fieldsNotes
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
Use empty string to remove
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 or base64)
POST /message/sendStatus/{instance}
type
, 
content
, 
statusJidList[]
, 
caption
Post to WhatsApp Status
端点请求体字段备注
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 Configuration

Webhook配置

Set Webhook via API

通过API设置Webhook

bash
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"
    ]
  }
}
When 
webhookByEvents
is 
true
, events are sent to 
{url}/{EVENT_NAME}
(e.g., 
/webhook/MESSAGES_UPSERT
).
bash
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
）。

Get Webhook Config

获取Webhook配置

GET /webhook/find/{instanceName}
For the complete list of available events, see references/events.md.
GET /webhook/find/{instanceName}
完整的可用事件列表请参考 references/events.md。

Chat Operations

聊天操作

MethodEndpointBodyDescription
POST
/chat/checkIsWhatsApp/{instance}
numbers: ["5511..."]
Verify numbers on WhatsApp
POST
/chat/findMessages/{instance}
where: {key: {remoteJid}}
Search messages
POST
/chat/findChats/{instance}
{}
List all chats
POST
/chat/findContacts/{instance}
where: {id}
Search contacts
POST
/chat/markMessageAsRead/{instance}
readMessages: [{remoteJid, id}]
Mark as read
POST
/chat/archiveChat/{instance}
chat, archive: true
Archive/unarchive chat
DELETE
/chat/deleteMessageForEveryone/{instance}
key: {remoteJid, fromMe, id}
Delete for everyone
POST
/chat/updateMessage/{instance}
number, text, key: {id}
Edit sent message
POST
/chat/sendPresence/{instance}
number, presence
Show typing/recording
POST
/chat/getBase64/{instance}
message: {key}
Get media as base64
presence
values: 
composing
, 
recording
, 
paused
.
请求方法端点请求体描述
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
（已暂停）。

Group Management

群组管理

MethodEndpointBody / ParamsDescription
POST
/group/create/{instance}
subject, participants[]
Create group
GET
/group/fetchAllGroups/{instance}
query: 
getParticipants=true
List all groups
GET
/group/findGroupInfos/{instance}?groupJid=
query paramGroup details
GET
/group/inviteCode/{instance}?groupJid=
query paramGet invite link
GET
/group/participants/{instance}?groupJid=
query paramList members
POST
/group/updateParticipant/{instance}
groupJid, action, participants[]
Add/remove/promote/demote
POST
/group/updateSetting/{instance}
groupJid, action
Lock/unlock group settings
POST
/group/toggleEphemeral/{instance}
groupJid, expiration
Set disappearing messages
DELETE
/group/leaveGroup/{instance}
groupJid
Leave group
action
for participants: 
add
, 
remove
, 
promote
, 
demote
.
请求方法端点请求体/参数描述
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
设置 disappearing messages（消失消息）
DELETE
/group/leaveGroup/{instance}
groupJid
退出群组
群成员操作的
action
可选值：
add
（添加）、
remove
（移除）、
promote
（提升为管理员）、
demote
（降级为普通成员）。

Profile Settings

个人资料设置

MethodEndpointDescription
POST
/profile/fetchProfile/{instance}
Fetch profile info
POST
/profile/updateProfileName/{instance}
Update display name
POST
/profile/updateProfileStatus/{instance}
Update status text
POST
/profile/updateProfilePicture/{instance}
Update avatar
DELETE
/profile/removeProfilePicture/{instance}
Remove avatar
GET
/profile/fetchPrivacySettings/{instance}
Get privacy settings
POST
/profile/updatePrivacySettings/{instance}
Update privacy
请求方法端点描述
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}
更新隐私设置

Integrations

集成能力

Evolution API supports chatbot integrations configured per-instance:
IntegrationEndpoints prefixDescription
Typebot
/typebot/
Conversational bot flows
Chatwoot
/chatwoot/
Help desk / CRM
OpenAI
/openai/
AI-powered bots + audio transcription
Dify
/dify/
AI agent platform
n8n
/n8n/
Workflow automation
Flowise
/flowise/
LLM flow builder
EvoAI
/evoai/
Evolution's own AI bot
Each integration follows the CRUD pattern: 
create
, 
find
, 
update
, 
delete
, 
settings
, 
change-status
, 
fetch-session
.
Evolution API支持按实例配置聊天机器人集成：
集成工具端点前缀描述
Typebot
/typebot/
对话式机器人流程
Chatwoot
/chatwoot/
服务台/CRM
OpenAI
/openai/
AI驱动的机器人+音频转写
Dify
/dify/
AI Agent平台
n8n
/n8n/
工作流自动化
Flowise
/flowise/
LLM流程构建器
EvoAI
/evoai/
Evolution自带的AI机器人
每个集成都遵循CRUD模式：
create
（创建）、
find
（查询）、
update
（更新）、
delete
（删除）、
settings
（设置）、
change-status
（修改状态）、
fetch-session
（获取会话）。

Event Delivery Channels

事件投递渠道

Beyond webhooks, Evolution API can deliver events via:
  • RabbitMQ — 
    POST /rabbitmq/set/{instance}
  • Amazon SQS — 
    POST /sqs/set/{instance}
  • WebSocket (Socket.io) — 
    POST /websocket/set/{instance}
  • Apache Kafka — Via environment variables
除了Webhook外，Evolution API还支持通过以下渠道投递事件：
  • RabbitMQ — 
    POST /rabbitmq/set/{instance}
  • Amazon SQS — 
    POST /sqs/set/{instance}
  • WebSocket (Socket.io) — 
    POST /websocket/set/{instance}
  • Apache Kafka — 通过环境变量配置

Advanced References

高级参考

  • Full endpoint table: See references/api-endpoints.md
  • Environment variables (self-hosted): See references/environment-variables.md
  • Webhook events catalog: See references/events.md
  • 完整端点列表：参考 references/api-endpoints.md
  • 环境变量（自托管场景）：参考 references/environment-variables.md
  • Webhook事件目录：参考 references/events.md