\r \r

evoGo - Evolution API Go v3\r

\r Complete WhatsApp automation via Evolution API Go v3. Send messages, manage groups, automate conversations, and integrate webhooks.\r \r ---\r \r

🚀 Quick Start\r

\r

1. Set Environment Variables\r

\r

{\r
  env: {\r
    EVOGO_API_URL: "http://localhost:8080",        // Your API URL\r
    EVOGO_GLOBAL_KEY: "your-global-admin-key",     // Admin key (instance mgmt)\r
    EVOGO_INSTANCE: "my-bot",                      // Instance name\r
    EVOGO_API_KEY: "your-instance-token"           // Instance token (messaging)\r
  }\r
}\r
```\r
\r
### 2. Create Instance & Connect\r
\r
```bash\r
# Create instance\r
curl -X POST "$EVOGO_API_URL/instance/create" \\r
  -H "apikey: $EVOGO_GLOBAL_KEY" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "name": "my-bot",\r
    "token": "my-secret-token",\r
    "qrcode": true\r
  }'\r
\r
# Connect & get QR code\r
curl -X POST "$EVOGO_API_URL/instance/connect" \\r
  -H "apikey: $EVOGO_API_KEY" \\r
  -H "Content-Type: application/json" \\r
  -d '{"number": ""}'\r
```\r
\r
Scan the QR code returned in `qrcode.base64`.\r
\r
### 3. Send First Message\r
\r
```bash\r
curl -X POST "$EVOGO_API_URL/send/text" \\r
  -H "apikey: $EVOGO_API_KEY" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "number": "5511999999999",\r
    "text": "Hello from evoGo! 🚀"\r
  }'\r
