✓ Verified 💻 Development ✓ Enhanced Data

Evolution Api

Complete WhatsApp automation via Evolution API v2.3 - instances, messages (text/media/polls/lists/bu

Rating
4.8 (350 reviews)
Downloads
49,018 downloads
Version
1.0.0

Overview

Complete WhatsApp automation via Evolution API v2.3 - instances, messages (text/media/polls/lists/buttons/status)

Complete Documentation

View Source →

name: evolution-api-v2 description: Complete WhatsApp automation via Evolution API v2.3 - instances, messages (text/media/polls/lists/buttons/status), groups, labels, chatbots (Typebot/OpenAI/Dify/Flowise/N8N/EvoAI), webhooks, proxy, S3 storage, and Chatwoot integration metadata: openclaw: requires: bins: [] env: EVO_API_URL: "Evolution API base URL (e.g., http://localhost:8080 or https://api.yourdomain.com)" EVO_GLOBAL_KEY: "Global API key for admin operations (instance management)" EVO_INSTANCE: "Default instance name" EVO_API_KEY: "Instance-specific API key for messaging operations"

Evolution API v2.3

Complete WhatsApp automation via Evolution API v2.3. Send messages, manage groups, integrate chatbots (Typebot, OpenAI, Dify, Flowise, N8N, Evo AI), configure webhooks, and connect with Chatwoot.

Quick Start

1. Set Environment Variables

``json5 { env: { EVO_API_URL: "http://localhost:8080", // Your API URL EVO_GLOBAL_KEY: "your-global-admin-key", // Admin key (instance mgmt) EVO_INSTANCE: "my-bot", // Instance name EVO_API_KEY: "your-instance-token" // Instance token (messaging) } } `

2. Create Instance & Connect

`bash

Create instance (supports Baileys, Business, or Evolution integration)

curl -X POST "$EVO_API_URL/instance/create" \ -H "apikey: $EVO_GLOBAL_KEY" \ -H "Content-Type: application/json" \ -d '{ "instanceName": "my-bot", "qrcode": true, "integration": "WHATSAPP-BAILEYS" }'

Connect & get QR code

curl -X GET "$EVO_API_URL/instance/connect/$EVO_INSTANCE" \ -H "apikey: $EVO_API_KEY" ` Scan the QR code returned in base64 field. Alternately pass ?number=5511999999999 for pairing code.

3. Send First Message

`bash curl -X POST "$EVO_API_URL/message/sendText/$EVO_INSTANCE" \ -H "apikey: $EVO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "number": "5511999999999", "text": "Hello from Evolution API v2! 🚀" }' `

Authentication

Two authentication levels: | Type | Header | Usage | |------|--------|-------| | Global API Key | apikey: $EVO_GLOBAL_KEY | Admin: create/delete instances, fetch all | | Instance API Key | apikey: $EVO_API_KEY | Messaging, groups, chat, profile, labels | All instance endpoints use the path pattern: /{resource}/{action}/{instanceName}

Core Concepts

Phone Number Formats

| Context | Format | Example | |---------|--------|---------| | Sending messages | Country code + number | 5511999999999 | | Group JID | Group ID | [email protected] | | User JID | Number + suffix | [email protected] |

Integration Types

| Value | Description | |-------|-------------| | WHATSAPP-BAILEYS | Unofficial (default, full features) | | WHATSAPP-BUSINESS | Official Cloud API | | EVOLUTION | Evolution channel |

Message Delay

Add delay (milliseconds) to avoid rate limits: `json { "delay": 1200 } `

Feature Reference

Instance Management

#### Create Instance `bash POST /instance/create Header: apikey: $EVO_GLOBAL_KEY { "instanceName": "my-bot", "qrcode": true, "integration": "WHATSAPP-BAILEYS", // Optional "token": "custom-api-key", "number": "5511999999999", // Settings (optional) "rejectCall": false, "msgCall": "", "groupsIgnore": false, "alwaysOnline": false, "readMessages": false, "readStatus": false, "syncFullHistory": false, // Proxy (optional) "proxyHost": "", "proxyPort": "", "proxyProtocol": "", "proxyUsername": "", "proxyPassword": "" } ` Inline webhook (optional during creation): `json { "webhook": { "url": "https://webhook.site/your-id", "byEvents": false, "base64": true, "headers": { "autorization": "Bearer TOKEN" }, "events": ["MESSAGES_UPSERT", "CONNECTION_UPDATE"] } } ` Inline RabbitMQ / SQS (optional during creation): `json { "rabbitmq": { "enabled": true, "events": ["MESSAGES_UPSERT"] }, "sqs": { "enabled": true, "events": ["MESSAGES_UPSERT"] } } ` Inline Chatwoot (optional during creation): `json { "chatwootAccountId": "1", "chatwootToken": "TOKEN", "chatwootUrl": "https://chatwoot.com", "chatwootSignMsg": true, "chatwootReopenConversation": true, "chatwootConversationPending": false, "chatwootImportContacts": true, "chatwootNameInbox": "evolution", "chatwootMergeBrazilContacts": true, "chatwootImportMessages": true, "chatwootDaysLimitImportMessages": 3 } ` #### Fetch Instances `bash GET /instance/fetchInstances Header: apikey: $EVO_GLOBAL_KEY

Optional query params:

?instanceName=my-bot

?instanceId=INSTANCE_ID

` #### Connect Instance (QR Code) `bash GET /instance/connect/{instance} Header: apikey: $EVO_API_KEY

Optional: ?number=5511999999999 (for pairing code)

` #### Connection Status `bash GET /instance/connectionState/{instance} Header: apikey: $EVO_API_KEY ` #### Restart Instance `bash POST /instance/restart/{instance} Header: apikey: $EVO_API_KEY ` #### Set Presence `bash POST /instance/setPresence/{instance} Header: apikey: $EVO_API_KEY { "presence": "available" } ` Options: available, unavailable #### Logout Instance `bash DELETE /instance/logout/{instance} Header: apikey: $EVO_API_KEY ` #### Delete Instance `bash DELETE /instance/delete/{instance} Header: apikey: $EVO_GLOBAL_KEY `

Settings

#### Set Settings `bash POST /settings/set/{instance} Header: apikey: $EVO_API_KEY { "rejectCall": true, "msgCall": "I do not accept calls", "groupsIgnore": false, "alwaysOnline": true, "readMessages": false, "syncFullHistory": false, "readStatus": false } ` #### Find Settings `bash GET /settings/find/{instance} Header: apikey: $EVO_API_KEY `

Proxy

#### Set Proxy `bash POST /proxy/set/{instance} Header: apikey: $EVO_API_KEY { "enabled": true, "host": "0.0.0.0", "port": "8000", "protocol": "http", "username": "user", "password": "pass" } ` #### Find Proxy `bash GET /proxy/find/{instance} Header: apikey: $EVO_API_KEY `

Send Messages

#### Send Text `bash POST /message/sendText/{instance} { "number": "5511999999999", "text": "Hello World!" // Options: // "delay": 1200, // "linkPreview": false, // "mentionsEveryOne": false, // "mentioned": ["5511888888888"], // "quoted": { "key": { "id": "MESSAGE_ID" }, "message": { "conversation": "quoted text" } } } ` #### Send Media (URL) `bash POST /message/sendMedia/{instance} { "number": "5511999999999", "mediatype": "image", "mimetype": "image/png", "caption": "Caption text", "media": "https://example.com/photo.jpg", "fileName": "photo.png" // Options: delay, quoted, mentionsEveryOne, mentioned } ` Media types: image, video, document #### Send Media (File Upload) `bash POST /message/sendMedia/{instance} Content-Type: multipart/form-data

Use form-data with file field

` #### Send PTV (Round Video) `bash POST /message/sendPtv/{instance} { "number": "5511999999999", "video": "https://example.com/video.mp4" // Options: delay, quoted, mentionsEveryOne, mentioned } ` Also supports file upload via form-data. #### Send Narrated Audio (Voice Note) `bash POST /message/sendWhatsAppAudio/{instance} { "number": "5511999999999", "audio": "https://example.com/audio.mp3" // Options: delay, quoted, encoding (true/false) } ` #### Send Status/Stories `bash POST /message/sendStatus/{instance} { "type": "text", "content": "My status update!", "backgroundColor": "#008000", "font": 1, "allContacts": false, "statusJidList": ["[email protected]"] } ` Types: text, image, video, audio Fonts (text only): 1 SERIF, 2 NORICAN_REGULAR, 3 BRYNDAN_WRITE, 4 BEBASNEUE_REGULAR, 5 OSWALD_HEAVY For image/video: use content as URL and caption for text. #### Send Sticker `bash POST /message/sendSticker/{instance} { "number": "5511999999999", "sticker": "https://example.com/sticker.webp" // Options: delay, quoted } ` #### Send Location `bash POST /message/sendLocation/{instance} { "number": "5511999999999", "name": "Bora Bora", "address": "French Polynesia", "latitude": -16.505538, "longitude": -151.742277 // Options: delay, quoted } ` #### Send Contact (vCard) `bash POST /message/sendContact/{instance} { "number": "5511999999999", "contact": [ { "fullName": "Contact Name", "wuid": "559999999999", "phoneNumber": "+55 99 9 9999-9999", "organization": "Company", "email": "[email protected]", "url": "https://example.com" } ] } ` Multiple contacts can be sent in the array. #### Send Reaction `bash POST /message/sendReaction/{instance} { "key": { "remoteJid": "[email protected]", "fromMe": true, "id": "BAE5A75CB0F39712" }, "reaction": "🚀" } ` Set reaction: "" to remove. #### Send Poll `bash POST /message/sendPoll/{instance} { "number": "5511999999999", "name": "What is your favorite color?", "selectableCount": 1, "values": ["Red", "Blue", "Green"] // Options: delay, quoted } ` #### Send List `bash POST /message/sendList/{instance} { "number": "5511999999999", "title": "List Title", "description": "Choose an option", "buttonText": "Click Here", "footerText": "Footer text", "sections": [ { "title": "Section 1", "rows": [ { "title": "Option A", "description": "Description of option A", "rowId": "opt_a" }, { "title": "Option B", "description": "Description of option B", "rowId": "opt_b" } ] } ] // Options: delay, quoted } ` #### Send Buttons `bash POST /message/sendButtons/{instance} { "number": "5511999999999", "title": "Button Title", "description": "Button Description", "footer": "Footer Text", "buttons": [ { "type": "reply", "displayText": "Reply", "id": "btn_1" }, { "type": "copy", "displayText": "Copy Code", "copyCode": "ABC123" }, { "type": "url", "displayText": "Open Link", "url": "https://example.com" }, { "type": "call", "displayText": "Call Us", "phoneNumber": "5511999999999" }, { "type": "pix", "currency": "BRL", "name": "John Doe", "keyType": "random", "key": "uuid-key" } ] // Options: delay, quoted } ` Button types: reply, copy, url, call, pix Pix keyType: phone, email, cpf, cnpj, random

Chat Operations

#### Check WhatsApp Numbers `bash POST /chat/whatsappNumbers/{instance} { "numbers": [ "55911111111", "55922222222", "55933333333" ] } ` #### Read Messages (Mark as Read) `bash POST /chat/markMessageAsRead/{instance} { "readMessages": [ { "remoteJid": "[email protected]", "fromMe": false, "id": "MESSAGE_ID" } ] } ` #### Archive Chat `bash POST /chat/archiveChat/{instance} { "lastMessage": { "key": { "remoteJid": "[email protected]", "fromMe": false, "id": "MESSAGE_ID" } }, "chat": "[email protected]", "archive": true } ` Set archive: false to unarchive. #### Mark Chat Unread `bash POST /chat/markChatUnread/{instance} { "lastMessage": { "key": { "remoteJid": "[email protected]", "fromMe": false, "id": "MESSAGE_ID" } }, "chat": "[email protected]" } ` #### Delete Message `bash DELETE /chat/deleteMessageForEveryone/{instance} { "id": "MESSAGE_ID", "remoteJid": "[email protected]", "fromMe": true, "participant": "participant_jid" } ` #### Update Message (Edit) `bash POST /chat/updateMessage/{instance} { "number": "5511999999999", "key": { "remoteJid": "[email protected]", "fromMe": true, "id": "MESSAGE_ID" }, "text": "new edited message" } ` #### Send Presence (Typing Indicator) `bash POST /chat/sendPresence/{instance} { "number": "5511999999999", "delay": 1200, "presence": "composing" } ` Options: composing, recording, paused #### Update Block Status `bash POST /message/updateBlockStatus/{instance} { "number": "5511999999999", "status": "block" } ` Options: block, unblock #### Fetch Profile Picture `bash POST /chat/fetchProfilePictureUrl/{instance} { "number": "5511999999999" } ` #### Get Base64 From Media Message `bash POST /chat/getBase64FromMediaMessage/{instance} { "message": { "key": { "id": "MESSAGE_ID" } }, "convertToMp4": false } ` Extracts base64 from received media. Set convertToMp4: true for audio files to get MP4 instead of OGG. #### Find Contacts `bash POST /chat/findContacts/{instance} { "where": { "id": "5511999999999" } } ` Omit id to list all contacts. #### Find Messages `bash POST /chat/findMessages/{instance} { "where": { "key": { "remoteJid": "5511999999999" } }, "page": 1, "offset": 10 } ` #### Find Status Message `bash POST /chat/findStatusMessage/{instance} { "where": { "remoteJid": "[email protected]", "id": "MESSAGE_ID" }, "page": 1, "offset": 10 } ` #### Find Chats `bash POST /chat/findChats/{instance} `

Calls

#### Fake Call (Offer) `bash POST /call/offer/{instance} { "number": "5511999999999", "isVideo": false, "callDuration": 3 } ` Simulates a call offer to the number. callDuration is in seconds.

Labels

#### Find Labels `bash GET /label/findLabels/{instance} ` #### Handle Labels (Add/Remove) `bash POST /label/handleLabel/{instance} { "number": "5511999999999", "labelId": "label_id_here", "action": "add" } ` Actions: add, remove

Profile Settings

#### Fetch Business Profile `bash POST /chat/fetchBusinessProfile/{instance} { "number": "5511999999999" } ` #### Fetch Profile `bash POST /chat/fetchProfile/{instance} { "number": "5511999999999" } ` #### Update Profile Name `bash POST /chat/updateProfileName/{instance} { "name": "My Bot Name" } ` #### Update Profile Status `bash POST /chat/updateProfileStatus/{instance} { "status": "Available 24/7" } ` #### Update Profile Picture `bash POST /chat/updateProfilePicture/{instance} { "picture": "https://example.com/avatar.jpg" } ` #### Remove Profile Picture `bash DELETE /chat/removeProfilePicture/{instance} ` #### Fetch Privacy Settings `bash GET /chat/fetchPrivacySettings/{instance} ` #### Update Privacy Settings `bash POST /chat/updatePrivacySettings/{instance} { "readreceipts": "all", "profile": "all", "status": "contacts", "online": "all", "last": "contacts", "groupadd": "none" } ` Privacy values:
  • readreceipts: all, none
  • profile: all, contacts, contact_blacklist, none
  • status: all, contacts, contact_blacklist, none
  • online: all, match_last_seen
  • last: all, contacts, contact_blacklist, none
  • groupadd: all, contacts, contact_blacklist

Group Management

#### Create Group `bash POST /group/create/{instance} { "subject": "Group Name", "description": "Group description (optional)", "participants": [ "5531900000000", "5531900000000" ] } ` #### Update Group Picture `bash POST /group/updateGroupPicture/{instance}?groupJid={groupJid} { "image": "https://example.com/group-photo.png" } ` #### Update Group Subject (Name) `bash POST /group/updateGroupSubject/{instance}?groupJid={groupJid} { "subject": "New Group Name" } ` #### Update Group Description `bash POST /group/updateGroupDescription/{instance}?groupJid={groupJid} { "description": "New group description" } ` #### Fetch Invite Code `bash GET /group/inviteCode/{instance}?groupJid={groupJid} ` #### Revoke Invite Code `bash POST /group/revokeInviteCode/{instance}?groupJid={groupJid} ` #### Send Invite URL `bash POST /group/sendInvite/{instance} { "groupJid": "[email protected]", "description": "Join my WhatsApp group:", "numbers": ["5511999999999"] } ` #### Find Group by Invite Code `bash GET /group/inviteInfo/{instance}?inviteCode={inviteCode} ` #### Find Group by JID `bash GET /group/findGroupInfos/{instance}?groupJid={groupJid} ` #### Fetch All Groups `bash GET /group/fetchAllGroups/{instance}

Optional: ?getParticipants=true

` #### Find Participants `bash GET /group/participants/{instance}?groupJid={groupJid} ` #### Update Participants `bash POST /group/updateParticipant/{instance}?groupJid={groupJid} { "action": "add", "participants": ["5511999999999"] } ` Actions: add, remove, promote, demote #### Update Group Settings `bash POST /group/updateSetting/{instance}?groupJid={groupJid} { "action": "announcement" } ` Actions:
  • announcement - Only admins send messages
  • not_announcement - Everyone can send
  • locked - Only admins edit group info
  • unlocked - Everyone can edit group info
#### Toggle Ephemeral (Disappearing Messages) `bash POST /group/toggleEphemeral/{instance}?groupJid={groupJid} { "expiration": 86400 } ` Expiration values (seconds):
  • 0 - Off
  • 86400 - 24 hours
  • 604800 - 7 days
  • 7776000 - 90 days
#### Leave Group `bash DELETE /group/leaveGroup/{instance}?groupJid={groupJid} `

Integrations - Events

#### Webhook `bash

Set Webhook

POST /webhook/set/{instance} { "webhook": { "enabled": true, "url": "https://webhook.site/your-id", "headers": { "autorization": "Bearer TOKEN", "Content-Type": "application/json" }, "byEvents": false, "base64": false, "events": [ "APPLICATION_STARTUP", "QRCODE_UPDATED", "MESSAGES_UPSERT", "MESSAGES_UPDATE", "MESSAGES_DELETE", "SEND_MESSAGE", "CONTACTS_UPDATE", "PRESENCE_UPDATE", "CHATS_UPDATE", "CHATS_DELETE", "GROUPS_UPSERT", "GROUP_UPDATE", "GROUP_PARTICIPANTS_UPDATE", "CONNECTION_UPDATE", "LABELS_EDIT", "LABELS_ASSOCIATION", "CALL", "TYPEBOT_START", "TYPEBOT_CHANGE_STATUS" ] } }

Find Webhook

GET /webhook/find/{instance} ` Key options:
  • byEvents - If true, sends to separate URLs per event type
  • base64 - If true, media comes as base64 in payload
#### WebSocket `bash POST /websocket/set/{instance} { "websocket": { "enabled": true, "events": ["MESSAGES_UPSERT", "CONNECTION_UPDATE"] } } GET /websocket/find/{instance} ` #### RabbitMQ `bash POST /rabbitmq/set/{instance} { "rabbitmq": { "enabled": true, "events": ["MESSAGES_UPSERT", "CONNECTION_UPDATE"] } } GET /rabbitmq/find/{instance} ` #### SQS (Amazon) `bash POST /sqs/set/{instance} { "sqs": { "enabled": true, "events": ["MESSAGES_UPSERT", "CONNECTION_UPDATE"] } } GET /sqs/find/{instance} ` #### NATS `bash POST /nats/set/{instance} GET /nats/find/{instance} ` Same payload structure as SQS/RabbitMQ. #### Pusher `bash POST /pusher/set/{instance} GET /pusher/find/{instance} ` Same payload structure as SQS/RabbitMQ. Available Events (all transports): APPLICATION_STARTUP, QRCODE_UPDATED, MESSAGES_SET, MESSAGES_UPSERT, MESSAGES_UPDATE, MESSAGES_DELETE, SEND_MESSAGE, CONTACTS_SET, CONTACTS_UPSERT, CONTACTS_UPDATE, PRESENCE_UPDATE, CHATS_SET, CHATS_UPSERT, CHATS_UPDATE, CHATS_DELETE, GROUPS_UPSERT, GROUP_UPDATE, GROUP_PARTICIPANTS_UPDATE, CONNECTION_UPDATE, LABELS_EDIT, LABELS_ASSOCIATION, CALL, TYPEBOT_START, TYPEBOT_CHANGE_STATUS

Integrations - Chatbots

All chatbot integrations share a common pattern with settings, session management, CRUD, and trigger configuration. Common trigger options (all chatbots): `json { "triggerType": "keyword", "triggerOperator": "equals", "triggerValue": "hello", "expire": 20, "keywordFinish": "#SAIR", "delayMessage": 1000, "unknownMessage": "Message not recognized", "listeningFromMe": false, "stopBotFromMe": false, "keepOpen": false, "debounceTime": 10, "ignoreJids": [] } ` | Field | Description | |-------|-------------| | triggerType | all (every message) or keyword (matched) | | triggerOperator | contains, equals, startsWith, endsWith, regex, none | | triggerValue | The keyword/pattern to match | | expire | Session timeout (minutes) | | keywordFinish | Keyword to end bot session | | delayMessage | Delay between messages (ms) | | unknownMessage | Response for unrecognized input | | listeningFromMe | Process messages sent by you | | stopBotFromMe | Pause bot when you send a message | | keepOpen | Keep session alive after flow ends | | debounceTime | Debounce interval (seconds) | | ignoreJids | JIDs to ignore (e.g., ["@g.us"] to ignore groups) | #### Chatwoot `bash

Set Chatwoot

POST /chatwoot/set/{instance} { "enabled": true, "accountId": "1", "token": "CHATWOOT_TOKEN", "url": "https://chatwoot.yourdomain.com", "signMsg": true, "reopenConversation": true, "conversationPending": false, "nameInbox": "evolution", "mergeBrazilContacts": true, "importContacts": true, "importMessages": true, "daysLimitImportMessages": 2, "signDelimiter": "\n", "autoCreate": true, "organization": "BOT", "logo": "https://example.com/logo.png", "ignoreJids": ["@g.us"] }

Find Chatwoot

GET /chatwoot/find/{instance} ` #### Typebot `bash

Create Typebot

POST /typebot/create/{instance} { "enabled": true, "url": "https://typebot.yourdomain.com", "typebot": "my-typebot-flow-id", "triggerType": "keyword", "triggerOperator": "regex", "triggerValue": "^atend.*", "expire": 20, "keywordFinish": "#SAIR", "delayMessage": 1000, "unknownMessage": "Message not recognized", "listeningFromMe": false, "stopBotFromMe": false, "keepOpen": false, "debounceTime": 10 }

Find/Fetch/Update/Delete

GET /typebot/find/{instance} GET /typebot/fetch/{typebotId}/{instance} PUT /typebot/update/{typebotId}/{instance} DELETE /typebot/delete/{typebotId}/{instance}

Start Typebot manually

POST /typebot/start/{instance} { "url": "https://typebot.yourdomain.com", "typebot": "flow-id", "remoteJid": "[email protected]", "startSession": false, "variables": [ { "name": "pushName", "value": "User Name" } ] }

Change session status

POST /typebot/changeStatus/{instance} { "remoteJid": "[email protected]", "status": "closed" }

Fetch sessions

GET /typebot/fetchSessions/{typebotId}/{instance}

Default settings

POST /typebot/settings/{instance} GET /typebot/fetchSettings/{instance} { "expire": 20, "keywordFinish": "#SAIR", "delayMessage": 1000, "unknownMessage": "Not recognized", "listeningFromMe": false, "stopBotFromMe": false, "keepOpen": false, "debounceTime": 10, "ignoreJids": [], "typebotIdFallback": "fallback-typebot-id" } ` Session statuses: opened, paused, closed #### OpenAI `bash

Set Credentials

POST /openai/creds/{instance} { "name": "apikey", "apiKey": "sk-proj-..." } GET /openai/creds/{instance} DELETE /openai/creds/{openaiCredsId}/{instance}

Create Bot (Assistant or Chat Completion)

POST /openai/create/{instance} { "enabled": true, "openaiCredsId": "creds-id", "botType": "assistant", // For assistants: "assistantId": "asst_XXXXX", "functionUrl": "https://n8n.site.com", // For chatCompletion: "model": "gpt-4o", "systemMessages": ["You are a helpful assistant."], "assistantMessages": ["Hello, how can I help?"], "userMessages": ["Hello!"], "maxTokens": 300, // Trigger options... "triggerType": "keyword", "triggerOperator": "equals", "triggerValue": "ai" }

Find/Fetch/Update/Delete

GET /openai/find/{instance} GET /openai/fetch/{openaiBotId}/{instance} PUT /openai/update/{openaiBotId}/{instance} DELETE /openai/delete/{openaiBotId}/{instance}

Session management

POST /openai/changeStatus/{instance} GET /openai/fetchSessions/{openaiBotId}/{instance}

Default settings

POST /openai/settings/{instance} GET /openai/fetchSettings/{instance} ` Bot types: assistant, chatCompletion #### Dify `bash POST /dify/create/{instance} { "enabled": true, "botType": "chatBot", "apiUrl": "http://dify.site.com/v1", "apiKey": "app-123456", // Trigger options... } GET /dify/find/{instance} GET /dify/fetch/{difyId}/{instance} PUT /dify/update/{difyId}/{instance} DELETE /dify/delete/{difyId}/{instance} POST /dify/changeStatus/{instance} GET /dify/fetchSessions/{difyId}/{instance} POST /dify/settings/{instance} GET /dify/fetchSettings/{instance} ` Dify bot types: chatBot, textGenerator, agent, workflow #### Flowise `bash POST /flowise/create/{instance} { "enabled": true, "apiUrl": "http://flowise.site.com/v1", "apiKey": "app-123456", // Trigger options... } GET /flowise/find/{instance} GET /flowise/fetch/{flowiseId}/{instance} PUT /flowise/update/{flowiseId}/{instance} DELETE /flowise/delete/{flowiseId}/{instance} POST /flowise/changeStatus/{instance} GET /flowise/fetchSessions/{flowiseId}/{instance} POST /flowise/settings/{instance} GET /flowise/fetchSettings/{instance} ` #### N8N `bash POST /n8n/create/{instance} { "enabled": true, "apiUrl": "http://n8n.site.com/v1", "apiKey": "app-123456", // Trigger options... } GET /n8n/find/{instance} GET /n8n/fetch/{n8nId}/{instance} PUT /n8n/update/{n8nId}/{instance} DELETE /n8n/delete/{n8nId}/{instance} POST /n8n/changeStatus/{instance} GET /n8n/fetchSessions/{n8nId}/{instance} POST /n8n/settings/{instance} GET /n8n/fetchSettings/{instance} ` #### Evolution Bot `bash POST /evolutionBot/create/{instance} { "enabled": true, "apiUrl": "http://api.site.com/v1", "apiKey": "app-123456", // Trigger options... } GET /evolutionBot/find/{instance} GET /evolutionBot/fetch/{evolutionBotId}/{instance} PUT /evolutionBot/update/{evolutionBotId}/{instance} DELETE /evolutionBot/delete/{evolutionBotId}/{instance} POST /evolutionBot/changeStatus/{instance} GET /evolutionBot/fetchSessions/{evolutionBotId}/{instance} POST /evolutionBot/settings/{instance} GET /evolutionBot/fetchSettings/{instance} ` #### Evo AI `bash POST /evoai/create/{instance} { "enabled": true, "apiUrl": "http://evoai.site.com/v1", "apiKey": "app-123456", // Trigger options... } GET /evoai/find/{instance} GET /evoai/fetch/{evoaiId}/{instance} PUT /evoai/update/{evoaiId}/{instance} DELETE /evoai/delete/{evoaiId}/{instance} POST /evoai/changeStatus/{instance} GET /evoai/fetchSessions/{evoaiId}/{instance} POST /evoai/settings/{instance} GET /evoai/fetchSettings/{instance} `

Integrations - Channel (WhatsApp Business Cloud API)

#### Send Template `bash POST /message/sendTemplate/{instance} { "number": "5511999999999", "name": "hello_world", "language": "en_US", "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "John" }, { "type": "text", "text": "[email protected]" } ] }, { "type": "button", "sub_type": "URL", "index": "1", "parameters": [ { "type": "text", "text": "/reset-password/1234" } ] } ] } ` #### Create Template `bash POST /template/create/{instance} { "name": "my_template", "category": "MARKETING", "allowCategoryChange": false, "language": "en_US", "components": [ { "type": "BODY", "text": "Thank you {{1}}! Confirmation: {{2}}", "example": { "body_text": [["John", "860198-230332"]] } }, { "type": "BUTTONS", "buttons": [ { "type": "QUICK_REPLY", "text": "Unsubscribe" }, { "type": "URL", "text": "Support", "url": "https://example.com" } ] } ] } ` Categories: AUTHENTICATION, MARKETING, UTILITY #### Find Templates `bash GET /template/find/{instance} ` #### Evolution Channel Webhook `bash POST /webhook/evolution { "numberId": "5511999999999", "key": { "remoteJid": "5511888888888", "fromMe": false, "id": "ABC1234" }, "pushName": "Contact Name", "message": { "conversation": "Hello" }, "messageType": "conversation" } ` Message types: conversation, imageMessage, videoMessage, documentMessage, audioMessage

Storage (S3/MinIO)

#### Get Media `bash POST /s3/getMedia/{instance} { "id": "media-id", "type": "image", "messageId": "MESSAGE_ID" } ` #### Get Media URL `bash POST /s3/getMediaUrl/{instance} { "id": "media-id" } `

System

#### Get API Information `bash GET / ` Returns API version and system info. #### Metrics `bash GET /metrics Authorization: Basic (METRICS_USER:password) `

Common Workflows

Broadcast Message

`bash for number in 5511999999999 5511888888888 5511777777777; do curl -X POST "$EVO_API_URL/message/sendText/$EVO_INSTANCE" \ -H "apikey: $EVO_API_KEY" \ -H "Content-Type: application/json" \ -d "{ \"number\": \"$number\", \"text\": \"Broadcast message!\", \"delay\": 2000 }" done `

Auto-Create Group + Configure Bot

`bash

1. Create group

curl -X POST "$EVO_API_URL/group/create/$EVO_INSTANCE" \ -H "apikey: $EVO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "subject": "Support Group", "participants": ["5511999999999"] }'

2. Attach Typebot for auto-response

curl -X POST "$EVO_API_URL/typebot/create/$EVO_INSTANCE" \ -H "apikey: $EVO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "enabled": true, "url": "https://typebot.yourdomain.com", "typebot": "support-flow-id", "triggerType": "all" }' `

Full Instance Setup (Instance + Webhook + Chatwoot)

`bash

1. Create instance with webhook inline

curl -X POST "$EVO_API_URL/instance/create" \ -H "apikey: $EVO_GLOBAL_KEY" \ -H "Content-Type: application/json" \ -d '{ "instanceName": "support-bot", "qrcode": true, "integration": "WHATSAPP-BAILEYS", "webhook": { "url": "https://n8n.yourdomain.com/webhook/evo", "byEvents": false, "base64": false, "events": ["MESSAGES_UPSERT", "CONNECTION_UPDATE"] } }'

2. Connect

curl -X GET "$EVO_API_URL/instance/connect/support-bot" \ -H "apikey: $EVO_API_KEY"

3. Configure Chatwoot

curl -X POST "$EVO_API_URL/chatwoot/set/support-bot" \ -H "apikey: $EVO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "enabled": true, "accountId": "1", "token": "CHATWOOT_TOKEN", "url": "https://chatwoot.yourdomain.com", "signMsg": true, "importContacts": true, "importMessages": true, "autoCreate": true, "nameInbox": "support-bot" }' `

Check Numbers Before Sending

`bash

1. Validate numbers

curl -X POST "$EVO_API_URL/chat/whatsappNumbers/$EVO_INSTANCE" \ -H "apikey: $EVO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "numbers": ["5511999999999", "5511888888888"] }'

2. Send only to valid numbers

`

Rate Limits & Best Practices

Delays

Always add delays between messages: `json { "delay": 1200 } ` Recommended:
  • 1-2 seconds between individual messages
  • 3-5 seconds between mass sends
  • Exponential backoff on errors

Error Handling

| Status | Meaning | |--------|---------| | 200 | Success | | 400 | Bad request (check body/params) | | 401 | Unauthorized (check API key) | | 404 | Not found (instance/resource) | | 500 | Server error |

Common Issues

| Error | Solution | |-------|----------| | Instance not connected | Run GET /instance/connect/{instance} | | Invalid phone format | Use country code without +: 5511999999999 | | Message not sent | Check GET /instance/connectionState/{instance} | | Group operation failed | Verify you're admin | | Media extraction fails | Ensure MongoDB/file storage is enabled | | Chatwoot not syncing | Check token and URL, verify importMessages is true |

Troubleshooting

Instance Won't Connect

`bash

1. Check instances

GET /instance/fetchInstances

2. Restart instance

POST /instance/restart/{instance}

3. Reconnect

GET /instance/connect/{instance} `

Chatbot Not Responding

  • Check bot is enabled: GET /{botType}/find/{instance}
  • Check trigger matches incoming message
  • Check session status: GET /{botType}/fetchSessions/{botId}/{instance}
  • Reset session: POST /{botType}/changeStatus/{instance} with status: "closed"

Messages Not Being Delivered

  • Verify connection: GET /instance/connectionState/{instance}
  • Check phone format (no +, no spaces)
  • Verify recipient has WhatsApp: POST /chat/whatsappNumbers/{instance}
  • Check webhook for delivery status events

v2 vs v3 (Evolution Go) Differences

| Feature | v2.3 | v3 (Go) | |---------|------|---------| | Language | Node.js/TypeScript | Go | | Endpoints | /message/sendText/{instance} | /send/text | | Chatbot integrations | 7 (Typebot, OpenAI, Dify, Flowise, N8N, EvolutionBot, EvoAI) | Fewer built-in | | Chatwoot | Native integration | Separate | | Event transports | 6 (Webhook, WS, RabbitMQ, SQS, NATS, Pusher) | Fewer | | Lists/Buttons | Supported | Deprecated | | PTV (Round Video) | Supported | Supported | | Status/Stories | Supported | Supported | | Templates | Business Cloud API | Business Cloud API | | S3 Storage | Built-in | Separate |

Resources

  • Evolution API: https://github.com/EvolutionAPI/evolution-api
  • Documentation: https://doc.evolution-api.com
  • Chatwoot: https://www.chatwoot.com
  • Typebot: https://typebot.io
  • WhatsApp Business API: https://developers.facebook.com/docs/whatsapp

Tips

  • Always check connection before operations
  • Use delays to avoid rate limits (1.2s+ between messages)
  • Store keys in environment variables, never hardcode
  • Handle disconnects with webhook CONNECTION_UPDATE event
  • Validate numbers with whatsappNumbers before bulk sends
  • Use debounceTime in chatbots to group fast messages
  • Set ignoreJids: ["@g.us"] in chatbots to ignore group messages
  • Test triggers with triggerType: "keyword" before switching to "all"`
  • Monitor sessions - expired sessions stop chatbot responses
  • Use Chatwoot for human handoff from chatbot flows

Installation

Terminal bash 

openclaw install evolution-api
Copied!

Tags

#web_and-frontend-development #api #automation

Quick Info

Category Development
Model Claude 3.5
Complexity Multi-Agent
Author impa365
Last Updated 3/10/2026
🚀
Optimized for
Claude 3.5
🧠

Ready to Install?

Get started with this skill in seconds

openclaw install evolution-api

Resources

📂
OpenClaw Skills
View on OpenClaw GitHub
→

Related Skills

✓ Verified 💻 Development

4claw

4claw — a moderated imageboard for AI agents.

🧠 Claude-Ready #ai_and-llms
)}
★ 4.4 (118)
↓ 4,990
v1.0.0
✓ Verified 💻 Development

Aap Passport

Agent Attestation Protocol - The Reverse Turing Test.

🧠 Claude-Ready #ai_and-llms
)}
★ 4.3 (89)
↓ 4,621
v1.0.0
✓ Verified 💻 Development

Acestep Lyrics Transcription

Transcribe audio to timestamped lyrics using OpenAI Whisper or ElevenLabs Scribe API.

⚡ GPT-Optimized #ai_and-llms #api #script
)}
★ 3.8 (274)
↓ 17,648
v1.0.0
✓ Verified 💻 Development

Adaptive Suite

A continuously adaptive skill suite that empowers Clawdbot.

🧠 Claude-Ready #ai_and-llms #bot
)}
★ 4.7 (88)
↓ 1,625
v1.0.0