Skip to main content

​
Overview

GOWA WhatsApp API provides comprehensive group management capabilities including creating groups, managing participants, configuring settings, and handling join requests.

​
Creating Groups

​
Create New Group

Create a new WhatsApp group with optional initial participants: 
curl -X POST http://localhost:3000/group \
  -H "Content-Type: application/json" \
  -H "X-Device-Id: [email protected]" \
  -d '{
    "title": "Project Team",
    "participants": [
      "[email protected]",
      "[email protected]"
    ]
  }'
​
title
string
required
Group name (max 25 characters).
​
participants
array
Optional array of phone numbers (JIDs) to add as initial members.

​
Response

{
  "status": 200,
  "code": "SUCCESS",
  "message": "Group created successfully",
  "results": {
    "group_id": "[email protected]",
    "name": "Project Team"
  }
}

​
Joining Groups

Join a group using its invite link: 
curl -X POST http://localhost:3000/group/join-with-link \
  -H "Content-Type: application/json" \
  -H "X-Device-Id: [email protected]" \
  -d '{
    "link": "https://chat.whatsapp.com/ABC123DEF456"
  }'
The API automatically extracts the group ID from the invite link and sends a join request.
Retrieve group information before joining: 
curl -X GET "http://localhost:3000/group/info-from-link?link=https://chat.whatsapp.com/ABC123DEF456" \
  -H "X-Device-Id: [email protected]"
Response: 
{
  "status": 200,
  "results": {
    "group_id": "[email protected]",
    "name": "Public Community Group",
    "topic": "Welcome to our community!",
    "created_at": "2024-01-15T10:30:00Z",
    "participant_count": 127,
    "is_locked": false,
    "is_announce": true,
    "description": "Group for sharing updates"
  }
}

​
Leave Group

curl -X POST http://localhost:3000/group/leave \
  -H "Content-Type: application/json" \
  -H "X-Device-Id: [email protected]" \
  -d '{
    "group_id": "[email protected]"
  }'

​
Participant Management

​
List Participants

Get all group members with their roles: 
curl -X GET "http://localhost:3000/group/[email protected]" \
  -H "X-Device-Id: [email protected]"
Response: 
{
  "status": 200,
  "results": {
    "group_id": "[email protected]",
    "name": "Project Team",
    "participants": [
      {
        "jid": "[email protected]",
        "phone_number": "6289685024051",
        "lid": "251556368777322@lid",
        "display_name": "John Doe",
        "is_admin": true,
        "is_super_admin": true
      },
      {
        "jid": "[email protected]",
        "phone_number": "6289685024052",
        "display_name": "Jane Smith",
        "is_admin": false,
        "is_super_admin": false
      }
    ]
  }
}

​
Add Participants

Add new members to a group: 
curl -X POST http://localhost:3000/group/participants \
  -H "Content-Type: application/json" \
  -H "X-Device-Id: [email protected]" \
  -d '{
    "group_id": "[email protected]",
    "participants": [
      "[email protected]",
      "[email protected]"
    ]
  }'
Only group admins can add participants. Some groups may require admin approval for new members.

​
Remove Participants

curl -X POST http://localhost:3000/group/participants/remove \
  -H "Content-Type: application/json" \
  -H "X-Device-Id: [email protected]" \
  -d '{
    "group_id": "[email protected]",
    "participants": ["[email protected]"]
  }'

​
Promote to Admin

Grant admin privileges to participants: 
curl -X POST http://localhost:3000/group/participants/promote \
  -H "Content-Type: application/json" \
  -H "X-Device-Id: [email protected]" \
  -d '{
    "group_id": "[email protected]",
    "participants": ["[email protected]"]
  }'

​
Demote from Admin

Remove admin privileges: 
curl -X POST http://localhost:3000/group/participants/demote \
  -H "Content-Type: application/json" \
  -H "X-Device-Id: [email protected]" \
  -d '{
    "group_id": "[email protected]",
    "participants": ["[email protected]"]
  }'
