# Supergreen API Documentation

Supergreen is a WhatsApp account management platform. It provides a programmatic API to interact with managed WhatsApp accounts.

## Getting Started

All API endpoints require authentication using your account's secret token. You can find this token in your WhatsApp account settings on the main dashboard.

**Base URL:** `https://api.supergreen.cc`

All endpoints accept JSON request bodies and return JSON responses. Make sure to set the `Content-Type: application/json` header.

## Webhook Events

When you configure a webhook URL, Supergreen will send POST requests to your server whenever messages or events are received. The webhook payload follows this structure:

```json
{
  "network": "whatsapp",
  "chat": {
    "id": "972509876543@c.us",
    "username": "John Doe",
    "title": "Optional Group Title"
  },
  "author": {
    "id": "972509876543@c.us",
    "username": "John Doe"
  },
  "text": "Hello! This is a message from a user.",
  "time": 1703251200000
}
```

## Endpoints

### sendMessage

**POST** `/sendMessage`

Send a text message to any WhatsApp number or group.

**Authentication:** Required - Include token in request body

**Request Body:**
- `fromNumber` *string* (Required): Your WhatsApp account phone number
- `toNumber` *string* (Required): Recipient's WhatsApp ID (e.g., '972501234567@c.us' for individuals or 'group-id@g.us' for groups)
- `message` *string* (Required): The text message to send
- `linkPreview` *boolean* (Required): Whether to show link previews for URLs in the message
- `quotedMessageId` *string*: ID of a message to quote/reply to
- `token` *string* (Required): Your account's secret authentication token

**Response Body:**
- `messageId` *string*: 

**Request:**
```json
{
  "fromNumber": "972501234567",
  "toNumber": "972509876543@c.us",
  "message": "Hello! This is a test message.",
  "linkPreview": false,
  "token": "your-secret-token"
}
```

**Response:**
```json
{
  "messageId": "3EB0123456789ABCDEF"
}
```

### sendMedia

**POST** `/sendMedia`

Send images, videos, or documents with optional caption to any WhatsApp number or group.

**Authentication:** Required - Include token in request body

**Request Body:**
- `fromNumber` *string* (Required): Your WhatsApp account phone number
- `toNumber` *string* (Required): Recipient's WhatsApp ID
- `base64` *string* (Required): Base64 encoded media data (with or without data URL prefix)
- `type` *string* (Required): Media type: 'image', 'video', or 'document'
- `mimeType` *string*: Media MIME type (e.g., 'image/jpeg', 'video/mp4', 'application/pdf'). Auto-detected from data URL if not provided
- `filename` *string*: Filename for the media. Auto-generated from MIME type if not provided
- `caption` *string*: Optional caption text for the media
- `token` *string* (Required): Your account's secret authentication token

**Response Body:**
- `messageId` *string*: 

**Request:**
```json
{
  "fromNumber": "972501234567",
  "toNumber": "972509876543@c.us",
  "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
  "type": "image",
  "caption": "Check out this image!",
  "token": "your-secret-token"
}
```

**Response:**
```json
{
  "messageId": "3EB0987654321FEDCBA"
}
```

### editMessage

**POST** `/editMessage`

Edit a previously sent message.

**Authentication:** Required - Include token in request body

**Request Body:**
- `fromNumber` *string* (Required): Your WhatsApp account phone number
- `messageId` *string* (Required): ID of the message to edit (returned from sendMessage)
- `newText` *string* (Required): The new text for the message
- `token` *string* (Required): Your account's secret authentication token

**Request:**
```json
{
  "fromNumber": "972501234567",
  "messageId": "3EB0123456789ABCDEF",
  "newText": "Updated message text",
  "token": "your-secret-token"
}
```

**Response:**
```json
{
  "success": true
}
```

### deleteMessage

**POST** `/deleteMessage`

Delete a previously sent message.

**Authentication:** Required - Include token in request body

**Request Body:**
- `fromNumber` *string* (Required): Your WhatsApp account phone number
- `chatId` *string* (Required): Chat ID (e.g. 972501234567@c.us for 1:1 or groupId@g.us for group)
- `messageId` *string* (Required): ID of the message to delete
- `token` *string* (Required): Your account's secret authentication token

**Request:**
```json
{
  "fromNumber": "972501234567",
  "chatId": "972501234567@c.us",
  "messageId": "3EB0123456789ABCDEF",
  "token": "your-secret-token"
}
```

**Response:**
```json
{
  "success": true
}
```

### sendReaction

**POST** `/sendReaction`

