evolution-api

name

evolution-api

description

Evolution API integration for WhatsApp messaging, instance management, webhooks, and chatbot orchestration. Use when: (1) Creating or managing WhatsApp instances via Evolution API, (2) Sending messages (text, media, audio, lists, buttons, reactions), (3) Configuring webhooks or event listeners, (4) Managing groups or contacts, (5) Integrating with Typebot, Chatwoot, Dify, or OpenAI through Evolution API. Triggers on: evolution-api, evolution api, whatsapp api, baileys, whatsapp integration, send whatsapp, whatsapp webhook.

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.

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:

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

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):

{
  "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)

Connect Instance (get QR code)

GET /instance/connect/{instanceName}

Returns QR code as base64 for scanning with WhatsApp mobile app.

Check Connection State

GET /instance/connectionState/{instanceName}

Returns: open, close, or connecting.

Other Instance Operations

Method	Endpoint	Description
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

Sending Messages

Text Message

POST /message/sendText/{instanceName}

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

Response (201):

{
  "key": {
    "remoteJid": "[e-mail]",
    "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., [e-mail]).

Reply / Quote a Message

Add quoted to any send payload:

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

Media Message

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.

Audio Message

POST /message/sendWhatsAppAudio/{instanceName}

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

Audio is automatically converted to WhatsApp PTT (push-to-talk) format.

Other Message Types

Endpoint	Body fields	Notes
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

Webhook Configuration

Set Webhook via API

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).

Get Webhook Config

GET /webhook/find/{instanceName}

For the complete list of available events, see references/events.md.

Chat Operations

Method	Endpoint	Body	Description
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.

Group Management

Method	Endpoint	Body / Params	Description
POST	/group/create/{instance}	subject, participants[]	Create group
GET	/group/fetchAllGroups/{instance}	query: getParticipants=true	List all groups
GET	/group/findGroupInfos/{instance}?groupJid=	query param	Group details
GET	/group/inviteCode/{instance}?groupJid=	query param	Get invite link
GET	/group/participants/{instance}?groupJid=	query param	List 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.

Profile Settings

Method	Endpoint	Description
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

Integrations

Evolution API supports chatbot integrations configured per-instance:

Integration	Endpoints prefix	Description
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.

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

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