Перейти к содержимому
Wbiztool

API сообщений

API отправки сообщений в группу WhatsApp

Отправляйте текст, изображение или документ WhatsApp в группу WhatsApp, участником которой является ваш подключённый номер. Подходит для объявлений для команды, новостей сообщества и массовых уведомлений.

POSThttps://wbiztool.com/api/v1/send_msg/group/

Тело запроса: JSON, поля формы или multipart/form-data при загрузке файла

Сообщение ставится в очередь и отправляется в группу с вашего номера WhatsApp. В ответе вы получаете msg_id, по которому можно проверить его статус.

Быстрый пример#

curl -X POST https://wbiztool.com/api/v1/send_msg/group/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "whatsapp_client": 678,
    "msg_type": 0,
    "group_name": "Sales Team Mumbai",
    "msg": "Reminder: *weekly review* starts at 4 PM today."
  }'

Замените 12345, YOUR_API_KEY и 678 своими значениями. Где их найти, описано в разделе Аутентификация.

Параметры запроса#

Аутентификация

client_idintegerобязательно

Ваш API Client ID из раздела Настройки → API ключи.

api_keystringобязательно

Ваш API-ключ с той же страницы.

whatsapp_clientintegerОбязателен, если у владельца больше одного подключённого номера

ID номера WhatsApp, с которого отправляется сообщение, со страницы настроек WhatsApp. Номер должен принадлежать владельцу рабочего пространства. Если вы его не передадите, а у владельца ровно один подключённый номер, будет использован этот номер.

Группа и сообщение

group_namestringобязательно

Название группы WhatsApp — точно так, как оно отображается в WhatsApp. Передавайте его строкой. Число JSON, например 2024, возвращает HTML-страницу ошибки (HTTP 500). См. раздел Как ищется группа.

msg_typeintegerнеобязательно

0 — текст (по умолчанию), 1 — изображение, 2 — файл или документ.

msgstringОбязателен, если msg_type равен 0

Текст сообщения. Для изображений и файлов это подпись, она может быть пустой. Форматирование WhatsApp работает: *bold*, _italic_, ~strikethrough~. В качестве псевдонима принимается message.

Изображения и файлы

img_urlstringОбязателен, если msg_type равен 1 и файл не загружается

Публичный URL изображения (http или https).

file_urlstringОбязателен, если msg_type равен 2 и файл не загружается

Публичный URL (http или https), по которому файл можно скачать напрямую.

filefileнеобязательно

Загрузите изображение или файл вместо указания URL. Отправьте запрос как multipart/form-data с полем file.

file_namestringнеобязательно

Имя файла, которое увидят участники группы, например price-list.pdf. От расширения зависит, как будет отправлен файл, поэтому обязательно укажите его. Отправляется в нижнем регистре, символы вроде & : ? * $ ; заменяются на _, а длина обрезается до 150 символов. Если параметр не передан, имя берётся из URL или загруженного файла.

Параметры доставки

expire_after_secondsintegerнеобязательно

Пометить сообщение как просроченное (статус 4), если оно не было отправлено в течение указанного числа секунд, например 3600 — один час. Это делает фоновая задача не раньше чем через 30 секунд после срока, поэтому не полагайтесь на неё для сроков меньше минуты.

webhookstringнеобязательно

URL, на который приходит POST, когда сообщение отправлено или не удалось его отправить. Содержимое запроса такое же, как в API отправки сообщений.

Для изображений и файлов действуют те же правила, что и в API отправки сообщений: файлы по URL скачиваются в момент вызова API (до 100 МБ). При отправке сообщения изображения больше 16 МБ и видео больше 64 МБ не проходят, аудио WAV и OGG не поддерживается, а к файлам (msg_type 2) без поддерживаемого расширения добавляется .pdf, в том числе к загруженным. Имена файлов отправляются в нижнем регистре. Полный список расширений и ошибок — в разделе Отправка изображений и файлов.

Чтобы загрузить файл, используйте примеры multipart из раздела API отправки сообщений, заменив URL на /api/v1/send_msg/group/, а phone/country_code — на group_name.

Изображение по URL
curl -X POST https://wbiztool.com/api/v1/send_msg/group/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "whatsapp_client": 678,
    "msg_type": 1,
    "group_name": "Sales Team Mumbai",
    "img_url": "https://example.com/reports/weekly-sales.png",
    "msg": "This week'\''s sales summary"
  }'

