Introduction
Who is this for:
- Developers and software engineers building CRM, SaaS, or custom business integrations;
- No-code integrators and automation specialists utilizing Make, Zapier, or n8n;
Use cases include:
- Auto-creating dedicated support or client onboarding groups;
- Synchronizing group participant rosters with CRM deal pipelines;
- Broadcasting transactional announcements and alerts in group chats;
- Connecting interactive chatbots to group conversations;
Prerequisites:
- An active standard WhatsApp number (personal or business app, not official WABA);
- Basic HTTP request knowledge or access to a low-code automation platform;
What you can do with WhatsApp Groups via API
- Send messages to groups: Broadcast updates, announcements, or reminders directly to any group.
- Create new WhatsApp groups: Automatically generate new groups based on events like new customer onboarding or course enrollment.
- Add members to a group: Programmatically invite contacts to a group without manual approval.
- Promote members to admins: Assign or revoke admin rights for selected participants.
- Fetch group participants: Retrieve a full list of members for analytics or CRM sync.
- Detect group events: Track messages, joins, and leaves using webhook listeners.
- Connect bots to groups: Enable bots to read and respond to group messages using defined logic.
Why Meta's Official Groups API Falls Short for Most Businesses
| Feature Cap | Meta Official Business API | Whapi.Cloud Gateway |
|---|---|---|
| Group Member Limit | Strictly limited to 8 participants | Up to 1024 members (standard WhatsApp limit) |
| Verification Barrier | Requires Meta Business Verification & Blue Badge (OBA) | No verification required; connect any active number |
| Onboarding Speed | Days or weeks of application reviews | Under two minutes via quick QR code scan |
| Cost Structure | Metered session-based charges | Predictable flat monthly subscription |
| Rich Media & Actions | Basic template messaging only | Full access to groups, channels, statuses, and catalogs |
How to Link Your WhatsApp and Start Using the API
- 1) Go to your dashboard and open the Default Channel - it's already created for you.
- 2) On Step 1, you'll see a QR code with instructions.
- 3) On your phone, open WhatsApp → Settings → Linked Devices → Link a Device, then scan the QR code.
- 4) Once connected, give your channel a name (e.g., "My Chatbot") for easier identification.
- 5) You'll be redirected to the channel settings screen, you can skip this step for now and return to it later.
How to Send WhatsApp Group Messages via API (with Code Examples)
[email protected]. They are not visible in the mobile or web app — retrieve them with GET /groups before sending messages.- 1) First, retrieve the group ID. Use the
GET /groupsendpoint to fetch a list of your WhatsApp groups along with their unique identifiers. For full details, see the documentation: Get groups. - 2) Once you have the group ID, you can send a message. Automatically generate new groups based on events like new customer onboarding or course enrollment. Use the
POST /messages/textendpoint, specifying the group ID in thetoparameter and your message content in thebodyparameter. For more details, refer to: Send text message.
You can obtain the group ID using the Get groups endpoint or by checking recent conversations through the chats endpoint.
- 1) When you create a group, the group ID will be specified in the response from the API. Below, in a separate chapter, we will show you how to do this;
- 2) Endpoint Get a list of groups;
- 3) Endpoint Get a list of all chats;
curl --request POST \
--url https://gate.whapi.cloud/messages/text \
--header 'accept: application/json' \
--header 'authorization: Bearer YOUR_API_TOKEN' \
--header 'content-type: application/json' \
--data '
{
"to": "[email protected]",
"body": "Hello, this message was sent via API!"
}
'
// composer require guzzlehttp/guzzle
require_once('vendor/autoload.php');
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://gate.whapi.cloud/messages/text', [
'body' => '{"to":"[email protected]","body":"Hello, this message was sent via API!"}',
'headers' => [
'accept' => 'application/json',
'authorization' => 'Bearer YOUR_API_TOKEN',
'content-type' => 'application/json',
],
]);
echo $response->getBody();
# python -m pip install requests
import requests
url = "https://gate.whapi.cloud/messages/text"
payload = {
"to": "[email protected]",
"body": "Hello, this message was sent via API!"
}
headers = {
"accept": "application/json",
"content-type": "application/json",
"authorization": "Bearer YOUR_API_TOKEN"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
// npm install axios --save
import axios from 'axios';
const options = {
method: 'POST',
url: 'https://gate.whapi.cloud/messages/text',
headers: {
accept: 'application/json',
'content-type': 'application/json',
authorization: 'Bearer YOUR_API_TOKEN'
},
data: {to: '[email protected]', body: 'Hello, this message was sent via API!'}
};
axios
.request(options)
.then(res => console.log(res.data))
.catch(err => console.error(err));
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"to\":\"[email protected]\",\"body\":\"Hello, this message was sent via API!\"}");
Request request = new Request.Builder()
.url("https://gate.whapi.cloud/messages/text")
.post(body)
.addHeader("accept", "application/json")
.addHeader("content-type", "application/json")
.addHeader("authorization", "Bearer YOUR_API_TOKEN")
.build();
Response response = client.newCall(request).execute();
//dotnet add package RestSharp
using RestSharp;
var options = new RestClientOptions("https://gate.whapi.cloud/messages/text");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("accept", "application/json");
request.AddHeader("authorization", "Bearer YOUR_API_TOKEN");
request.AddJsonBody("{\"to\":\"[email protected]\",\"body\":\"Hello, this message was sent via API!\"}", false);
var response = await client.PostAsync(request);
Console.WriteLine("{0}", response.Content);
Sending Media and Documents to Groups
POST /messages/image or POST /messages/document.to, a publicly accessible file URL in media, and an optional description in caption.// Send an image or PDF document to a WhatsApp group
const groupId = "[email protected]";
const res = await fetch('https://gate.whapi.cloud/messages/image', {
method: 'POST',
headers: {
'accept': 'application/json',
'content-type': 'application/json',
'authorization': `Bearer ${process.env.WHAPI_TOKEN}`
},
body: JSON.stringify({
to: groupId,
media: "https://whapi.cloud/assets/img/whapi/logo-text.svg",
caption: "Welcome to your automated support channel!"
})
});
const result = await res.json();
console.log("Media message sent:", result);
How to Send WhatsApp Group Messages Using No-Code Tools like Make or n8n
GET https://gate.whapi.cloud/groups
POST https://gate.whapi.cloud/messages/text to: the group ID.body: the message content
How to Create a WhatsApp Group via API
participants array.- 1) Use the
POSTmethod with thehttps://gate.whapi.cloud/groupsendpoint to create a new group. Provide the group name in the subject parameter and include at least one phone number in the participants parameter - this is required for the group to be successfully created. - 2) Upon successful creation, the API will return a group ID. You'll need this identifier to send messages to the group.
- 3) To send a message to the group, use the standard message-sending method. Specify the group ID in the
toparameter and the message content in thebodyparameter.
participants array to ensure successful group creation.
curl --request POST \
--url https://gate.whapi.cloud/groups \
--header 'accept: application/json' \
--header 'authorization: Bearer Your_Token' \
--header 'content-type: application/json' \
--data '
{
"participants": [
"498935516106",
"4915155985667"
],
"subject": "SEO Common GmbH"
}
'
// composer require guzzlehttp/guzzle
require_once('vendor/autoload.php');
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://gate.whapi.cloud/groups', [
'body' => '{"participants":["498935516106","4915155985667"],"subject":"SEO Common GmbH"}',
'headers' => [
'accept' => 'application/json',
'authorization' => 'Bearer Your_Token',
'content-type' => 'application/json',
],
]);
echo $response->getBody();
# python -m pip install requests
import requests
url = "https://gate.whapi.cloud/groups"
payload = {
"participants": ["498935516106", "4915155985667"],
"subject": "SEO Common GmbH"
}
headers = {
"accept": "application/json",
"content-type": "application/json",
"authorization": "Bearer Your_Token"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
// npm install axios --save
import axios from 'axios';
const options = {
method: 'POST',
url: 'https://gate.whapi.cloud/groups',
headers: {
accept: 'application/json',
'content-type': 'application/json',
authorization: 'Bearer Your_Token'
},
data: {participants: ['498935516106', '4915155985667'], subject: 'SEO Common GmbH'}
};
axios
.request(options)
.then(res => console.log(res.data))
.catch(err => console.error(err));
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"participants\":[\"498935516106\",\"4915155985667\"],\"subject\":\"SEO Common GmbH\"}");
Request request = new Request.Builder()
.url("https://gate.whapi.cloud/groups")
.post(body)
.addHeader("accept", "application/json")
.addHeader("content-type", "application/json")
.addHeader("authorization", "Bearer Your_Token")
.build();
Response response = client.newCall(request).execute();
//dotnet add package RestSharp
using RestSharp;
var options = new RestClientOptions("https://gate.whapi.cloud/groups");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("accept", "application/json");
request.AddHeader("authorization", "Bearer Your_Token");
request.AddJsonBody("{\"participants\":[\"498935516106\",\"4915155985667\"],\"subject\":\"SEO Common GmbH\"}", false);
var response = await client.PostAsync(request);
Console.WriteLine("{0}", response.Content);
How to Create a WhatsApp Group Using a No-Code Platform
POST request to https://gate.whapi.cloud/groups with the correct subject (group name) and participants (array of phone numbers).{
"participants": [
"498935516106",
"4915155985667"
],
"subject": "SEO Common GmbH"
}
How to Add Participants to a WhatsApp Group
- 1) Ensure you have the Group ID of the group you want to update. This is a required parameter for the request. We wrote above how to obtain a group ID.
- 2) Send a
POSTrequest tohttps://gate.whapi.cloud/groups/{GroupID}/participantsto add new members. You'll need to include the Group ID in the URL and provide an array of phone numbers for the participants you wish to add.
Direct Addition vs Invite Links
POST /groups/{GroupID}/participants adds users instantly. Invite-link flows often lose a significant share of users who never complete the join step.GET /groups/{GroupID}/invite, and deliver it in a personal message.
curl --request POST \
--url https://gate.whapi.cloud/groups/120367831625595066%40g.us/participants \
--header 'accept: application/json' \
--header 'authorization: Bearer Your_Token' \
--header 'content-type: application/json' \
--data '
{
"participants": [
"373983445541",
"373983445542",
"373983445543"
]
}
'
// composer require guzzlehttp/guzzle
require_once('vendor/autoload.php');
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://gate.whapi.cloud/groups/120367831625595066%40g.us/participants', [
'body' => '{"participants":["373983445541","373983445542","373983445543"]}',
'headers' => [
'accept' => 'application/json',
'authorization' => 'Bearer Your_Token',
'content-type' => 'application/json',
],
]);
echo $response->getBody();
# python -m pip install requests
import requests
url = "https://gate.whapi.cloud/groups/120367831625595066%40g.us/participants"
payload = { "participants": ["373983445541", "373983445542", "373983445543"] }
headers = {
"accept": "application/json",
"content-type": "application/json",
"authorization": "Bearer Your_Token"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
// npm install axios --save
import axios from 'axios';
const options = {
method: 'POST',
url: 'https://gate.whapi.cloud/groups/120367831625595066%40g.us/participants',
headers: {
accept: 'application/json',
'content-type': 'application/json',
authorization: 'Bearer Your_Token'
},
data: {participants: ['373983445541', '373983445542', '373983445543']}
};
axios
.request(options)
.then(res => console.log(res.data))
.catch(err => console.error(err));
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"participants\":[\"373983445541\",\"373983445542\",\"373983445543\"]}");
Request request = new Request.Builder()
.url("https://gate.whapi.cloud/groups/120367831625595066%40g.us/participants")
.post(body)
.addHeader("accept", "application/json")
.addHeader("content-type", "application/json")
.addHeader("authorization", "Bearer Your_Token")
.build();
Response response = client.newCall(request).execute();
//dotnet add package RestSharp
using RestSharp;
var options = new RestClientOptions("https://gate.whapi.cloud/groups/120367831625595066%40g.us/participants");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("accept", "application/json");
request.AddHeader("authorization", "Bearer Your_Token");
request.AddJsonBody("{\"participants\":[\"373983445541\",\"373983445542\",\"373983445543\"]}", false);
var response = await client.PostAsync(request);
Console.WriteLine("{0}", response.Content);
How to Add Participants to a WhatsApp Group Using No-Code Tools
https://gate.whapi.cloud/groups/[email protected]/participants.@ with %40.{
"participants": [
"373983445541",
"373983445542",
"373983445543"
]
}
Real-World No-Code Automation: Auto-Creating Support Groups (Make & n8n)
- Create the group:
POST /groupswith a subject like "Client Support: Company Name" and your bot number. - Add participants:
POST /groups/{groupId}/participantswith the customer and account manager numbers. - Send a welcome message:
POST /messages/imageorPOST /messages/textwith onboarding instructions.
| Automation Path | When to Choose | Key Advantages |
|---|---|---|
| Make / n8n (No-Code) | Rapid prototyping and small to medium business operations. | Visual debugging, pre-built connectors, zero server maintenance. |
| Custom Code (Node.js / Python) | High-volume enterprise apps and complex database syncs. | Lower execution cost, full error handling, unlimited scalability. |
How to Fetch WhatsApp Group Participants via API
- 1) Make sure you are a member of the group you want to access. Without being part of the group, you won’t be able to retrieve its participant list.
- 2) Use the API method Get Groups to fetch a list of all groups associated with your WhatsApp account. If you know the ID of the desired group, call it directly using the Get group endpoint.
- 3) The response will include an array of group objects, each containing information such as the group ID, name, and a participants field with a list of members. Example response:
{
"id": "[email protected]",
"name": "A group of researchers",
"participants": [
{ "id": "972558557032", "rank": "member" },
{ "id": "14409416972", "rank": "creator" },
{ "id": "905589461962", "rank": "member" }
]
}
curl --request GET \
--url 'https://gate.whapi.cloud/groups?count=100' \
--header 'accept: application/json' \
--header 'authorization: Bearer Your_Token'
// composer require guzzlehttp/guzzle
require_once('vendor/autoload.php');
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://gate.whapi.cloud/groups?count=100', [
'headers' => [
'accept' => 'application/json',
'authorization' => 'Bearer Your_Token',
],
]);
echo $response->getBody();
# python -m pip install requests
import requests
url = "https://gate.whapi.cloud/groups?count=100"
headers = {
"accept": "application/json",
"authorization": "Bearer Your_Token"
}
response = requests.get(url, headers=headers)
print(response.text)
// npm install axios --save
import axios from 'axios';
const options = {
method: 'GET',
url: 'https://gate.whapi.cloud/groups?count=100',
headers: {accept: 'application/json', authorization: 'Bearer Your_Token'}
};
axios
.request(options)
.then(res => console.log(res.data))
.catch(err => console.error(err));
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://gate.whapi.cloud/groups?count=100")
.get()
.addHeader("accept", "application/json")
.addHeader("authorization", "Bearer Your_Token")
.build();
Response response = client.newCall(request).execute();
//dotnet add package RestSharp
using RestSharp;
var options = new RestClientOptions("https://gate.whapi.cloud/groups?count=100");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("accept", "application/json");
request.AddHeader("authorization", "Bearer Your_Token");
var response = await client.GetAsync(request);
Console.WriteLine("{0}", response.Content);
How to Retrieve WhatsApp Group Members via No-Code
GET request to https://gate.whapi.cloud/groups to retrieve a list of all WhatsApp groups you are a member of, along with details about each group - including participant information.GET https://gate.whapi.cloud/groups/{GroupID} to fetch data for a specific group.How to Connect a Bot to a WhatsApp Group
- Create a WhatsApp Bot in Node.js;
- Create a WhatsApp Bot in Python;
- Create a WhatsApp Bot in PHP;
- Create a WhatsApp Bot in Java;
chat_id, which will follow the format [email protected] (as opposed to a phone number in private chats). The from field will indicate the individual sender's number inside the group.Tips, Limitations, and Best Practices
- Do not add users to groups without their consent. Always respect user privacy and avoid unsolicited invitations;
- Avoid sending spam or unwanted content, as this may result in your account being flagged or permanently banned;
- Whapi.Cloud does not impose strict API rate limits on paid channels, but WhatsApp may flag accounts sending more than ~20 messages per minute without warm-up history. Use human-like pacing and randomized 1.5–3.5 second delays between actions.
PATCH /groups/{GroupID}/admins immediately after group creation. If the primary bot disconnects, the secondary admin can re-add and promote a new bot. See also Promote to Group Admin.// PATCH https://gate.whapi.cloud/groups/{groupId}/admins
const groupId = "[email protected]";
const res = await fetch(`https://gate.whapi.cloud/groups/${groupId}/admins`, {
method: 'PATCH',
headers: {
'accept': 'application/json',
'content-type': 'application/json',
'authorization': `Bearer ${process.env.WHAPI_TOKEN}`
},
body: JSON.stringify({
participants: ["4915155985667"]
})
});
const status = await res.json();
console.log("Admin promotion status:", status);
Troubleshooting
The Bot Does Not Respond to Incoming Messages
- Ensure you are sending messages to the number on which the bot is running from a different phone. The bot will not be able to respond to messages sent from the same number.
- If the bot does not respond to messages from other numbers, check the operation of webhooks. Use services to simulate webhooks, for example, Webhook.site, to ensure which path the callback requests are coming through. Afterwards, check if the path matches the one you have configured. Also, ensure your server responds with 200Ok.
The Bot Sends Messages Non-Stop
Webhook Callbacks and Common Group Automation Issues
message_created or group_updated. Parse chat_id ending in @g.us to distinguish group traffic from private chats.
- Bot loop sending: check the
from_meflag — without it, the bot may reply to its own messages indefinitely. - Permission denied: the bot must be a group admin to add participants — verify rank via
GET /groups/{GroupID}. - Missing numbers in roster: group metadata sync can take up to 15 seconds after creation before all participant numbers resolve.
Can’t Add a User to the Group?
- You must be a group admin. Only admins are allowed to add new members.
- The user may have restricted group invitations in their privacy settings. If so, they cannot be added automatically via API.
- The group may have reached the maximum size of 1024 participants. In this case, remove inactive members or consider creating a new group.
- WhatsApp’s anti-spam policies may block certain numbers from being added to groups — especially if the contact is not saved in your address book or hasn’t interacted with you. To reduce this risk, we highly recommend programmatically adding the contact to your list first using our Add Contact API.
Message Not Delivered?
- Double-check the group ID - incorrect or expired IDs will result in delivery failure.
- If the message is sent but not visible in the group, review the message format. For example, WhatsApp groups may not display certain content types, such as webp images or interactive buttons.
Permission Denied?
- Your number is not recognized as a group admin.
- The API may not have correctly synced your admin status or phone number. In such cases, try re-authorizing your API channel to refresh permissions and metadata.
Group Members Not Displayed?
GET /groups or GET /group request, group data is queued for synchronization.What Does @lid Mean in Participant List?
@lid instead of phone JIDs, resolve them for CRM mapping with GET /contacts/lids or GET /contacts/ids/{ContactLID}. See resolving anonymized @lid identifiers.// GET https://gate.whapi.cloud/contacts/ids/{contactLid}
const contactLid = "1524746986546@lid";
const res = await fetch(`https://gate.whapi.cloud/contacts/ids/${contactLid}`, {
method: 'GET',
headers: {
'accept': 'application/json',
'authorization': `Bearer ${process.env.WHAPI_TOKEN}`
}
});
const { phone } = await res.json();
console.log("Resolved JID phone number:", phone);
Deployment and Using Servers
Firebase
- Create a project in Firebase Console;
- Install Firebase CLI, following the instructions;
- Initialize Firebase in your project directory with the command firebase init;
- Deploy your bot using the command firebase deploy --only functions.
AWS (Amazon Web Services)
- Register or log in to AWS Management Console;
- Create a new Lambda function through the AWS console, selecting API Gateway as the trigger;
- Upload your bot's code into the Lambda function;
- Configure the API Gateway to interact with your bot and the outside world.
Heroku
- Create an account on Heroku;
- Install Heroku CLI and log in;
- Create a new Heroku app through the console or using the command heroku create;
- Link your Git repository to Heroku and perform deployment with the commands git push heroku master;
- Set the webhook URL provided by Heroku.