Send a reaction emoji to a message.

**Authentication:** Required - Include token in request body

**Request Body:**
- `fromNumber` *string* (Required): Your WhatsApp account phone number
- `messageId` *string* (Required): ID of the message to react to
- `reaction` *string* (Required): Reaction emoji to send
- `token` *string* (Required): Your account's secret authentication token

**Request:**
```json
{
  "fromNumber": "972501234567",
  "messageId": "3EB0123456789ABCDEF",
  "reaction": "👍",
  "token": "your-secret-token"
}
```

**Response:**
```json
{
  "success": true
}
```

### sendTypingIndication

**POST** `/sendTypingIndication`

Show the 'typing...' indicator in a chat to make your bot feel more human.

**Authentication:** Required - Include token in request body

**Request Body:**
- `fromNumber` *string* (Required): Your WhatsApp account phone number
- `chatId` *string* (Required): Chat ID where typing indicator should appear
- `durationMs` *number*: Duration in milliseconds (optional, defaults to standard duration)
- `token` *string* (Required): Your account's secret authentication token

**Request:**
```json
{
  "fromNumber": "972501234567",
  "chatId": "972509876543@c.us",
  "durationMs": 3000,
  "token": "your-secret-token"
}
```

**Response:**
```json
{
  "success": true
}
```

### stopTypingIndication

**POST** `/stopTypingIndication`

Stop showing the 'typing...' indicator in a chat.

**Authentication:** Required - Include token in request body

**Request Body:**
- `fromNumber` *string* (Required): Your WhatsApp account phone number
- `chatId` *string* (Required): Chat ID where typing indicator should stop
- `token` *string* (Required): Your account's secret authentication token

**Request:**
```json
{
  "fromNumber": "972501234567",
  "chatId": "972509876543@c.us",
  "token": "your-secret-token"
}
```

**Response:**
```json
{
  "success": true
}
```

### getGroups

**POST** `/getGroups`

Retrieve a list of WhatsApp groups with admin status for each group.

**Authentication:** Required - Include token in request body

**Request Body:**
- `fromNumber` *string* (Required): Your WhatsApp account phone number
- `useCache` *boolean*: Whether to use cached group metadata (defaults to true). Set to false for a fresh fetch.
- `token` *string* (Required): Your account's secret authentication token

**Response Body:**
- `warning` *string*: 
- `cacheMaxAgeSeconds` *number*: 
- `groups` *array*: 

**Request:**
```json
{
  "fromNumber": "972501234567",
  "token": "your-secret-token"
}
```

**Response:**
```json
{
  "groups": [
    {
      "id": "120363123456789012@g.us",
      "name": "My Cool Group",
      "isAdmin": true
    },
    {
      "id": "120363987654321098@g.us",
      "name": "Another Group",
      "isAdmin": false
    }
  ]
}
```

### addUserToWhatsAppGroup

**POST** `/addUserToWhatsAppGroup`

Add a user to a WhatsApp group where you are an admin.

**Authentication:** Required - Include token in request body

**Request Body:**
- `groupId` *string* (Required): Group ID (e.g., '120363123456789012@g.us')
- `userId` *string* (Required): User ID to add (e.g., '972509876543@c.us')
- `fromNumber` *string* (Required): Your WhatsApp account phone number
- `token` *string* (Required): Your account's secret authentication token

**Request:**
```json
{
  "fromNumber": "972501234567",
  "groupId": "120363123456789012@g.us",
  "userId": "972509876543@c.us",
  "token": "your-secret-token"
}
```

**Response:**
```json
{
  "success": true
}
```

### getCommonWhatsappGroups

**POST** `/getCommonWhatsappGroups`

Get a list of WhatsApp groups that both you and another user are members of.

**Authentication:** Required - Include token in request body

**Request Body:**
- `fromNumber` *string* (Required): Your WhatsApp account phone number
- `userId` *string* (Required): User ID to check common groups with
- `token` *string* (Required): Your account's secret authentication token

**Response Body:**
- `groups` *array*: 

**Request:**
```json
{
  "fromNumber": "972501234567",
  "userId": "972509876543@c.us",
  "token": "your-secret-token"
}
```

**Response:**
```json
{
  "groups": [
    {
      "id": "120363123456789012@g.us",
      "name": "Shared Group"
    }
  ]
}
```

### getWhatsappJoinRequests

**POST** `/getWhatsappJoinRequests`

Get pending join requests for a group where you are an admin.

**Authentication:** Required - Include token in request body