```\r
\r
---\r
\r
## 🔐 Authentication\r
\r
Two authentication levels:\r
\r
| Type | Header | Usage |\r
|------|--------|-------|\r
| **Global API Key** | `apikey: xxx` | Admin: create/delete instances, logs |\r
| **Instance Token** | `apikey: xxx` | Messaging: send messages, groups, contacts |\r
\r
Set via environment or pass directly in headers.\r
\r
---\r
\r
## 📦 Core Concepts\r
\r
### Phone Number Formats\r
\r
| Context | Format | Example |\r
|---------|--------|---------|\r
| **Sending messages** | International (no +) | `5511999999999` |\r
| **Group participants** | JID format | `[email protected]` |\r
| **Groups** | Group JID | `[email protected]` |\r
| **Newsletters** | Newsletter JID | `120363123456789012@newsletter` |\r
\r
### Message Delay\r
\r
Add `delay` (milliseconds) to avoid rate limits:\r
```json\r
{\r
  "number": "5511999999999",\r
  "text": "Message with delay",\r
  "delay": 2000\r
}\r
```\r
\r
---\r
\r
## 🎯 Feature Reference\r
\r
### 📱 Instance Management\r
\r
#### Create Instance\r
```bash\r
POST /instance/create\r
Header: apikey: $EVOGO_GLOBAL_KEY\r
\r
{\r
  "name": "bot-name",\r
  "token": "secret-token",\r
  "qrcode": true,\r
  "advancedSettings": {\r
    "rejectCalls": false,\r
    "groupsIgnore": false,\r
    "alwaysOnline": true,\r
    "readMessages": true,\r
    "readStatus": true,\r
    "syncFullHistory": true\r
  }\r
}\r
```\r
\r
**Advanced Settings:**\r
- `rejectCalls` - Auto-reject calls\r
- `groupsIgnore` - Ignore group messages\r
- `alwaysOnline` - Stay online always\r
- `readMessages` - Auto-mark messages as read\r
- `readStatus` - Auto-mark status as viewed\r
- `syncFullHistory` - Sync full chat history\r
\r
#### Connect / Get QR Code\r
```bash\r
POST /instance/connect\r
GET  /instance/qr\r
Header: apikey: $EVOGO_API_KEY\r
\r
{"number": ""}  # Leave empty for QR, or phone number for pairing\r
```\r
\r
#### Connection Status\r
```bash\r
GET /instance/status\r
Header: apikey: $EVOGO_API_KEY\r
```\r
\r
Returns: `connected`, `connecting`, `disconnected`\r
\r
#### List All Instances\r
```bash\r
GET /instance/all\r
Header: apikey: $EVOGO_GLOBAL_KEY\r
```\r
\r
#### Delete Instance\r
```bash\r
DELETE /instance/delete/{instance}\r
Header: apikey: $EVOGO_GLOBAL_KEY\r
```\r
\r
#### Force Reconnect\r
```bash\r
POST /instance/forcereconnect/{instance}\r
Header: apikey: $EVOGO_GLOBAL_KEY\r
\r
{"number": "5511999999999"}\r
```\r
\r
#### Logs\r
```bash\r
GET /instance/logs/{instance}?start_date=2026-01-01&end_date=2026-02-10&level=info&limit=100\r
Header: apikey: $EVOGO_GLOBAL_KEY\r
```\r
\r
**Log levels:** `info`, `warn`, `error`, `debug`\r
\r
---\r
\r
### 💬 Send Messages\r
\r
#### Text Message\r
```bash\r
POST /send/text\r
\r
{\r
  "number": "5511999999999",\r
  "text": "Hello World!",\r
  "delay": 1000,\r
  "mentionsEveryOne": false,\r
  "mentioned": ["[email protected]"]\r
}\r
```\r
\r
#### Media (URL)\r
```bash\r
POST /send/media\r
\r
{\r
  "number": "5511999999999",\r
  "url": "https://example.com/photo.jpg",\r
  "type": "image",\r
  "caption": "Check this out!",\r
  "filename": "photo.jpg"\r
}\r
```\r
\r
**Media types:**\r
- `image` - JPG, PNG, GIF, WEBP\r
- `video` - MP4, AVI, MOV, MKV\r
- `audio` - MP3, OGG, WAV (sent as voice note/PTT)\r
- `document` - PDF, DOC, DOCX, XLS, XLSX, PPT, TXT, ZIP\r
- `ptv` - Round video (Instagram-style)\r
\r
#### Media (File Upload)\r
```bash\r
POST /send/media\r
Content-Type: multipart/form-data\r
\r
number=5511999999999\r
type=image\r
file=@/path/to/file.jpg\r
caption=Photo caption\r
filename=custom-name.jpg\r
```\r
\r
#### Poll\r
```bash\r
POST /send/poll\r
\r
{\r
  "number": "5511999999999",\r
  "question": "Best language?",\r
  "options": ["JavaScript", "Python", "Go", "Rust"],\r
  "selectableCount": 1\r
}\r
```\r
\r
**Get poll results:**\r
```bash\r
GET /polls/{messageId}/results\r
```\r
\r
#### Sticker\r
```bash\r
POST /send/sticker\r
\r
{\r
  "number": "5511999999999",\r
  "sticker": "https://example.com/sticker.webp"\r
}\r
```\r
\r
Auto-converts images to WebP format.\r
\r
#### Location\r
```bash\r
POST /send/location\r
\r
{\r
  "number": "5511999999999",\r
  "latitude": -23.550520,\r
  "longitude": -46.633308,\r
  "name": "Avenida Paulista",\r
  "address": "Av. Paulista, São Paulo - SP"\r
}\r
```\r
\r
#### Contact\r
```bash\r
POST /send/contact\r
\r
{\r
  "number": "5511999999999",\r
  "vcard": {\r
    "fullName": "João Silva",\r
    "phone": "5511988888888",\r
    "organization": "Company XYZ",\r
    "email": "[email protected]"\r
  }\r
}\r
```\r
\r
#### Carousel\r
```bash\r
POST /send/carousel\r
\r
{\r
  "number": "5511999999999",\r
  "body": "Main carousel text",\r
  "footer": "Footer text",\r
  "cards": [\r
    {\r
      "header": {\r
        "title": "Card 1",\r
        "subtitle": "Subtitle",\r
        "imageUrl": "https://example.com/img1.jpg"\r
      },\r
      "body": {"text": "Card description"},\r
      "footer": "Card footer",\r
      "buttons": [\r
        {\r
          "displayText": "Click Me",\r
          "id": "btn1",\r
          "type": "REPLY"\r
        }\r
      ]\r
    }\r
  ]\r
}\r
```\r
\r
**Button types:**\r
- `REPLY` - Simple reply\r
- `URL` - Opens link\r
- `CALL` - Initiates call\r
- `COPY` - Copies text\r
\r
---\r
\r
### 📨 Message Operations\r
\r
#### React to Message\r
```bash\r
POST /message/react\r
\r
{\r
  "number": "5511999999999",\r
  "reaction": "👍",\r
  "id": "MESSAGE_ID",\r
  "fromMe": false,\r
  "participant": "[email protected]"  # Required in groups\r
}\r
```\r
\r
**Reactions:** `👍`, `❤️`, `😂`, `😮`, `😢`, `🙏`, or `"remove"`\r
\r
#### Typing/Recording Indicator\r
```bash\r
POST /message/presence\r
\r
{\r
  "number": "5511999999999",\r
  "state": "composing",\r
  "isAudio": false\r
}\r
```\r
\r
**States:**\r
- `composing` + `isAudio: false` → "typing..."\r
- `composing` + `isAudio: true` → "recording audio..."\r
- `paused` → Stops indicator\r
\r
#### Mark as Read\r
```bash\r
POST /message/markread\r
\r
{\r
  "number": "5511999999999",\r
  "id": ["MESSAGE_ID_1", "MESSAGE_ID_2"]\r
}\r
```\r
\r
#### Download Media\r
```bash\r
POST /message/downloadmedia\r
\r
{\r
  "message": {}  # Full message object from webhook\r
}\r
```\r
\r
Returns base64-encoded media.\r
\r
#### Edit Message\r
```bash\r
POST /message/edit\r
\r
{\r
  "chat": "[email protected]",\r
  "messageId": "MESSAGE_ID",\r
  "message": "Edited text"\r
}\r
```\r
\r
**Limitations:**\r
- Text messages only\r
- Your messages only\r
- ~15 minute time limit\r
\r
#### Delete Message\r
```bash\r
POST /message/delete\r
\r
{\r
  "chat": "[email protected]",\r
  "messageId": "MESSAGE_ID"\r
}\r
```\r
\r
**Limitations:**\r
- Your messages only\r
- ~48 hour time limit\r
\r
#### Get Message Status\r
```bash\r
POST /message/status\r
\r
{\r
  "id": "MESSAGE_ID"\r
}\r
```\r
\r
Returns delivery/read status.\r
\r
---\r
\r
### 👥 Group Management\r
\r
#### List Groups\r
```bash\r
GET /group/list        # Basic info (JID + name)\r
GET /group/myall       # Full info (participants, settings, etc)\r
```\r
\r
#### Get Group Info\r
```bash\r
POST /group/info\r
\r
{\r
  "groupJid": "[email protected]"\r
}\r
```\r
\r
#### Create Group\r
```bash\r
POST /group/create\r
\r
{\r
  "groupName": "My Team",\r
  "participants": [\r
    "[email protected]",\r
    "[email protected]"\r
  ]\r
}\r
```\r
\r
**Requirements:**\r
- Name: max 25 characters\r
- Participants: minimum 1\r
\r
#### Manage Participants\r
```bash\r
POST /group/participant\r
\r
{\r
  "groupJid": "[email protected]",\r
  "action": "add",\r
  "participants": ["[email protected]"]\r
}\r
```\r
\r
**Actions:**\r
- `add` - Add members\r
- `remove` - Remove members\r
- `promote` - Make admin\r
- `demote` - Remove admin\r
\r
#### Update Group Settings\r
```bash\r
POST /group/settings\r
\r
{\r
  "groupJid": "[email protected]",\r
  "action": "announcement"\r
}\r
```\r
\r
**Settings:**\r
- `announcement` / `not_announcement` - Only admins send messages\r
- `locked` / `unlocked` - Only admins edit group info\r
- `approval_on` / `approval_off` - Require approval to join\r
- `admin_add` / `all_member_add` - Who can add members\r
\r
#### Get Invite Link\r
```bash\r
POST /group/invitelink\r
\r
{\r
  "groupJid": "[email protected]",\r
  "reset": false\r
}\r
```\r
\r
Set `reset: true` to revoke old link and generate new one.\r
\r
#### Join Group\r
```bash\r
POST /group/join\r
\r
{\r
  "code": "https://chat.whatsapp.com/XXXXXX"\r
}\r
```\r
\r
Accepts full link or just the code.\r
\r
#### Leave Group\r
```bash\r
POST /group/leave\r
\r
{\r
  "groupJid": "[email protected]"\r
}\r
```\r
\r
#### Manage Join Requests\r
```bash\r
# Get pending requests\r
POST /group/requests\r
{\r
  "groupJid": "[email protected]"\r
}\r
\r
# Approve/Reject\r
POST /group/requests/action\r
{\r
  "groupJid": "[email protected]",\r
  "action": "approve",\r
  "participants": ["[email protected]"]\r
}\r
```\r
\r
**Actions:** `approve`, `reject`\r
\r
#### Update Group Metadata\r
```bash\r
# Set photo\r
POST /group/photo\r
{\r
  "groupJid": "[email protected]",\r
  "image": "https://example.com/photo.jpg"\r
}\r
\r
# Set name\r
POST /group/name\r
{\r
  "groupJid": "[email protected]",\r
  "name": "New Group Name"\r
}\r
\r
# Set description\r
POST /group/description\r
{\r
  "groupJid": "[email protected]",\r
  "description": "New description"\r
}\r
```\r
\r
---\r
\r
### 💬 Chat Management\r
\r
#### Pin/Unpin Chat\r
```bash\r
POST /chat/pin\r
POST /chat/unpin\r
\r
{\r
  "chat": "[email protected]"\r
}\r
```\r
\r
#### Archive/Unarchive Chat\r
```bash\r
POST /chat/archive\r
POST /chat/unarchive\r
\r
{\r
  "chat": "[email protected]"\r
}\r
```\r
\r
#### Mute/Unmute Chat\r
```bash\r
POST /chat/mute\r
POST /chat/unmute\r
\r
{\r
  "chat": "[email protected]"\r
}\r
```\r
\r
#### Sync History\r
```bash\r
POST /chat/history-sync-request\r
```\r
\r
Requests full chat history sync (may take time).\r
\r
---\r
\r
### 👤 User & Profile\r
\r
#### Get User Info\r
```bash\r
POST /user/info\r
\r
{\r
  "number": ["5511999999999", "5511888888888"],\r
  "formatJid": true\r
}\r
```\r
\r
Returns: status, profile photo, verified badge, linked devices, etc.\r
\r
#### Check WhatsApp Registration\r
```bash\r
POST /user/check\r
\r
{\r
  "number": ["5511999999999", "5511888888888"]\r
}\r
```\r
\r
Returns: `isInWhatsapp` (true/false) for each number.\r
\r
#### Get Profile Picture\r
```bash\r
POST /user/avatar\r
\r
{\r
  "number": "5511999999999",\r
  "preview": false\r
}\r
```\r
\r
**Preview options:**\r
- `false` - Full resolution\r
- `true` - Low resolution preview\r
\r
#### Get Contacts\r
```bash\r
GET /user/contacts\r
```\r
\r
Lists all saved contacts.\r
\r
#### Privacy Settings\r
```bash\r
# Get privacy settings\r
GET /user/privacy\r
\r
# Set privacy settings\r
POST /user/privacy\r
{\r
  "groupAdd": "all",\r
  "lastSeen": "contacts",\r
  "status": "all",\r
  "profile": "all",\r
  "readReceipts": "all",\r
  "callAdd": "all",\r
  "online": "match_last_seen"\r
}\r
```\r
\r
**Options:** `all`, `contacts`, `contact_blacklist`, `none`, `match_last_seen` (online only)\r
\r
#### Block/Unblock Contact\r
```bash\r
POST /user/block\r
POST /user/unblock\r
\r
{\r
  "number": "5511999999999"\r
}\r
\r
# Get block list\r
GET /user/blocklist\r
```\r
\r
#### Update Profile\r
```bash\r
# Set profile picture\r
POST /user/profilePicture\r
{\r
  "image": "https://example.com/photo.jpg"\r
}\r
\r
# Set profile name\r
POST /user/profileName\r
{\r
  "name": "My Name"\r
}\r
\r
# Set status/about\r
POST /user/profileStatus\r
{\r
  "status": "My custom status"\r
}\r
```\r
\r
**Limits:**\r
- Name: 25 characters max\r
- Status: 139 characters max\r
\r
---\r
\r
### 🏷️ Labels (Tags)\r
\r
#### Add Label\r
```bash\r
# To chat\r
POST /label/chat\r
{\r
  "jid": "[email protected]",\r
  "labelId": "1"\r
}\r
\r
# To message\r
POST /label/message\r
{\r
  "jid": "[email protected]",\r
  "labelId": "1",\r
  "messageId": "MESSAGE_ID"\r
}\r
```\r
\r
#### Remove Label\r
```bash\r
POST /unlabel/chat\r
POST /unlabel/message\r
\r
{\r
  "jid": "[email protected]",\r
  "labelId": "1",\r
  "messageId": "MESSAGE_ID"  # Only for /unlabel/message\r
}\r
```\r
\r
#### Edit Label\r
```bash\r
POST /label/edit\r
\r
{\r
  "labelId": "1",\r
  "name": "New Label Name"\r
}\r
```\r
\r
#### List Labels\r
```bash\r
GET /label\r
```\r
\r
---\r
\r
### 🏘️ Communities\r
\r
#### Create Community\r
```bash\r
POST /community/create\r
\r
{\r
  "communityName": "My Community",\r
  "description": "Optional description"\r
}\r
```\r
\r
#### Add/Remove Groups\r
```bash\r
POST /community/add\r
{\r
  "communityJID": "[email protected]",\r
  "groupJID": ["[email protected]"]\r
}\r
\r
POST /community/remove\r
{\r
  "communityJID": "[email protected]",\r
  "groupJID": ["[email protected]"]\r
}\r
```\r
\r
---\r
\r
### 📢 Newsletters (Channels)\r
\r
#### Create Newsletter\r
```bash\r
POST /newsletter/create\r
\r
{\r
  "name": "My Channel",\r
  "description": "Optional description"\r
}\r
```\r
\r
#### List Newsletters\r
```bash\r
GET /newsletter/list\r
```\r
\r
#### Get Newsletter Info\r
```bash\r
POST /newsletter/info\r
\r
{\r
  "jid": "120363123456789012@newsletter"\r
}\r
```\r
\r
#### Subscribe\r
```bash\r
POST /newsletter/subscribe\r
\r
{\r
  "jid": "120363123456789012@newsletter"\r
}\r
```\r
\r
#### Get Newsletter Messages\r
```bash\r
POST /newsletter/messages\r
\r
{\r
  "jid": "120363123456789012@newsletter",\r
  "limit": 50\r
}\r
```\r
\r
#### Get Invite Link Info\r
```bash\r
POST /newsletter/link\r
\r
{\r
  "key": "INVITE_KEY"\r
}\r
```\r
\r
---\r
\r
### 📞 Call Management\r
\r
#### Reject Call\r
```bash\r
POST /call/reject\r
\r
# Webhook payload from call event\r
```\r
\r
Use with webhook automation to auto-reject calls.\r
\r
---\r
\r
## 🎬 Common Workflows\r
\r
### Broadcast Message to Multiple Contacts\r
```bash\r
for number in 5511999999999 5511888888888 5511777777777; do\r
  curl -X POST "$EVOGO_API_URL/send/text" \\r
    -H "apikey: $EVOGO_API_KEY" \\r
    -H "Content-Type: application/json" \\r
    -d "{\r
      \"number\": \"$number\",\r
      \"text\": \"Broadcast message\",\r
      \"delay\": 2000\r
    }"\r
