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

API сообщений

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

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

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

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

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

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

curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "whatsapp_client": 678,
    "msg_type": 0,
    "country_code": "91",
    "phone": "9876543210",
    "msg": "Hi Aman, your order #4821 has shipped and will arrive on Thursday."
  }'

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

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

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

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

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

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

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

whatsapp_clientintegerОбязателен, если у вас больше одного номера

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

Получатель и сообщение

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

Номер WhatsApp получателя, только цифры. Пробелы, +, -, . и скобки удаляются автоматически. Передайте номер либо с кодом страны (919876543210), либо без него (9876543210) вместе с country_code. В полях формы не указывайте ведущий 0 междугородного префикса (09876543210): он не удаляется перед добавлением country_code, поэтому сообщение уйдёт не на тот номер. В JSON-запросах он удаляется автоматически.

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

Телефонный код страны без +, например 91 для Индии или 1 для США. Он добавляется перед phone, если номер ещё не начинается с него. Исключение: с кодом 91 к 10-значному номеру префикс добавляется всегда. С другими кодами местный номер, который начинается с тех же цифр, префикс не получает, поэтому передавайте такой номер уже с кодом страны.

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

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

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

Текст сообщения, до 3000 символов. Для изображений и файлов это подпись, она может быть пустой. Форматирование 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необязательно

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

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

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

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

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

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

Отправка изображений и файлов#

Ограничения на загрузку по img_url и file_url:

  • URL должен быть публичным: http или https, доступный из интернета. Выполняется до 5 перенаправлений, и каждое из них тоже должно вести на публичный адрес.
  • Файлы по ссылке могут быть размером до 100 МБ. Сервер должен начать отвечать в течение 45 секунд и не зависать дольше этого времени.
  • Файл скачивается в момент вызова API, поэтому нерабочая ссылка сразу приводит к ошибке Invalid file url.

Поддерживаемые расширения: .pdf, .xlsx, .xls, .txt, .docx, .png, .jpg, .jpeg, .webp, .mp3, .mpga, .m4a, .mp4, .webm.

Эти проверки выполняются при отправке сообщения, а не при вызове API, поэтому такие ошибки видны только в API статуса сообщений и в webhook:

Проблемаerror в статусе сообщения
Изображение (msg_type 1) больше 16 МБFile exceeds WhatsApp size limit (16MB max)
Видео (.mp4, .webm) больше 64 МБ или пустой файлFile exceeds WhatsApp size limit (…)
Файл .ogg или файл .wav, отправленный как изображение (msg_type 1)File type not supported

Аудио WAV и OGG не поддерживается. Файл .wav, отправленный как файл (msg_type 2), не отклоняется, но приходит как recording.wav.pdf. Сначала преобразуйте аудио в .mp3 или .m4a.

Изображение по URL
curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "whatsapp_client": 678,
    "msg_type": 1,
    "country_code": "91",
    "phone": "9876543210",
    "img_url": "https://example.com/offers/diwali-sale.jpg",
    "msg": "Our Diwali sale starts today 🎉"
  }'
Загрузка файла
curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -F client_id=12345 \
  -F api_key=YOUR_API_KEY \
  -F whatsapp_client=678 \
  -F msg_type=2 \
  -F country_code=91 \
  -F phone=9876543210 \
  -F "msg=Your invoice for order #4821 is attached." \
  -F file_name=invoice-4821.pdf \
  -F file=@./invoice-4821.pdf

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

Клиенты для Python и Node.js вызывают этот endpoint за вас.

from wbiztool_client import WbizToolClient

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

result = client.send_message(
    phone="9876543210",
    country_code="91",
    msg="Hi Aman, your order #4821 has shipped.",
    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, равным 0Account Disabled нет поля status):

{ "status": 0, "message": "Msg 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.
Either phone or group_name parameter is requiredДобавьте phone.
Please provide either phone OR group_name, not bothУдалите один из параметров.
Invalid phone numberphone должен содержать только цифры (от 6 до 17), в начале допускается +.
Invalid Contact Number "…"Вместе с кодом страны номер должен содержать от 6 до 15 цифр.
Msg cant be nullДля текстовых сообщений (msg_type 0) нужен msg.
Message length is too longДлина msg не должна превышать 3000 символов.
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Этого 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.

Сообщение, поставленное в очередь, всё ещё может не отправиться, например с ошибкой File exceeds WhatsApp size limit (…). Такие ошибки никогда не появляются в этом ответе. См. Отправка изображений и файлов и проверяйте API статуса сообщений.

Webhook#

Если вы передали webhook, Wbiztool отправляет POST на этот URL, когда сообщение отправлено или не удалось его отправить. Тело запроса передаётся в виде полей формы (application/x-www-form-urlencoded), а не JSON:

msg_id=9817263&status=SENT
ПолеЗначения
msg_idmsg_id, полученный при отправке сообщения.
statusSENT или FAILED

Ответьте любым кодом 2xx. Если ваш endpoint не отвечает вовремя (дольше 3 секунд) или возвращает 5xx, вызов повторяется — всего до 3 попыток. Ответ 4xx не повторяется. При отмене или истечении срока сообщения webhook не отправляется; в этих случаях используйте Статус сообщения.

Советы#

  • Номера телефонов: храните номера в международном формате и передавайте их вместе с country_code, чтобы избежать неоднозначности.
  • Переводы строк в JSON: записывайте их как \n внутри msg. Непосредственный перенос строки делает JSON некорректным.
  • Держите номер подключённым: сообщения отправляются с вашего номера WhatsApp, поэтому он должен оставаться подключённым в настройках WhatsApp.
  • Много получателей: чтобы отправить одно и то же сообщение на несколько номеров одним запросом, используйте Отправку на несколько номеров. Для крупных кампаний загрузите таблицу на странице Кампании.