**Request Body:**
- `fromNumber` *string* (Required): Your WhatsApp account phone number
- `groupId` *string* (Required): Group ID to check for join requests
- `token` *string* (Required): Your account's secret authentication token

**Response Body:**
- `requests` *array*: 

**Request:**
```json
{
  "fromNumber": "972501234567",
  "groupId": "120363123456789012@g.us",
  "token": "your-secret-token"
}
```

**Response:**
```json
{
  "requests": [
    {
      "requesterId": "972509876543@c.us",
      "addedById": null,
      "parentGroupId": null,
      "method": "non_admin_add",
      "timestamp": 1703251200000
    }
  ]
}
```

### approveWhatsappJoinRequests

**POST** `/approveWhatsappJoinRequests`

Approve one or more pending join requests for a group.

**Authentication:** Required - Include token in request body

**Request Body:**
- `fromNumber` *string* (Required): Your WhatsApp account phone number
- `groupId` *string* (Required): Group ID where requests should be approved
- `requesterIds` *array | null*: Array of requester IDs to approve, or null to approve all
- `token` *string* (Required): Your account's secret authentication token

**Response Body:**
- `results` *array*: 

**Request:**
```json
{
  "fromNumber": "972501234567",
  "groupId": "120363123456789012@g.us",
  "requesterIds": [
    "972509876543@c.us"
  ],
  "token": "your-secret-token"
}
```

**Response:**
```json
{
  "results": [
    {
      "requesterId": "972509876543@c.us",
      "error": null,
      "message": "Approved successfully"
    }
  ]
}
```

### rejectWhatsappJoinRequests

**POST** `/rejectWhatsappJoinRequests`

Reject one or more pending join requests for a group.

**Authentication:** Required - Include token in request body

**Request Body:**
- `fromNumber` *string* (Required): Your WhatsApp account phone number
- `groupId` *string* (Required): Group ID where requests should be rejected
- `requesterIds` *array* (Required): Array of requester IDs to reject
- `token` *string* (Required): Your account's secret authentication token

**Response Body:**
- `results` *array*: 

**Request:**
```json
{
  "fromNumber": "972501234567",
  "groupId": "120363123456789012@g.us",
  "requesterIds": [
    "972509876543@c.us"
  ],
  "token": "your-secret-token"
}
```

**Response:**
```json
{
  "results": [
    {
      "requesterId": "972509876543@c.us",
      "error": null,
      "message": "Rejected successfully"
    }
  ]
}
```

### getGroupMembers

**POST** `/getGroupMembers`

Get all members of a WhatsApp group, including their admin status. Member IDs may be LID format (e.g., '12345@lid') instead of phone numbers depending on the account's addressing mode. Use the convertLidToNumber endpoint to resolve LIDs to phone numbers.

**Authentication:** Required - Include token in request body

**Request Body:**
- `fromNumber` *string* (Required): Your WhatsApp account phone number
- `groupId` *string* (Required): Group ID (e.g., '120363123456789012@g.us')
- `token` *string* (Required): Your account's secret authentication token

**Response Body:**
- `members` *array*: 

**Request:**
```json
{
  "fromNumber": "972501234567",
  "groupId": "120363123456789012@g.us",
  "token": "your-secret-token"
}
```

**Response:**
```json
{
  "members": [
    {
      "id": "972509876543@c.us",
      "isAdmin": true,
      "isSuperAdmin": true
    },
    {
      "id": "972501111111@c.us",
      "isAdmin": false,
      "isSuperAdmin": false
    }
  ]
}
```

### getWhatsappGroupDetails

**POST** `/getWhatsappGroupDetails`

Get details about a WhatsApp group using its invite link, including group name, description, size, and participants.

**Authentication:** Required - Include token in request body

**Request Body:**
- `fromNumber` *string* (Required): Your WhatsApp account phone number
- `groupLink` *string* (Required): WhatsApp group invite link (e.g., 'https://chat.whatsapp.com/AbCdEfGhIjK')
- `token` *string* (Required): Your account's secret authentication token

**Response Body:**
- `id` *string*: 
- `subject` *string*: 
- `desc` *string*: 
- `size` *number*: 
- `owner` *string*: 
- `isInGroup` *boolean*: 
- `announce` *boolean*: 
- `restrict` *boolean*: 
- `creation` *number*: 
- `suspended` *boolean*: 
- `participants` *array*: 

**Request:**
```json
{
  "fromNumber": "972501234567",
  "groupLink": "https://chat.whatsapp.com/AbCdEfGhIjK",
  "token": "your-secret-token"
}
```

