evogo

Complete WhatsApp automation via Evolution API Go v3 - instances, messages (text/media/polls/carousels), groups, contacts, chats, communities, newsletters, and real-time webhooks

# evoGo - Evolution API Go v3

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

---

## 🚀 Quick Start

### 1. Set Environment Variables

```json5
{
  env: {
    EVOGO_API_URL: "http://localhost:8080",        // Your API URL
    EVOGO_GLOBAL_KEY: "your-global-admin-key",     // Admin key (instance mgmt)
    EVOGO_INSTANCE: "my-bot",                      // Instance name
    EVOGO_API_KEY: "your-instance-token"           // Instance token (messaging)
  }
}
```

### 2. Create Instance & Connect

```bash
# Create instance
curl -X POST "$EVOGO_API_URL/instance/create" \
  -H "apikey: $EVOGO_GLOBAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-bot",
    "token": "my-secret-token",
    "qrcode": true
  }'

# Connect & get QR code
curl -X POST "$EVOGO_API_URL/instance/connect" \
  -H "apikey: $EVOGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number": ""}'
```

Scan the QR code returned in `qrcode.base64`.

### 3. Send First Message

```bash
curl -X POST "$EVOGO_API_URL/send/text" \
  -H "apikey: $EVOGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "text": "Hello from evoGo! 🚀"
  }'
```

---

## 🔐 Authentication

Two authentication levels:

| Type | Header | Usage |
|------|--------|-------|
| **Global API Key** | `apikey: xxx` | Admin: create/delete instances, logs |
| **Instance Token** | `apikey: xxx` | Messaging: send messages, groups, contacts |

Set via environment or pass directly in headers.

---

## 📦 Core Concepts

### Phone Number Formats

| Context | Format | Example |
|---------|--------|---------|
| **Sending messages** | International (no +) | `5511999999999` |
| **Group participants** | JID format | `5511999999999@s.whatsapp.net` |
| **Groups** | Group JID | `120363123456789012@g.us` |
| **Newsletters** | Newsletter JID | `120363123456789012@newsletter` |

### Message Delay

Add `delay` (milliseconds) to avoid rate limits:
```json
{
  "number": "5511999999999",
  "text": "Message with delay",
  "delay": 2000
}
```

---

## 🎯 Feature Reference

### 📱 Instance Management

#### Create Instance
```bash
POST /instance/create
Header: apikey: $EVOGO_GLOBAL_KEY

{
  "name": "bot-name",
  "token": "secret-token",
  "qrcode": true,
  "advancedSettings": {
    "rejectCalls": false,
    "groupsIgnore": false,
    "alwaysOnline": true,
    "readMessages": true,
    "readStatus": true,
    "syncFullHistory": true
  }
}
```

**Advanced Settings:**
- `rejectCalls` - Auto-reject calls
- `groupsIgnore` - Ignore group messages
- `alwaysOnline` - Stay online always
- `readMessages` - Auto-mark messages as read
- `readStatus` - Auto-mark status as viewed
- `syncFullHistory` - Sync full chat history

#### Connect / Get QR Code
```bash
POST /instance/connect
GET  /instance/qr
Header: apikey: $EVOGO_API_KEY

{"number": ""}  # Leave empty for QR, or phone number for pairing
```

#### Connection Status
```bash
GET /instance/status
Header: apikey: $EVOGO_API_KEY
```

Returns: `connected`, `connecting`, `disconnected`

#### List All Instances
```bash
GET /instance/all
Header: apikey: $EVOGO_GLOBAL_KEY
```

#### Delete Instance
```bash
DELETE /instance/delete/{instance}
Header: apikey: $EVOGO_GLOBAL_KEY
```

#### Force Reconnect
```bash
POST /instance/forcereconnect/{instance}
Header: apikey: $EVOGO_GLOBAL_KEY

{"number": "5511999999999"}
```

#### Logs
```bash
GET /instance/logs/{instance}?start_date=2026-01-01&end_date=2026-02-10&level=info&limit=100
Header: apikey: $EVOGO_GLOBAL_KEY
```

**Log levels:** `info`, `warn`, `error`, `debug`

---

### 💬 Send Messages

#### Text Message
```bash
POST /send/text

{
  "number": "5511999999999",
  "text": "Hello World!",
  "delay": 1000,
  "mentionsEveryOne": false,
  "mentioned": ["5511888888888@s.whatsapp.net"]
}
```

