Введение
Для кого это руководство:
- Разработчикам и инженерам, внедряющим функции WhatsApp в CRM, SaaS или кастомные бизнес-системы;
- No-code интеграторам и специалистам по автоматизации, использующим Make, Zapier или n8n;
Примеры использования:
- Автоматически создавать выделенные группы поддержки или чаты онбординга клиентов;
- Синхронизировать списки участников групп с этапами сделок в CRM;
- Рассылать транзакционные объявления и уведомления в групповые чаты;
- Подключать интерактивных чат-ботов к групповым обсуждениям;
Что потребуется:
- Активный стандартный номер WhatsApp (обычное личное или бизнес-приложение, не официальный WABA);
- Базовые знания HTTP-запросов или доступ к low-code платформе автоматизации;
Возможности управления группами WhatsApp через API
- Отправка сообщений в группы: Рассылайте обновления, анонсы или напоминания напрямую в любую группу.
- Создание новых групп WhatsApp: Автоматически создавайте группы для новых клиентов или участников курсов.
- Добавление участников в группу: Приглашайте контакты в группу программно, без ручного подтверждения.
- Назначение администраторов: Делайте участников администраторами или снимайте права админа.
- Получение списка участников: Получайте полный список членов группы для аналитики или синхронизации с CRM.
- Отслеживание событий в группе: Реагируйте на сообщения, входы и выходы через webhook.
- Подключение ботов к группам: Позвольте ботам читать и отвечать на сообщения в группе по заданной логике.
Почему официальный API групп от Meta* не подходит для большинства компаний
| Лимиты функций | Официальный API WhatsApp Business | Шлюз Whapi.Cloud |
|---|---|---|
| Лимит участников группы | Строго ограничен 8 участниками | До 1024 участников (стандартный лимит WhatsApp) |
| Барьер верификации | Требуется верификация бизнеса в Meta* и синяя галочка (OBA) | Верификация не требуется; подключите любой активный номер |
| Скорость подключения | Дни или недели проверок заявок | Менее двух минут путем быстрого сканирования QR-кода |
| Структура расходов | Тарификация за каждую сессию | Предсказуемая фиксированная ежемесячная подписка |
| Медиафайлы и действия | Только базовые шаблонные сообщения | Полный доступ к группам, каналам, статусам и каталогам |
Как подключить WhatsApp и начать работу с API
- 1) Перейдите в личный кабинет и откройте Default Channel — он уже создан.
- 2) На шаге 1 появится QR-код с инструкциями.
- 3) На телефоне откройте WhatsApp → Настройки → Связанные устройства → Привязать устройство, затем отсканируйте QR-код.
- 4) После подключения дайте каналу имя (например, "Мой чат-бот") для удобства.
- 5) Вы попадёте на страницу настроек канала — этот шаг можно пропустить и вернуться позже.
Как отправлять сообщения в группы WhatsApp через API (с примерами кода)
[email protected]. Они не видны в мобильном или веб-приложении — получайте их с помощью запроса GET /groups перед отправкой сообщений.- 1) Сначала получите ID группы. Используйте endpoint
GET /groupsдля получения списка ваших групп WhatsApp с их уникальными идентификаторами. Подробнее — Get groups. - 2) Получив ID группы, отправьте сообщение. Автоматически создавайте новые группы по событиям (например, новый клиент). Используйте endpoint
POST /messages/text, указывая ID группы в параметреtoи текст сообщения вbody. Подробнее — Send text message.
Получить ID можно через endpoint Get groups или просмотрев недавние чаты через chats endpoint.
- 1) При создании группы ID будет в ответе API. Пример ниже;
- 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);
Отправка медиафайлов и документов в группы
POST /messages/image или POST /messages/document.to, прямую ссылку на файл в поле media и необязательное описание в поле 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);
Как отправлять сообщения в группы WhatsApp с помощью no-code инструментов (Make, n8n)
GET https://gate.whapi.cloud/groups
POST https://gate.whapi.cloud/messages/text to: ID группы.body: текст сообщения
Как создать группу WhatsApp через API
participants.- 1) Используйте
POSTзапрос кhttps://gate.whapi.cloud/groupsдля создания новой группы. Укажите название группы в параметре subject и хотя бы один номер в participants — это обязательно для успешного создания. - 2) После успешного создания API вернёт ID группы. Он потребуется для отправки сообщений.
- 3) Для отправки сообщений используйте стандартный метод, указывая ID группы в
toи текст вbody.
participants для гарантии.
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);
Как создать группу WhatsApp через no-code платформу
https://gate.whapi.cloud/groups с параметрами subject (название) и participants (массив номеров).{
"participants": [
"498935516106",
"4915155985667"
],
"subject": "SEO Common GmbH"
}
Как добавить участников в группу WhatsApp
- 1) Получите ID группы, в которую хотите добавить участников. Это обязательный параметр. Как получить ID — выше.
- 2) Отправьте
POSTзапрос наhttps://gate.whapi.cloud/groups/{GroupID}/participantsдля добавления новых участников. В URL укажите ID группы, а в теле — массив номеров.
Прямое добавление участников vs Ссылки-приглашения
POST /groups/{GroupID}/participants добавляет пользователей мгновенно. Сценарии со ссылками часто теряют значительную часть клиентов, которые просто не завершают процесс вступления.GET /groups/{GroupID}/invite и отправьте ее пользователю в личном сообщении.
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);
Как добавить участников в группу WhatsApp с помощью no-code инструментов
https://gate.whapi.cloud/groups/[email protected]/participants.@ на %40.{
"participants": [
"373983445541",
"373983445542",
"373983445543"
]
}
Реальная no-code автоматизация: автосоздание групп поддержки (Make и n8n)
- Создание группы: запрос
POST /groupsс темой вида "Поддержка клиентов: Название компании" и номером вашего бота. - Добавление участников: запрос
POST /groups/{groupId}/participantsс номерами клиента и ответственного менеджера. - Отправка приветствия: запрос
POST /messages/imageилиPOST /messages/textс приветственным баннером или инструкциями по онбордингу.
| Путь автоматизации | Когда выбирать | Ключевые преимущества |
|---|---|---|
| Make / n8n (No-Code) | Быстрое прототипирование и операции малого и среднего бизнеса. | Визуальная отладка, готовые коннекторы, отсутствие затрат на обслуживание сервера. |
| Собственный код (Node.js / Python) | Высоконагруженные корпоративные приложения и сложная синхронизация баз данных. | Более низкая стоимость выполнения, полная обработка ошибок, неограниченная масштабируемость. |
Как получить список участников группы WhatsApp через API
- 1) Убедитесь, что вы участник нужной группы. Без этого получить список не получится.
- 2) Используйте API-метод Get Groups для получения всех групп вашего аккаунта. Если знаете ID, вызовите Get group напрямую.
- 3) В ответе будет массив групп с ID, названием и полем participants — список участников. Пример ответа:
{
"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);
Как получить участников группы WhatsApp через no-code
GET запрос к https://gate.whapi.cloud/groups для получения всех групп, где вы участник, с деталями по каждой — включая участников.GET https://gate.whapi.cloud/groups/{GroupID} для получения данных по конкретной группе.Как подключить бота к группе WhatsApp
- Создание бота WhatsApp на Node.js;
- Создание бота WhatsApp на Python;
- Создание бота WhatsApp на PHP;
- Создание бота WhatsApp на Java;
chat_id (формат [email protected]), а поле from покажет номер отправителя внутри группы.Советы, ограничения и лучшие практики
- Не добавляйте пользователей в группы без их согласия. Соблюдайте приватность и избегайте нежелательных приглашений;
- Не рассылайте спам — это может привести к блокировке или бану аккаунта;
- Whapi.Cloud не накладывает строгих ограничений на частоту API-запросов на платных тарифах, но WhatsApp может пометить аккаунты, отправляющие более ~20 сообщений в минуту без истории прогрева. Используйте естественные интервалы отправки и случайные задержки в 1.5–3.5 секунды между действиями.
PATCH /groups/{GroupID}/admins сразу после создания группы. Если основной бот отключится, резервный администратор сможет заново добавить и повысить нового бота. Подробнее см. в руководстве 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);
Устранение неполадок
Бот не реагирует на входящие сообщения
- Убедитесь, что вы отправляете сообщения на номер, на котором запущен бот, с другого телефона. Бот не сможет реагировать на сообщения, отправленные с того же номера.
- Если бот не реагирует на сообщения с других номеров, проверьте работу вебхуков. Используйте сервисы для симуляции вебхуков, например, Webhook.site, чтобы удостовериться, по какому пути приходят callback запросы. После этого проверьте соответствует ли путь, указанному вами в конфигурации. Так же, убедитесь, что ваш сервер отвечает 200Ok.
Бот отправляет сообщения без остановки
Обработка вебхуков и типичные проблемы автоматизации групп
message_created или group_updated. Проверяйте chat_id, оканчивающийся на @g.us, чтобы отличать групповой трафик от личных чатов.
- Бесконечный цикл бота: проверяйте флаг
from_me— без этого бот может начать бесконечно отвечать на собственные сообщения. - Ошибка Permission denied: бот должен иметь статус администратора группы, чтобы добавлять участников — проверьте его статус через
GET /groups/{GroupID}. - Отсутствие участников в списке: фоновая синхронизация метаданных группы может занимать до 15 секунд после создания, прежде чем все номера участников станут доступны.
Не удаётся добавить пользователя в группу?
- Вы должны быть администратором группы. Только админы могут добавлять новых участников.
- Пользователь мог ограничить приглашения в группы настройками приватности. В этом случае добавить его через API не получится.
- Группа достигла лимита в 1024 участника. Удалите неактивных или создайте новую группу.
- Антиспам-фильтры WhatsApp могут блокировать добавление определенных номеров в группы — особенно если контакт не сохранен в вашей телефонной книге или не взаимодействовал с вами. Чтобы снизить этот риск, мы настоятельно рекомендуем сначала программно добавить контакт в список с помощью нашего API добавления контактов.
Сообщение не доставлено?
- Проверьте ID группы — неверный или устаревший ID приведёт к ошибке доставки.
- Если сообщение отправлено, но не видно в группе, проверьте формат. Например, группы WhatsApp могут не отображать некоторые типы контента (webp, интерактивные кнопки).
Доступ запрещён?
- Ваш номер не распознан как администратор группы.
- API мог не синхронизировать ваш статус администратора или номер. В таком случае попробуйте повторно авторизовать канал для обновления прав.
Участники группы не отображаются?
GET /groups или GET /group запроса данные ставятся в очередь на синхронизацию.Что означает @lid в списке участников?
@lid вместо обычных номеров JID, разрешайте их для сопоставления в CRM с помощью запросов GET /contacts/lids или GET /contacts/ids/{ContactLID}. Подробнее см. в статье о разрешении анонимных идентификаторов @lid.// 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);
Деплой и использование серверов
Firebase
- Создайте проект в Firebase Console;
- Установите Firebase CLI, следуя инструкциям;
- Инициализируйте Firebase в директории вашего проекта с помощью команды firebase init;
- Разверните вашего бота, используя команду firebase deploy --only functions.
AWS (Amazon Web Services)
- Зарегистрируйтесь или войдите в AWS Management Console;
- Создайте новую функцию Lambda через консоль AWS, выбрав в качестве триггера API Gateway;
- Загрузите код вашего бота в Lambda функцию;
- Настройте API Gateway для взаимодействия вашего бота с внешним миром.
Heroku
- Создайте аккаунт на Heroku;
- Установите Heroku CLI и войдите в систему;
- Создайте новое приложение на Heroku через консоль или используя команду heroku create;
- Свяжите ваш Git репозиторий с Heroku и выполните деплой с помощью команд git push heroku master;
- Установите URL вебхука, предоставленный Heroku.