You must be a group admin to promote/demote participants. Super admins (group creators) cannot be demoted.

​
Group Settings

​
Update Group Name

curl -X POST http://localhost:3000/group/name \
  -H "Content-Type: application/json" \
  -H "X-Device-Id: [email protected]" \
  -d '{
    "group_id": "[email protected]",
    "name": "Updated Team Name"
  }'

​
Update Group Description

curl -X POST http://localhost:3000/group/topic \
  -H "Content-Type: application/json" \
  -H "X-Device-Id: [email protected]" \
  -d '{
    "group_id": "[email protected]",
    "topic": "Official project team for Q1 2024"
  }'

​
Set Group Photo

curl -X POST http://localhost:3000/group/photo \
  -H "X-Device-Id: [email protected]" \
  -F "[email protected]" \
  -F "photo=@/path/to/group-photo.jpg"

​
Group Permissions

​
Lock Group Settings

Restrict who can edit group info (name, description, photo): 
curl -X POST http://localhost:3000/group/locked \
  -H "Content-Type: application/json" \
  -H "X-Device-Id: [email protected]" \
  -d '{
    "group_id": "[email protected]",
    "locked": true
  }'
Only admins can edit group name, description, and photo.

​
Announcement Mode

Control who can send messages: 
curl -X POST http://localhost:3000/group/announce \
  -H "Content-Type: application/json" \
  -H "X-Device-Id: [email protected]" \
  -d '{
    "group_id": "[email protected]",
    "announce": true
  }'
Only admins can send messages. Regular members can only read.

​
Join Requests

​
List Pending Join Requests

View participants waiting for approval: 
curl -X GET "http://localhost:3000/group/[email protected]" \
  -H "X-Device-Id: [email protected]"
Response: 
{
  "status": 200,
  "results": [
    {
      "jid": "[email protected]",
      "phone_number": "6289685024055",
      "display_name": "Alice Johnson",
      "requested_at": "2024-03-04T10:15:00Z"
    }
  ]
}

​
Approve Join Request

curl -X POST http://localhost:3000/group/participant-requests/approve \
  -H "Content-Type: application/json" \
  -H "X-Device-Id: [email protected]" \
  -d '{
    "group_id": "[email protected]",
    "participants": ["[email protected]"]
  }'

​
Reject Join Request

curl -X POST http://localhost:3000/group/participant-requests/reject \
  -H "Content-Type: application/json" \
  -H "X-Device-Id: [email protected]" \
  -d '{
    "group_id": "[email protected]",
    "participants": ["[email protected]"]
  }'
Retrieve the group’s current invite link: 
curl -X GET "http://localhost:3000/group/[email protected]" \
  -H "X-Device-Id: [email protected]"
Response: 
{
  "status": 200,
  "results": {
    "invite_link": "https://chat.whatsapp.com/ABC123DEF456",
    "group_id": "[email protected]"
  }
}
Generate a new invite link (invalidates the old one): 
curl -X GET "http://localhost:3000/group/[email protected]&reset=true" \
  -H "X-Device-Id: [email protected]"
Resetting the invite link will invalidate all previously shared links.

​
Get Group Information

Retrieve detailed group metadata: 
curl -X GET "http://localhost:3000/group/[email protected]" \
  -H "X-Device-Id: [email protected]"
Response: 
{
  "status": 200,
  "results": {
    "data": {
      "JID": "[email protected]",
      "Name": "Project Team",
      "Topic": "Official project team",
      "IsLocked": false,
      "IsAnnounce": false,
      "IsEphemeral": false,
      "IsIncognito": false,
      "LinkedParentJID": "",
      "IsDefaultSubGroup": false,
      "CreatedAt": "2024-01-15T10:30:00Z",
      "ParticipantVersionID": "1234567890",
      "Participants": [
        {
          "JID": "[email protected]",
          "IsAdmin": true,
          "IsSuperAdmin": true
        }
      ]
    }
  }
}

