API сообщений
API отправки сообщений
Отправляйте текст, изображение или документ WhatsApp на один номер телефона со своего подключённого номера WhatsApp. Подходит для подтверждений заказов, напоминаний об оплате, уведомлений и ответов службы поддержки.
https://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."
}'import requests
response = requests.post(
"https://wbiztool.com/api/v1/send_msg/",
json={
"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.",
},
timeout=60,
)
result = response.json() # read the body even when the HTTP code is 400
if result.get("status") == 1:
print("Queued with msg_id", result["msg_id"])
else:
print("Failed:", result.get("message"))// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v1/send_msg/", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
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.",
}),
});
const result = await response.json(); // read the body even when the HTTP code is 400
if (result.status === 1) {
console.log("Queued with msg_id", result.msg_id);
} else {
console.error("Failed:", result.message);
}<?php
$payload = [
'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.',
];
$ch = curl_init('https://wbiztool.com/api/v1/send_msg/');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
if (($result['status'] ?? 0) === 1) {
echo 'Queued with msg_id ' . $result['msg_id'];
} else {
echo 'Failed: ' . ($result['message'] ?? 'no response');
}Замените 12345, YOUR_API_KEY и 678 своими значениями. Где их найти, описано в разделе Аутентификация.
Параметры запроса#
Аутентификация
client_idintegerобязательноВаш API Client ID из раздела Настройки → API ключи.
api_keystringобязательноВаш API-ключ с той же страницы.
whatsapp_clientintegerОбязателен, если у вас больше одного номераID номера WhatsApp, с которого отправляется сообщение, со страницы настроек WhatsApp. Если вы его не передадите, а в вашем рабочем пространстве ровно один подключённый номер, будет использован этот номер.
Получатель и сообщение
phonestringобязательноНомер WhatsApp получателя. Пробелы,
+,-,., скобки и00в начале удаляются автоматически, поэтому+91 98765-43210подойдёт. Значения из таблиц, например919876543210.0и9.19876543210E+11, читаются как их цифры, а округлённое, например9.19877E+11, отклоняется, потому что в нём не хватает цифр. Передайте номер либо с кодом страны (919876543210), либо без него (9876543210) вместе сcountry_code. Местный номер с ведущим0тоже работает:09876543210сcountry_code91уходит на919876543210, а0612345678с39(Италия, где0— часть номера) — на390612345678. Не пишите(0)в скобках после кода страны:+44 (0)20 7946 0018читается как4402079460018и уходит не на тот номер. Пишите+44 20 7946 0018.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.
Файлы, отправленные с msg_type 2, сохраняют эти расширения:
| Категория | Расширения |
|---|---|
| Изображения | .jpg, .jpeg, .jpe, .png, .gif, .webp, .bmp |
| Документы | .pdf, .doc, .docx, .docm, .xls, .xlsx, .xlsm, .xlsb, .ppt, .pptx, .pptm, .txt, .csv |
| Аудио | .mp3, .mpga, .m4a, .aac, .wav, .ogg, .oga |
| Видео | .mp4, .mov, .avi, .webm |
| Архивы | .zip, .rar |
Эти проверки выполняются при отправке сообщения, а не при вызове API, поэтому такие ошибки видны только в API статуса сообщений и в webhook:
| Проблема | error в статусе сообщения |
|---|---|
Изображение (msg_type 1) больше 16 МБ | File exceeds WhatsApp size limit (16MB max) |
Видео (.mp4, .webm) больше 64 МБ, в том числе отправленное как изображение (msg_type 1) | File exceeds WhatsApp size limit (64MB max) |
Любой другой файл (msg_type 2) больше 100 МБ | File exceeds WhatsApp size limit (100MB max) |
| Пустой файл (0 байт) | The file is empty |
Файл .wav или .ogg, отправленный как изображение (msg_type 1) | File type not supported |
Аудио WAV и OGG нельзя отправить как изображение (msg_type 1). Отправленные как файл (msg_type 2), они приходят как документ под своим именем, например recording.wav. Файлы .mp3, .mpga, .m4a и .aac приходят как аудио, которое воспроизводится в чате, а msg идёт следом отдельным текстовым сообщением (у аудио нет подписи).
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 🎉"
}'import requests
response = requests.post(
"https://wbiztool.com/api/v1/send_msg/",
json={
"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 🎉",
},
timeout=60,
)
print(response.json())// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v1/send_msg/", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
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 🎉",
}),
});
console.log(await response.json());<?php
$ch = curl_init('https://wbiztool.com/api/v1/send_msg/');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode([
'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 🎉',
]),
CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch);
curl_close($ch);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.pdfimport requests
with open("invoice-4821.pdf", "rb") as f:
response = requests.post(
"https://wbiztool.com/api/v1/send_msg/",
data={
"client_id": 12345,
"api_key": "YOUR_API_KEY",
"whatsapp_client": 678,
"msg_type": 2,
"country_code": "91",
"phone": "9876543210",
"msg": "Your invoice for order #4821 is attached.",
"file_name": "invoice-4821.pdf",
},
files={"file": f},
timeout=120,
)
print(response.json())// Node.js 20+ (built-in fetch, FormData and fs.openAsBlob). Save as .mjs to use top-level await.
import { openAsBlob } from "node:fs";
const form = new FormData();
form.append("client_id", "12345");
form.append("api_key", "YOUR_API_KEY");
form.append("whatsapp_client", "678");
form.append("msg_type", "2");
form.append("country_code", "91");
form.append("phone", "9876543210");
form.append("msg", "Your invoice for order #4821 is attached.");
form.append("file_name", "invoice-4821.pdf");
form.append("file", await openAsBlob("./invoice-4821.pdf"), "invoice-4821.pdf");
// Don't set Content-Type yourself; fetch adds the multipart boundary.
const response = await fetch("https://wbiztool.com/api/v1/send_msg/", { method: "POST", body: form });
console.log(await response.json());<?php
$ch = curl_init('https://wbiztool.com/api/v1/send_msg/');
curl_setopt_array($ch, [
CURLOPT_POST => true,
// An array body (not json_encode) makes cURL send multipart/form-data.
CURLOPT_POSTFIELDS => [
'client_id' => 12345,
'api_key' => 'YOUR_API_KEY',
'whatsapp_client' => 678,
'msg_type' => 2,
'country_code' => '91',
'phone' => '9876543210',
'msg' => 'Your invoice for order #4821 is attached.',
'file_name' => 'invoice-4821.pdf',
'file' => new CURLFile('/path/to/invoice-4821.pdf', 'application/pdf', 'invoice-4821.pdf'),
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 120,
]);
echo curl_exec($ch);
curl_close($ch);Использование официальных клиентов#
Клиенты для 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"].
const { WbizToolClient } = require("wbiztool-client");
const client = new WbizToolClient({
clientId: 12345,
apiKey: "YOUR_API_KEY",
whatsappClient: 678,
});
(async () => {
// Errors throw, with the API's response in the error message.
const result = await client.sendMessage({
phone: "9876543210",
countryCode: "91",
message: "Hi Aman, your order #4821 has shipped.",
});
console.log(result);
})().catch(console.error);Ответ#
Успешный запрос возвращает HTTP 200:
{
"status": 1,
"message": "Created",
"msg_id": 9817263
}
| Поле | Тип | Описание |
|---|---|---|
status | integer | 1, если сообщение поставлено в очередь, 0, если запрос не выполнен. |
message | string | Created при успехе, иначе текст ошибки. |
msg_id | integer | ID сообщения в очереди. Сохраните его, чтобы позже проверить статус. Присутствует только при успехе. |
"status": 1 означает, что сообщение поставлено в очередь, а не что оно уже дошло до получателя. Чтобы убедиться, что оно отправлено, используйте webhook или Статус сообщения.
Ошибки#
Ошибки возвращаются с HTTP 400 и status, равным 0 (у Account 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 number | phone должен быть номером из 6–17 цифр. Буквы и другие символы не допускаются, как и округлённое значение из таблицы, например 9.19877E+11. |
Invalid Contact Number "…" | Вместе с кодом страны номер должен содержать от 6 до 15 цифр. Номер из 6 цифр принимается, но при отправке завершается ошибкой. |
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 url | URL не публичный, истекло время ожидания или файл больше 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_id | msg_id, полученный при отправке сообщения. |
status | SENT или FAILED |
Ответьте любым кодом 2xx. Если ваш endpoint не отвечает вовремя (дольше 3 секунд) или возвращает 5xx, вызов повторяется — всего до 3 попыток. Ответ 4xx не повторяется. При отмене или истечении срока сообщения webhook не отправляется; в этих случаях используйте Статус сообщения.
Советы#
- Номера телефонов: храните номера в международном формате и передавайте их вместе с
country_code, чтобы избежать неоднозначности. - Переводы строк в JSON: записывайте их как
\nвнутриmsg. Непосредственный перенос строки делает JSON некорректным. - Держите номер подключённым: сообщения отправляются с вашего номера WhatsApp, поэтому он должен оставаться подключённым в настройках WhatsApp.
- Много получателей: чтобы отправить одно и то же сообщение на несколько номеров одним запросом, используйте Отправку на несколько номеров. Для крупных кампаний загрузите таблицу на странице Кампании.