#### Media (URL)
```bash
POST /send/media

{
  "number": "5511999999999",
  "url": "https://example.com/photo.jpg",
  "type": "image",
  "caption": "Check this out!",
  "filename": "photo.jpg"
}
```

**Media types:**
- `image` - JPG, PNG, GIF, WEBP
- `video` - MP4, AVI, MOV, MKV
- `audio` - MP3, OGG, WAV (sent as voice note/PTT)
- `document` - PDF, DOC, DOCX, XLS, XLSX, PPT, TXT, ZIP
- `ptv` - Round video (Instagram-style)

#### Media (File Upload)
```bash
POST /send/media
Content-Type: multipart/form-data

number=5511999999999
type=image
file=@/path/to/file.jpg
caption=Photo caption
filename=custom-name.jpg
```

#### Poll
```bash
POST /send/poll

{
  "number": "5511999999999",
  "question": "Best language?",
  "options": ["JavaScript", "Python", "Go", "Rust"],
  "selectableCount": 1
}
```

**Get poll results:**
```bash
GET /polls/{messageId}/results
```

#### Sticker
```bash
POST /send/sticker

{
  "number": "5511999999999",
  "sticker": "https://example.com/sticker.webp"
}
```

Auto-converts images to WebP format.

#### Location
```bash
POST /send/location

{
  "number": "5511999999999",
  "latitude": -23.550520,
  "longitude": -46.633308,
  "name": "Avenida Paulista",
  "address": "Av. Paulista, São Paulo - SP"
}
```

#### Contact
```bash
POST /send/contact

{
  "number": "5511999999999",
  "vcard": {
    "fullName": "João Silva",
    "phone": "5511988888888",
    "organization": "Company XYZ",
    "email": "joao@example.com"
  }
}
```

#### Carousel
```bash
POST /send/carousel

{
  "number": "5511999999999",
  "body": "Main carousel text",
  "footer": "Footer text",
  "cards": [
    {
      "header": {
        "title": "Card 1",
        "subtitle": "Subtitle",
        "imageUrl": "https://example.com/img1.jpg"
      },
      "body": {"text": "Card description"},
      "footer": "Card footer",
      "buttons": [
        {
          "displayText": "Click Me",
          "id": "btn1",
          "type": "REPLY"
        }
      ]
    }
  ]
}
```

**Button types:**
- `REPLY` - Simple reply
- `URL` - Opens link
- `CALL` - Initiates call
- `COPY` - Copies text

---

### 📨 Message Operations

#### React to Message
```bash
POST /message/react

{
  "number": "5511999999999",
  "reaction": "👍",
  "id": "MESSAGE_ID",
  "fromMe": false,
  "participant": "5511888888888@s.whatsapp.net"  # Required in groups
}
```

**Reactions:** `👍`, `❤️`, `😂`, `😮`, `😢`, `🙏`, or `"remove"`

#### Typing/Recording Indicator
```bash
POST /message/presence

{
  "number": "5511999999999",
  "state": "composing",
  "isAudio": false
}
```

**States:**
- `composing` + `isAudio: false` → "typing..."
- `composing` + `isAudio: true` → "recording audio..."
- `paused` → Stops indicator

#### Mark as Read
```bash
POST /message/markread

{
  "number": "5511999999999",
  "id": ["MESSAGE_ID_1", "MESSAGE_ID_2"]
}
```

#### Download Media
```bash
POST /message/downloadmedia

{
  "message": {}  # Full message object from webhook
}
```

Returns base64-encoded media.

#### Edit Message
```bash
POST /message/edit

{
  "chat": "5511999999999@s.whatsapp.net",
  "messageId": "MESSAGE_ID",
  "message": "Edited text"
}
```

**Limitations:**
- Text messages only
- Your messages only
- ~15 minute time limit

#### Delete Message
```bash
POST /message/delete

{
  "chat": "5511999999999@s.whatsapp.net",
  "messageId": "MESSAGE_ID"
}
```

**Limitations:**
- Your messages only
- ~48 hour time limit

#### Get Message Status
```bash
POST /message/status

{
  "id": "MESSAGE_ID"
}
```

Returns delivery/read status.

---

### 👥 Group Management

#### List Groups
```bash
GET /group/list        # Basic info (JID + name)
GET /group/myall       # Full info (participants, settings, etc)
```