Как ищется группа#

При вызове API Wbiztool не проверяет название группы. Во время отправки сообщения Wbiztool ищет group_name в ваших чатах WhatsApp и открывает первый результат. Поэтому:

  • Ваш подключённый номер WhatsApp должен быть участником группы.
  • Используйте полное название группы точно так, как его показывает WhatsApp, включая эмодзи и знаки препинания. Пробелы в начале и в конце игнорируются.
  • Название должно быть уникальным. Короткое или неполное название может совпасть с другим чатом, который окажется первым в результатах поиска.
  • Если совпадений нет, если отправлять сообщения в группе могут только администраторы, а ваш номер не администратор, или если публиковать могут только администраторы сообщества, сообщение завершится ошибкой Group not found.
  • Если ваш номер вышел из группы, сообщение завершится ошибкой Group member blocked.

Проблемы с группой не видны в ответе API. Чтобы узнать, было ли сообщение отправлено, используйте webhook или Статус сообщения.

Использование официального клиента#

Python-клиент вызывает этот endpoint за вас.

Python
from wbiztool_client import WbizToolClient

client = WbizToolClient(api_key="YOUR_API_KEY", client_id=12345)

result = client.send_message_to_group(
    group_name="Sales Team Mumbai",
    msg="Reminder: weekly review starts at 4 PM today.",
    whatsapp_client=678,
)
print(result)

При ошибках выбрасывается requests.HTTPError. Причину можно прочитать через e.response.json()["message"].

Ответ#

Успешный запрос возвращает HTTP 200:

{
  "status": 1,
  "message": "Created",
  "msg_id": 9817263
}
ПолеТипОписание
statusinteger1, если сообщение поставлено в очередь, 0, если запрос не выполнен.
messagestringCreated при успехе, иначе текст ошибки.
msg_idintegerID сообщения в очереди. Сохраните его, чтобы позже проверить статус. Присутствует только при успехе.

"status": 1 означает, что сообщение поставлено в очередь, а не что оно уже дошло до группы. Чтобы убедиться, что оно отправлено, используйте webhook или Статус сообщения.

Ошибки#

Ошибки возвращаются с HTTP 400 и status, равным 0:

{ "status": 0, "message": "Group Name cant be null" }
СообщениеКак исправить
Auth Error - Please send correct API key and Client idПередайте непустой api_key.
Invalid client id.Передайте client_id числом.
Auth Error: invalid api keyПроверьте, что ключ существует, не удалён и принадлежит этому client_id.
Group Name cant be nullДобавьте group_name.
Msg cant be nullДля текстовых сообщений (msg_type 0) нужен msg.
Image Url Can't be nullДля msg_type 1 передайте img_url или загрузите file.
File Url Can't be nullДля msg_type 2 передайте file_url или загрузите file.
Invalid file url, Can't download / Invalid file urlURL не публичный, истекло время ожидания или файл больше 100 МБ.
Invalid whatsapp client NoneЭтот ID whatsapp_client не принадлежит владельцу рабочего пространства. См. предупреждение выше.
Invalid whatsapp client id.Передайте whatsapp_client. Он обязателен, если только у владельца не ровно один подключённый номер.
Not enough creditsВ вашем тарифе закончились сообщения.
Demo Account can not access apisИспользуйте обычный аккаунт.
Account DisabledВаш аккаунт отключён. Свяжитесь с поддержкой.
Invalid JSON format: …Тело JSON некорректно — часто из-за лишней запятой в конце или неэкранированного перевода строки в msg. Для новой строки используйте \n.

Советы#

  • Сначала проверьте название: отправьте в группу короткий текст и проверьте Статус сообщения, прежде чем что-либо автоматизировать.
  • Переименованные группы: если кто-то переименует группу в WhatsApp, обновите group_name и в вашей интеграции.
  • Типы сообщений: для msg_type допустимы только значения 0, 1 и 2. Любое значение, которое не является целым числом, возвращает HTML-страницу ошибки (HTTP 500) вместо JSON.
  • Несколько групп сразу: Отправка на несколько номеров принимает в одном запросе названия групп вперемешку с номерами телефонов.