API сообщений
API статуса сообщений
Проверьте, находится ли сообщение, отправленное через API, ещё в очереди, отправлено ли оно или завершилось ошибкой. Используйте этот API, чтобы убедиться, что важные сообщения ушли, и выяснить, почему какое-то из них не отправилось.
https://wbiztool.com/api/v1/message/status/{msg_id}/Тело запроса: JSON или поля формы
Укажите ID сообщения в URL, заменив {msg_id} значением msg_id, которое вернул API отправки сообщений, отправки в группу, отправки на несколько номеров или планирования сообщений. Например: https://wbiztool.com/api/v1/message/status/9817263/.
Быстрый пример#
curl -X POST https://wbiztool.com/api/v1/message/status/9817263/ \
-H "Content-Type: application/json" \
-d '{
"client_id": 12345,
"api_key": "YOUR_API_KEY"
}'import requests
msg_id = 9817263
response = requests.post(
f"https://wbiztool.com/api/v1/message/status/{msg_id}/",
json={
"client_id": 12345,
"api_key": "YOUR_API_KEY",
},
timeout=60,
)
result = response.json() # read the body even when the HTTP code is 400
if result.get("message") == "Unknown message id":
print("No message with this ID in your workspace")
elif "status_text" not in result:
print("Request failed:", result.get("message", "no message in response"))
elif result["status"] == 1:
print("Sent")
elif result["status"] == 2:
print("Failed:", result["error"])
else:
print("Status:", result["status_text"])// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const msgId = 9817263;
const response = await fetch(`https://wbiztool.com/api/v1/message/status/${msgId}/`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
client_id: 12345,
api_key: "YOUR_API_KEY",
}),
});
const result = await response.json(); // read the body even when the HTTP code is 400
if (result.message === "Unknown message id") {
console.log("No message with this ID in your workspace");
} else if (!("status_text" in result)) {
console.error("Request failed:", result.message ?? "no message in response");
} else if (result.status === 1) {
console.log("Sent");
} else if (result.status === 2) {
console.log("Failed:", result.error);
} else {
console.log("Status:", result.status_text);
}<?php
$msgId = 9817263;
$payload = [
'client_id' => 12345,
'api_key' => 'YOUR_API_KEY',
];
$ch = curl_init("https://wbiztool.com/api/v1/message/status/{$msgId}/");
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['message'] ?? '') === 'Unknown message id') {
echo 'No message with this ID in your workspace';
} elseif (!isset($result['status_text'])) {
echo 'Request failed: ' . ($result['message'] ?? 'no message in response');
} elseif ($result['status'] === 1) {
echo 'Sent';
} elseif ($result['status'] === 2) {
echo 'Failed: ' . $result['error'];
} else {
echo 'Status: ' . $result['status_text'];
}Замените 12345 и YOUR_API_KEY своими значениями. Где их найти, описано в разделе Аутентификация.
Параметры запроса#
URL
msg_idintegerобязательноID сообщения как часть пути URL. Он должен быть целым числом и принадлежать рабочему пространству вашего API-ключа.
Тело запроса
client_idintegerобязательноВаш API Client ID из раздела Настройки → API ключи.
api_keystringобязательноВаш API-ключ с той же страницы.
Использование официального клиента#
Python-клиент вызывает этот endpoint за вас.
from wbiztool_client import WbizToolClient
client = WbizToolClient(api_key="YOUR_API_KEY", client_id=12345)
result = client.get_message_status(msg_id=9817263)
print(result.get("status_text"), result.get("error"))Клиент возвращает те же поля, что и API, поэтому result["status"] — это состояние сообщения, а не признак успеха. При ошибках аутентификации выбрасывается requests.HTTPError; причину можно прочитать через e.response.json()["message"].
Ответ#
Endpoint возвращает HTTP 200 с текущим состоянием сообщения:
{
"message": "Sent",
"status": 1,
"status_text": "Sent",
"error": ""
}
Сообщение, отправка которого завершилась ошибкой:
{
"message": "Failed",
"status": 2,
"status_text": "Failed",
"error": "Phone number invalid"
}
| Поле | Тип | Описание |
|---|---|---|
status | integer | Код статуса сообщения. См. таблицу ниже. |
status_text | string | Название статуса: Created, Sent, Failed, Cancelled или Expired. |
message | string | То же значение, что и status_text. |
error | string or null | Причина ошибки отправки. Присутствует всегда; пустое ("" или null), если ошибки нет. |
Значения статуса#
status | status_text | Значение |
|---|---|---|
0 | Created | В очереди или запланировано, ожидает отправки. |
1 | Sent | Отправлено с вашего номера WhatsApp. |
2 | Failed | Не удалось отправить, или отправка была прервана. Причина указана в error. Если error равно Sending was interrupted and may have been delivered. Check WhatsApp before resending., у получателя сообщение, возможно, уже есть, поэтому не отправляйте его повторно автоматически. |
3 | Cancelled | Отменено до отправки, например через API отмены сообщений. |
4 | Expired | Не отправлено до истечения срока expire_after_seconds. |
Sent — конечный статус успешной отправки. Этот endpoint не сообщает, было ли сообщение доставлено на телефон или прочитано.
Примеры значений error для сообщений с ошибкой: Phone number invalid, Group not found, Image Url Error, File Url Error, Blocked Contact, File exceeds WhatsApp size limit (…), File type not supported, Sending was interrupted and may have been delivered. Check WhatsApp before resending.
Ошибки#
{
"message": "Unknown message id",
"status": 0,
"status_text": "pending",
"error": "Invalid message id"
}
| Сообщение | Как исправить |
|---|---|
Unknown message id | В рабочем пространстве вашего API-ключа нет сообщения с таким ID. Проверьте ID и убедитесь, что используете ключ из того же рабочего пространства. |
Auth Error | Передайте и client_id, и api_key. Недопустимое тело JSON (например, с лишней запятой в конце) тоже возвращает Auth Error. |
Invalid Client Id | Передайте client_id числом. Возвращается с HTTP 403. |
Auth Error: invalid api key | Проверьте, что ключ существует, не удалён и принадлежит этому client_id. Возвращается с HTTP 400. |
Советы#
- Для обновлений в реальном времени используйте webhook: передайте
webhookпри отправке сообщения, и Wbiztool уведомит вас, когда оно будет отправлено или завершится ошибкой, — опрашивать API не придётся. Отменённые сообщения и сообщения с истёкшим сроком не вызывают webhook, поэтому их проверяйте здесь. - Опрос: если вы всё же опрашиваете API, остановитесь, как только
statusперестанет быть0. Делайте паузу в несколько секунд между проверками. - Много сообщений сразу: чтобы проверить сообщения за целый день, используйте API истории сообщений вместо вызова этого endpoint для каждого ID.
- Старые сообщения удаляются: для отправленных, неудачных, отменённых и просроченных сообщений, которые не менялись около 90 дней, возвращается
Unknown message id. То же относится к сообщениям, которые всё ещё стоят в очереди через 90 дней после создания или запланированного времени на отключённом или удалённом номере. - Старые интеграции:
POST /api/v1/msg_status/сmsg_idв теле запроса устарел. Он возвращает те же поля. Он также принимаетGETсclient_id,api_keyиmsg_idв строке запроса, из-за чего ваш API-ключ попадает в URL и журналы. Перейдите на этот endpoint.