done\r
```\r
\r
### Send Image with Mentions (Groups)\r
```bash\r
curl -X POST "$EVOGO_API_URL/send/media" \\r
  -H "apikey: $EVOGO_API_KEY" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "number": "[email protected]",\r
    "url": "https://example.com/report.jpg",\r
    "type": "image",\r
    "caption": "Report ready! @5511999999999 please review",\r
    "mentionedJid": ["[email protected]"]\r
  }'\r
```\r
\r
### Auto-Create Group + Welcome Message\r
```bash\r
# 1. Create group\r
GROUP_JID=$(curl -s -X POST "$EVOGO_API_URL/group/create" \\r
  -H "apikey: $EVOGO_API_KEY" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "groupName": "Team Alpha",\r
    "participants": ["[email protected]"]\r
  }' | jq -r '.groupJid')\r
\r
# 2. Send welcome message\r
curl -X POST "$EVOGO_API_URL/send/text" \\r
  -H "apikey: $EVOGO_API_KEY" \\r
  -H "Content-Type: application/json" \\r
  -d "{\r
    \"number\": \"$GROUP_JID\",\r
    \"text\": \"Welcome to Team Alpha! 🎉\"\r
  }"\r
```\r
\r
### Check Multiple Numbers\r
```bash\r
curl -X POST "$EVOGO_API_URL/user/check" \\r
  -H "apikey: $EVOGO_API_KEY" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "number": [\r
      "5511999999999",\r
      "5511888888888",\r
      "5511777777777"\r
    ]\r
  }'\r