**Response:**
```json
{
  "success": true,
  "id": "120363123456789012@g.us",
  "subject": "My Group",
  "desc": "Group description",
  "size": 42,
  "participants": [
    {
      "id": "972509876543@c.us",
      "isAdmin": true,
      "isSuperAdmin": false
    }
  ]
}
```

### getGroupInviteLink

**POST** `/getGroupInviteLink`

Get the invite link for a WhatsApp group.

**Authentication:** Required - Include token in request body

**Request Body:**
- `fromNumber` *string* (Required): Your WhatsApp account phone number
- `groupId` *string* (Required): Group ID to get the invite link for
- `token` *string* (Required): Your account's secret authentication token

**Response Body:**
- `inviteLink` *string | null*: 

**Request:**
```json
{
  "fromNumber": "972501234567",
  "groupId": "120363123456789012@g.us",
  "token": "your-secret-token"
}
```

**Response:**
```json
{
  "inviteLink": null
}
```

### joinGroupByInviteLink

**POST** `/joinGroupByInviteLink`

Join a WhatsApp group using its invite link.

**Authentication:** Required - Include token in request body

**Request Body:**
- `fromNumber` *string* (Required): Your WhatsApp account phone number
- `groupLink` *string* (Required): WhatsApp group invite link to join
- `token` *string* (Required): Your account's secret authentication token

**Response Body:**
- `status` *string*: 
- `chatId` *string*: 

**Request:**
```json
{
  "fromNumber": "972501234567",
  "groupLink": "https://chat.whatsapp.com/AbCdEfGhIjK",
  "token": "your-secret-token"
}
```

**Response:**
```json
{
  "status": "joined",
  "chatId": "120363123456789012@g.us"
}
```

### blockContact

**POST** `/blockContact`

Block a WhatsApp contact.

**Authentication:** Required - Include token in request body

**Request Body:**
- `fromNumber` *string* (Required): Your WhatsApp account phone number
- `contactId` *string* (Required): Contact ID to block (e.g., '972509876543@c.us')
- `token` *string* (Required): Your account's secret authentication token

**Request:**
```json
{
  "fromNumber": "972501234567",
  "contactId": "972509876543@c.us",
  "token": "your-secret-token"
}
```

**Response:**
```json
{
  "success": true
}
```

### unblockContact

**POST** `/unblockContact`

Unblock a previously blocked WhatsApp contact.

**Authentication:** Required - Include token in request body

**Request Body:**
- `fromNumber` *string* (Required): Your WhatsApp account phone number
- `contactId` *string* (Required): Contact ID to unblock (e.g., '972509876543@c.us')
- `token` *string* (Required): Your account's secret authentication token

**Request:**
```json
{
  "fromNumber": "972501234567",
  "contactId": "972509876543@c.us",
  "token": "your-secret-token"
}
```

**Response:**
```json
{
  "success": true
}
```

### convertLidToNumber

**POST** `/convertLidToNumber`

Convert a WhatsApp LID (Linked ID) to a phone number. Some accounts use LID addressing mode where user IDs appear as '12345@lid' instead of phone numbers. This endpoint resolves them.

**Authentication:** Required - Include token in request body

**Request Body:**
- `fromNumber` *string* (Required): Your WhatsApp account phone number
- `lid` *string* (Required): LID to resolve (e.g., '119846817792023@lid')
- `token` *string* (Required): Your account's secret authentication token

**Response Body:**
- `number` *string | null*: 

**Request:**
```json
{
  "fromNumber": "972501234567",
  "lid": "119846817792023@lid",
  "token": "your-secret-token"
}
```

**Response:**
```json
{
  "number": "972509876543@c.us"
}
```

### setWebhook

**POST** `/setWebhook`

Set or update the webhook URL to receive incoming messages and events.

**Authentication:** Required - Include token in request body

**Request Body:**
- `phoneNumber` *string* (Required): Your WhatsApp account phone number
- `url` *string | null* (Required): Webhook URL to receive updates, or null to remove webhook
- `token` *string* (Required): Your account's secret authentication token

**Request:**
```json
{
  "phoneNumber": "972501234567",
  "url": "https://your-server.com/webhook",
  "token": "your-secret-token"
}
```

**Response:**
```json
{}
```

### addWebhook

**POST** `/addWebhook`

Add an additional webhook URL to receive incoming messages and events. Each account can have multiple webhook URLs — events will be sent to all of them.

**Authentication:** Required - Include token in request body

