Supergreen

API Documentation

Integrate Supergreen WhatsApp automation into your application using our HTTP API.

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.

Node.js Quick Start

// Install the client (optional)
// npm install node-fetch


const fetch = require('node-fetch');


const API_BASE = 'https://api.supergreen.cc';
const YOUR_TOKEN = 'your-secret-token-here';
const YOUR_PHONE = 'your-whatsapp-number';


async function sendMessage(toNumber, message) {
  const response = await fetch(API_BASE, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      endpoint: 'sendMessage',
      payload: {
        fromNumber: YOUR_PHONE,
        toNumber: toNumber,
        message: message,
        linkPreview: false,
        token: YOUR_TOKEN
      }
    })
  });
  return response.json();
}


// Example usage
sendMessage('972501234567@c.us', 'Hello from Node.js!')
  .then(result => console.log('Message sent:', result))
  .catch(err => console.error('Error:', err));

Messaging Endpoints

Send Text Message

POSThttps://api.supergreen.cc/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
token (string)*required
Your account's secret authentication token
Response:
messageId (string)
Unique identifier for the sent message
Example:
Request:
{
  "fromNumber": "972501234567",
  "toNumber": "972509876543@c.us",
  "message": "Hello! This is a test message.",
  "linkPreview": false,
  "token": "your-secret-token"
}
Response:
{
  "messageId": "3EB0123456789ABCDEF"
}

Send Media