```\r
\r
---\r
\r
## ⚠️ Rate Limits & Best Practices\r
\r
### Delays\r
Always add delays between messages:\r
```json\r
{"delay": 2000}  // 2 seconds\r
```\r
\r
**Recommended:**\r
- 1-2 seconds between individual messages\r
- 3-5 seconds between mass sends\r
- Exponential backoff on errors\r
\r
### Error Handling\r
\r
**HTTP Status Codes:**\r
- `200` - Success\r
- `400` - Bad request (check parameters)\r
- `401` - Unauthorized (check API key)\r
- `404` - Not found (instance/resource doesn't exist)\r
- `500` - Server error\r
\r
**Common Issues:**\r
\r
| Error | Solution |\r
|-------|----------|\r
| Instance not connected | Run `POST /instance/connect` |\r
| Invalid phone format | Use international without `+`: `5511999999999` |\r
| Message not sent | Check `GET /instance/status` |\r
| Group operation failed | Verify you're admin (for admin operations) |\r
\r
---\r
\r
## 🔗 Webhooks\r
\r
Configure webhooks to receive real-time events:\r
- Message received\r
- Message sent\r
- Connection status\r
- Group updates\r
- Calls received\r
- And more...\r
\r
Use `POST /webhook/set` endpoint to configure webhook URL (see Postman collection for details).\r
\r
---\r
\r
## 🧪 Troubleshooting\r
\r
### Instance Won't Connect\r
```bash\r
# 1. Check if instance exists\r
GET /instance/all\r
\r
# 2. Force reconnect\r
POST /instance/forcereconnect/{instance}\r
\r
# 3. Check logs\r
GET /instance/logs/{instance}?level=error\r
```\r
\r
### Messages Not Sending\r
1. Verify connection: `GET /instance/status`\r
2. Check phone format (no `+` or spaces)\r
3. Ensure recipient has WhatsApp\r
4. Verify API key is correct\r
\r
### Group Operations Failing\r
1. Check you're admin (for admin operations)\r
2. Verify group JID format: `[email protected]`\r
3. Ensure participants use format: `[email protected]`\r
\r
---\r
\r
## 📚 Resources\r
\r
- **Evolution API Go:** https://github.com/EvolutionAPI/evolution-api\r
- **WhatsApp Business API:** https://developers.facebook.com/docs/whatsapp\r
- **JID Format Guide:** `[email protected]` for users, `[email protected]` for groups\r
\r
---\r
\r
## 🆕 Known Limitations\r
\r
**Not Working (v3.0):**\r
- `/send/button` - Interactive buttons (deprecated by WhatsApp)\r
- `/send/list` - Interactive lists (deprecated by WhatsApp)\r
\r
These endpoints exist but are non-functional due to WhatsApp API changes.\r
\r
---\r
\r
## 💡 Tips\r
\r
1. **Always check status** before operations\r
2. **Use delays** to avoid rate limits (1-2s minimum)\r
3. **Store tokens securely** in environment variables\r
4. **Handle disconnects** with automatic reconnection\r
5. **Validate numbers** before sending\r
6. **Use webhooks** for real-time event handling\r
7. **Monitor logs** for troubleshooting\r
8. **Test with small groups** before mass operations\r
\r
---\r
\r
**evoGo** simplifies WhatsApp automation with Evolution API Go v3. For advanced features, check the full Postman collection or API documentation.\r