**Request Body:**
- `phoneNumber` *string* (Required): Your WhatsApp account phone number
- `url` *string* (Required): Webhook URL to add
- `token` *string* (Required): Your account's secret authentication token

**Request:**
```json
{
  "phoneNumber": "972501234567",
  "url": "https://your-server.com/webhook",
  "token": "your-secret-token"
}
```

**Response:**
```json
{}
```

### removeWebhook

**POST** `/removeWebhook`

Remove a webhook URL from the account. If the URL matches the legacy webhook field, that is also cleared.

**Authentication:** Required - Include token in request body

**Request Body:**
- `phoneNumber` *string* (Required): Your WhatsApp account phone number
- `url` *string* (Required): Webhook URL to remove
- `token` *string* (Required): Your account's secret authentication token

**Request:**
```json
{
  "phoneNumber": "972501234567",
  "url": "https://your-server.com/webhook",
  "token": "your-secret-token"
}
```

**Response:**
```json
{}
```

### reconnect

**POST** `/reconnect`

Manually trigger a reconnection of your WhatsApp account. The login method (QR code vs pairing code) is determined by the account's preferCodeLogin setting — use setLoginMethod to change it before reconnecting.

**Authentication:** Required - Include token in request body

**Request Body:**
- `number` *string* (Required): Your WhatsApp account phone number
- `token` *string* (Required): Your account's secret authentication token

**Request:**
```json
{
  "number": "972501234567",
  "token": "your-secret-token"
}
```

**Response:**
```json
{}
```

### setLoginMethod

**POST** `/setLoginMethod`

Set whether the account should use a pairing code or QR code when reconnecting. When preferCodeLogin is true, the next reconnect will generate a pairing code instead of a QR code.

**Authentication:** Required - Include token in request body

**Request Body:**
- `phoneNumber` *string* (Required): Your WhatsApp account phone number
- `preferCodeLogin` *boolean* (Required): Set to true for pairing code login, false for QR code login
- `token` *string* (Required): Your account's secret authentication token

**Request:**
```json
{
  "phoneNumber": "972501234567",
  "preferCodeLogin": true,
  "token": "your-secret-token"
}
```

**Response:**
```json
{
  "success": true
}
```

### clearCredentials

**POST** `/clearCredentials`

Clear all stored credentials for your WhatsApp account. Use this to reset authentication.

**Authentication:** Required - Include token in request body

**Request Body:**
- `phoneNumber` *string* (Required): Your WhatsApp account phone number
- `token` *string* (Required): Your account's secret authentication token

**Request:**
```json
{
  "phoneNumber": "972501234567",
  "token": "your-secret-token"
}
```

**Response:**
```json
{
  "success": true
}
```

### changeWhatsappAccountName

**POST** `/changeWhatsappAccountName`

Change the display name of your WhatsApp account.

**Authentication:** Required - Include token in request body

**Request Body:**
- `phoneNumber` *string* (Required): Your WhatsApp account phone number
- `name` *string* (Required): The new display name for your WhatsApp account
- `token` *string* (Required): Your account's secret authentication token

**Request:**
```json
{
  "phoneNumber": "972501234567",
  "name": "My Business Bot",
  "token": "your-secret-token"
}
```

**Response:**
```json
{}
```

### changeWhatsappAccountAvatar

**POST** `/changeWhatsappAccountAvatar`

Change the profile picture of your WhatsApp account.

**Authentication:** Required - Include token in request body

**Request Body:**
- `phoneNumber` *string* (Required): Your WhatsApp account phone number
- `imageBase64` *string* (Required): Base64-encoded JPEG image. Can optionally include data URI prefix (data:image/jpeg;base64,...)
- `token` *string* (Required): Your account's secret authentication token

**Request:**
```json
{
  "phoneNumber": "972501234567",
  "imageBase64": "/9j/4AAQSkZJRg...",
  "token": "your-secret-token"
}
```

**Response:**
```json
{}
```

### changeWhatsappAccountBio

**POST** `/changeWhatsappAccountBio`

Change the bio/about text of your WhatsApp account.

**Authentication:** Required - Include token in request body

**Request Body:**
- `phoneNumber` *string* (Required): Your WhatsApp account phone number
- `bio` *string* (Required): The new bio/about text for your account
- `token` *string* (Required): Your account's secret authentication token

**Request:**
```json
{
  "phoneNumber": "972501234567",
  "bio": "Powered by Supergreen",
  "token": "your-secret-token"
}
```

**Response:**
```json
{}
```