POSThttps://api.supergreen.cc/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:
messageId (string)
Unique identifier for the sent media message
Example:
Request:
{
  "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:
{
  "messageId": "3EB0987654321FEDCBA"
}

Edit Message

POSThttps://api.supergreen.cc/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
Response:
success (boolean)
Whether the message was successfully edited
Example:
Request:
{
  "fromNumber": "972501234567",
  "messageId": "3EB0123456789ABCDEF",
  "newText": "Updated message text",
  "token": "your-secret-token"
}
Response:
{
  "success": true
}

Chat Interaction

Send Typing Indication

POSThttps://api.supergreen.cc/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
Response:
success (boolean)
Whether the typing indication was successfully triggered
Example:
Request:
{
  "fromNumber": "972501234567",
  "chatId": "972509876543@c.us",
  "durationMs": 3000,
  "token": "your-secret-token"
}
Response:
{
  "success": true
}

Stop Typing Indication

POSThttps://api.supergreen.cc/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
Response:
success (boolean)
Whether the typing indication was successfully stopped
Example:
Request:
{
  "fromNumber": "972501234567",
  "chatId": "972509876543@c.us",
  "token": "your-secret-token"
}
Response:
{
  "success": true
}

Group Management

Get Groups

POSThttps://api.supergreen.cc/getGroups

Retrieve a list of WhatsApp groups. Set adminOnly to true to return only groups where your account is an admin.

Authentication: Required - Include token in request body
Request Body:
fromNumber (string)*required
Your WhatsApp account phone number
adminOnly (boolean)
If true, return only groups where you are an admin. Defaults to false.
token (string)*required
Your account's secret authentication token
Response:
groups (array)
Array of group objects with id and name
Example:
Request:
{
  "fromNumber": "972501234567",
  "adminOnly": true,
  "token": "your-secret-token"
}
Response:
{
  "groups": [
    {
      "id": "120363123456789012@g.us",
      "name": "My Cool Group"
    },
    {
      "id": "120363987654321098@g.us",
      "name": "Another Group"
    }
  ]
}

Add User to Group

POSThttps://api.supergreen.cc/addUserToWhatsAppGroup

Add a user to a WhatsApp 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 (e.g., '120363123456789012@g.us')
userId (string)*required
User ID to add (e.g., '972509876543@c.us')
token (string)*required
Your account's secret authentication token
Response:
success (boolean)
Whether the user was successfully added
Example:
Request:
{
  "fromNumber": "972501234567",
  "groupId": "120363123456789012@g.us",
  "userId": "972509876543@c.us",
  "token": "your-secret-token"
}
Response:
{
  "success": true
}

Get Common Groups

POSThttps://api.supergreen.cc/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:
groups (array)
Array of common group objects with id and name
Example:
Request:
{
  "fromNumber": "972501234567",
  "userId": "972509876543@c.us",
  "token": "your-secret-token"
}
Response:
{
  "groups": [
    {
      "id": "120363123456789012@g.us",
      "name": "Shared Group"
    }
  ]
}

Get Join Requests

POSThttps://api.supergreen.cc/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:
requests (array)
Array of join request objects
Example:
Request:
{
  "fromNumber": "972501234567",
  "groupId": "120363123456789012@g.us",
  "token": "your-secret-token"
}
Response:
{
  "requests": [
    {
      "requesterId": "972509876543@c.us",
      "addedById": null,
      "parentGroupId": null,
      "method": "non_admin_add",
      "timestamp": 1703251200000
    }
  ]
}

Approve Join Requests

POSThttps://api.supergreen.cc/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:
results (array)
Array of result objects for each requester
Example:
Request:
{
  "fromNumber": "972501234567",
  "groupId": "120363123456789012@g.us",
  "requesterIds": [
    "972509876543@c.us"
  ],
  "token": "your-secret-token"
}
Response:
{
  "results": [
    {
      "requesterId": "972509876543@c.us",
      "error": null,
      "message": "Approved successfully"
    }
  ]
}

Reject Join Requests

POSThttps://api.supergreen.cc/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 | null)
Array of requester IDs to reject, or null to reject all
token (string)*required
Your account's secret authentication token
Response:
results (array)
Array of result objects for each requester
Example:
Request:
{
  "fromNumber": "972501234567",
  "groupId": "120363123456789012@g.us",
  "requesterIds": [
    "972509876543@c.us"
  ],
  "token": "your-secret-token"
}
Response:
{
  "results": [
    {
      "requesterId": "972509876543@c.us",
      "error": null,
      "message": "Rejected successfully"
    }
  ]
}

Get Group Members

POSThttps://api.supergreen.cc/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 Convert LID to Number 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:
members (array)
Array of member objects with id, isAdmin, and isSuperAdmin
Example:
Request:
{
  "fromNumber": "972501234567",
  "groupId": "120363123456789012@g.us",
  "token": "your-secret-token"
}
Response:
{
  "members": [
    {
      "id": "972509876543@c.us",
      "isAdmin": true,
      "isSuperAdmin": true
    },
    {
      "id": "972501111111@c.us",
      "isAdmin": false,
      "isSuperAdmin": false
    }
  ]
}

Get Group Details from Link

POSThttps://api.supergreen.cc/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:
success (boolean)
Whether the group details were retrieved
id (string)
Group ID
subject (string)
Group name/subject
desc (string)
Group description
size (number)
Number of members
participants (array)
Array of participant objects
Example:
Request:
{
  "fromNumber": "972501234567",
  "groupLink": "https://chat.whatsapp.com/AbCdEfGhIjK",
  "token": "your-secret-token"
}
Response:
{
  "success": true,
  "id": "120363123456789012@g.us",
  "subject": "My Group",
  "desc": "Group description",
  "size": 42,
  "participants": [
    {
      "id": "972509876543@c.us",
      "isAdmin": true,
      "isSuperAdmin": false
    }
  ]
}

Contact Management

Block Contact

POSThttps://api.supergreen.cc/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
Response:
success (boolean)
Whether the contact was successfully blocked
Example:
Request:
{
  "fromNumber": "972501234567",
  "contactId": "972509876543@c.us",
  "token": "your-secret-token"
}
Response:
{
  "success": true
}

Unblock Contact

POSThttps://api.supergreen.cc/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
Response:
success (boolean)
Whether the contact was successfully unblocked
Example:
Request:
{
  "fromNumber": "972501234567",
  "contactId": "972509876543@c.us",
  "token": "your-secret-token"
}
Response:
{
  "success": true
}

Convert LID to Number

POSThttps://api.supergreen.cc/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:
number (string | null)
Resolved phone number (e.g., '972509876543@c.us'), or null if resolution failed
Example:
Request:
{
  "fromNumber": "972501234567",
  "lid": "119846817792023@lid",
  "token": "your-secret-token"
}
Response:
{
  "number": "972509876543@c.us"
}

Account Management

Set Webhook

POSThttps://api.supergreen.cc/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
Response:
Example:
Request:
{
  "phoneNumber": "972501234567",
  "url": "https://your-server.com/webhook",
  "token": "your-secret-token"
}
Response:
{}

Reconnect

POSThttps://api.supergreen.cc/reconnect

Manually trigger a reconnection of your WhatsApp account.

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
Response:
Example:
Request:
{
  "number": "972501234567",
  "token": "your-secret-token"
}
Response:
{}

Trigger Code Login

POSThttps://api.supergreen.cc/triggerCodeLogin

Request a pairing code for linking your WhatsApp account.

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
Response:
Example:
Request:
{
  "number": "972501234567",
  "token": "your-secret-token"
}
Response:
{}

Clear Credentials

POSThttps://api.supergreen.cc/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
Response:
success (boolean)
Whether credentials were successfully cleared
error (string)
Error message if operation failed
Example:
Request:
{
  "phoneNumber": "972501234567",
  "token": "your-secret-token"
}
Response:
{
  "success": true
}

Change Account Name

POSThttps://api.supergreen.cc/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
Response:
Example:
Request:
{
  "phoneNumber": "972501234567",
  "name": "My Business Bot",
  "token": "your-secret-token"
}
Response:
{}

Change Account Avatar

POSThttps://api.supergreen.cc/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
Response:
Example:
Request:
{
  "phoneNumber": "972501234567",
  "imageBase64": "/9j/4AAQSkZJRg...",
  "token": "your-secret-token"
}
Response:
{}

Delete Account

POSThttps://api.supergreen.cc/deleteAccount

Permanently delete a WhatsApp account from Supergreen. This stops the container, removes session data, and deletes the account record.

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
Response:
success (boolean)
Whether the account was successfully deleted
Example:
Request:
{
  "phoneNumber": "972501234567",
  "token": "your-secret-token"
}
Response:
{
  "success": true
}

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:

{
  "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
}

Error Handling

All API endpoints return standard HTTP status codes. Successful requests return 200 OK. Errors return appropriate status codes with JSON error details:

{
  "error": "Authentication failed",
  "message": "Invalid token provided"
}

Common error codes:

  • 400 - Bad Request (invalid parameters)
  • 401 - Unauthorized (invalid token)
  • 404 - Not Found (endpoint doesn't exist)
  • 500 - Internal Server Error