evolution-api

star 404

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.

pedronauck By pedronauck schedule Updated 5/12/2026
play_arrow Run Skill in Manus View GitHub

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": ["5511888888888@s.whatsapp.net"]
}

Response (201):

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

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

Install via CLI
npx skills add https://github.com/pedronauck/skills --skill evolution-api
Repository Details
star Stars 404
call_split Forks 67
navigation Branch main
article Path SKILL.md
More from Creator
pedronauck
pedronauck Explore all skills →