​
Export Participants

Export group participants list as CSV: 
curl -X GET "http://localhost:3000/group/participants/[email protected]" \
  -H "X-Device-Id: [email protected]" \
  -o participants.csv
CSV Format: 
JID,Phone Number,Display Name,Is Admin,Is Super Admin
[email protected],6289685024051,John Doe,true,true
[email protected],6289685024052,Jane Smith,false,false

​
Webhook Events

Receive real-time group events via webhooks:

​
Group Participant Events

{
  "event": "group.participants",
  "device_id": "[email protected]",
  "timestamp": "2024-03-04T10:30:00Z",
  "payload": {
    "chat_id": "[email protected]",
    "type": "join",
    "jids": ["[email protected]"]
  }
}
​
payload.type
string
Event type:
  • join — Members added/joined
  • leave — Members left/removed
  • promote — Members promoted to admin
  • demote — Members demoted from admin

​
Group Joined Event

{
  "event": "group.joined",
  "device_id": "[email protected]",
  "timestamp": "2024-03-04T10:30:00Z",
  "payload": {
    "group_id": "[email protected]",
    "name": "New Team Group"
  }
}

​
List Your Groups

Get all groups you’re a member of: 
curl -X GET http://localhost:3000/user/my/groups \
  -H "X-Device-Id: [email protected]"
Known Limitation: This endpoint returns a maximum of 500 groups due to WhatsApp protocol restrictions. This is enforced by WhatsApp servers, not the API.

​
Best Practices

Check Permissions

Always verify you have admin rights before attempting admin-only operations (add/remove participants, change settings).

Handle Failures Gracefully

Participant operations may fail for individual users (e.g., privacy settings). Check response status for each participant.

Rate Limit Additions

Avoid adding too many participants at once. WhatsApp may rate-limit bulk additions to prevent spam.

Use Webhooks

Subscribe to group.participants webhook events to track real-time group changes.

​
Error Handling

{
  "status": 403,
  "code": "FORBIDDEN",
  "message": "You must be a group admin to perform this action"
}
Solution: Only admins can modify group settings and manage participants.
{
  "status": 404,
  "code": "NOT_FOUND",
  "message": "Group not found or you are not a member"
}
Solution: Verify the group ID is correct and you’re a member of the group.

​
Complete Example

const axios = require('axios');

const BASE_URL = 'http://localhost:3000';
const DEVICE_ID = '[email protected]';

class GroupManager {
  constructor() {
    this.headers = {
      'Content-Type': 'application/json',
      'X-Device-Id': DEVICE_ID
    };
  }

  async createGroup(name, participants = []) {
    const response = await axios.post(
      `${BASE_URL}/group`,
      { title: name, participants },
      { headers: this.headers }
    );
    return response.data.results.group_id;
  }

  async addParticipants(groupId, participants) {
    return axios.post(
      `${BASE_URL}/group/participants`,
      { group_id: groupId, participants },
      { headers: this.headers }
    );
  }

  async promoteToAdmin(groupId, participants) {
    return axios.post(
      `${BASE_URL}/group/participants/promote`,
      { group_id: groupId, participants },
      { headers: this.headers }
    );
  }

  async updateSettings(groupId, locked, announce) {
    await axios.post(
      `${BASE_URL}/group/locked`,
      { group_id: groupId, locked },
      { headers: this.headers }
    );
    
    await axios.post(
      `${BASE_URL}/group/announce`,
      { group_id: groupId, announce },
      { headers: this.headers }
    );
  }
}

// Usage
const manager = new GroupManager();
const groupId = await manager.createGroup('Dev Team', [
  '[email protected]'
]);

await manager.addParticipants(groupId, [
  '[email protected]',
  '[email protected]'
]);

await manager.promoteToAdmin(groupId, ['[email protected]']);
await manager.updateSettings(groupId, true, false);

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us