API сообщений
API истории сообщений
Получите список сообщений вашего рабочего пространства за диапазон дат со статусом каждого из них. Используйте этот API, чтобы сверить отправленное, строить отчёты или находить сообщения с ошибками для повторной отправки.
https://wbiztool.com/api/v1/report/Тело запроса: JSON (нужен для страниц после первой) или поля формы
История охватывает все сообщения рабочего пространства вашего API-ключа — отправленные через API, панель управления или кампанию. Результаты возвращаются по 200 на страницу, начиная с самых старых. Те же данные доступны на странице Отчеты.
Быстрый пример#
curl -X POST https://wbiztool.com/api/v1/report/ \
-H "Content-Type: application/json" \
-d '{
"client_id": 12345,
"api_key": "YOUR_API_KEY",
"start_date": "01-09-2026",
"end_date": "08-09-2026",
"page": 1
}'import requests
page = 1
history = []
while True:
response = requests.post(
"https://wbiztool.com/api/v1/report/",
json={
"client_id": 12345,
"api_key": "YOUR_API_KEY",
"start_date": "01-09-2026",
"end_date": "08-09-2026",
"page": page, # must be a JSON number, not a string
},
timeout=60,
)
result = response.json() # read the body even when the HTTP code is 400
if result.get("message") != "Success" or "total" not in result:
print("Failed:", result.get("message", "no message in response"))
break
history.extend(result["history"])
if page * 200 >= result["total"]:
break
page += 1
failed = [m for m in history if m["message_status"] == "Failed"]
print(len(history), "messages,", len(failed), "failed")// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const history = [];
let page = 1;
while (true) {
const response = await fetch("https://wbiztool.com/api/v1/report/", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
client_id: 12345,
api_key: "YOUR_API_KEY",
start_date: "01-09-2026",
end_date: "08-09-2026",
page, // must be a JSON number, not a string
}),
});
const result = await response.json(); // read the body even when the HTTP code is 400
if (result.message !== "Success" || !("total" in result)) {
console.error("Failed:", result.message ?? "no message in response");
break;
}
history.push(...result.history);
if (page * 200 >= result.total) break;
page += 1;
}
const failed = history.filter((m) => m.message_status === "Failed");
console.log(`${history.length} messages, ${failed.length} failed`);<?php
$history = [];
$page = 1;
do {
$ch = curl_init('https://wbiztool.com/api/v1/report/');
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',
'start_date' => '01-09-2026',
'end_date' => '08-09-2026',
'page' => $page, // an integer, so json_encode sends a number
]),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
if (($result['message'] ?? '') !== 'Success' || !isset($result['total'])) {
echo 'Failed: ' . ($result['message'] ?? 'no message in response');
break;
}
$history = array_merge($history, $result['history']);
$page++;
} while (($page - 1) * 200 < $result['total']);
echo count($history) . ' messages';Замените 12345 и YOUR_API_KEY своими значениями. Где их найти, описано в разделе Аутентификация.
Параметры запроса#
Аутентификация
client_idintegerобязательноВаш API Client ID из раздела Настройки → API ключи.
api_keystringобязательноВаш API-ключ с той же страницы.
Фильтры
start_datestringобязательноПервый день диапазона в формате
DD-MM-YYYY, например01-09-2026.end_datestringобязательноКонец диапазона в формате
DD-MM-YYYY. Сам этот день не включается. См. раздел Диапазон дат.whatsapp_clientintegerнеобязательноВозвращать только сообщения, отправленные с этого номера WhatsApp; укажите его ID со страницы настроек WhatsApp. Не передавайте параметр, чтобы получить сообщения со всех ваших номеров.
pageintegerнеобязательноНомер страницы, начиная с
1(по умолчанию). На каждой странице до 200 сообщений. Передавайте его как число JSON.0или отрицательное число возвращаетtotalс пустымhistory.
Диапазон дат#
Даты считаются полуночью в начале соответствующего дня по индийскому стандартному времени (IST, UTC+5:30), а сообщения отбираются по времени создания (постановки в очередь или планирования), а не отправки. Диапазон длится с 00:00 start_date до 00:00 end_date, поэтому:
"start_date": "01-09-2026", "end_date": "08-09-2026"возвращает сообщения с 1 по 7 сентября. 8 сентября не включается.- Чтобы получить один день, укажите в
end_dateследующий день:"start_date": "15-09-2026", "end_date": "16-09-2026". - Если обе даты совпадают, сообщений не будет.
Пагинация#
Каждый ответ содержит total — число сообщений во всём диапазоне — и до 200 из них в history. Запрашивайте page 2, 3 и так далее, пока page × 200 не станет больше или равно total.
Ответ#
Успешный запрос возвращает HTTP 200:
{
"message": "Success",
"status": 0,
"total": 3,
"history": [
{ "id": 9817263, "msg_type": "Text", "contact": "919876543210", "message_status": "Sent" },
{ "id": 9817264, "msg_type": "File", "contact": "919812345670", "message_status": "Failed" },
{ "id": 9817265, "msg_type": "Image", "contact": "Sales Team Mumbai", "message_status": "Pending" }
]
}
| Поле | Тип | Описание |
|---|---|---|
message | string | Success, если запрос выполнен, иначе текст ошибки. |
status | integer | Всегда 0. Не используйте его для определения успеха. |
total | integer | Число сообщений в диапазоне дат на всех страницах. Присутствует только при успехе. |
history | array | До 200 сообщений на этой странице, начиная с самых старых. Пустой при ошибке. |
history[].id | integer | ID сообщения — тот же msg_id, что был возвращён при отправке. |
history[].msg_type | string | Text, Image или File. |
history[].contact | string | Номер телефона получателя с кодом страны или название группы для сообщений в группу. |
history[].message_status | string | См. таблицу ниже. |
Значения статуса сообщения#
message_status | Значение |
|---|---|
Pending | В очереди или запланировано, ещё не отправлено (статус 0). |
Sent | Отправлено с вашего номера WhatsApp (статус 1). |
Delivered | Зарезервировано, сейчас не возвращается. |
Read | Зарезервировано, сейчас не возвращается. |
Failed | Не удалось отправить, или отправка была прервана (статус 2). Чтобы увидеть error, используйте API статуса сообщений. |
Cancelled | Отменено до отправки (статус 3). |
Expired | Не отправлено до истечения срока expire_after_seconds (статус 4). |
Отметки о доставке и прочтении сейчас не записываются, поэтому отправленные сообщения всегда отображаются как Sent. Delivered и Read — зарезервированные значения; если они когда-нибудь появятся, считайте их равными Sent.
Ошибки#
Ошибки возвращаются с HTTP 200 и status, равным 0, если не указано иное:
{ "message": "Error", "status": 0, "history": [] }
| Сообщение | Как исправить |
|---|---|
Error | start_date или end_date отсутствует или указан не в формате DD-MM-YYYY, тело JSON некорректно (часто из-за лишней запятой в конце) или запрос отправлен не методом POST. |
Auth Error | Передайте и client_id, и api_key. |
Invalid Client Id | Передайте client_id числом. Возвращается с HTTP 403, без history. |
Auth Error: invalid api key | Проверьте, что ключ существует, не удалён и принадлежит этому client_id. Возвращается с HTTP 400, без history. |
Demo Account can not access apis | Используйте обычный аккаунт. |
Советы#
- Запрашивайте историю небольшими диапазонами: по дню или по неделе — так страниц будет немного.
- Поиск сообщений с ошибками: отфильтруйте
historyпоFailed, затем вызовите API статуса сообщений для каждогоid, чтобы узнать причину. Прежде чем повторять отправку, проверьтеerror:Sending was interrupted and may have been delivered…означает, что у получателя сообщение, возможно, уже есть. - Старые сообщения удаляются: сообщения, которые достигли окончательного статуса и не менялись около 90 дней, могут быть удалены и больше не будут здесь отображаться. То же происходит с сообщениями, которые всё ещё стоят в очереди через 90 дней после создания или запланированного времени на отключённом или удалённом номере.
- Отслеживание в реальном времени: чтобы реагировать на отправку сообщений, передавайте
webhookпри отправке сообщения, а не опрашивайте этот endpoint.
