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

API сообщений

API статуса сообщений

Проверьте, находится ли сообщение, отправленное через API, ещё в очереди, отправлено ли оно или завершилось ошибкой. Используйте этот API, чтобы убедиться, что важные сообщения ушли, и выяснить, почему какое-то из них не отправилось.

POSThttps://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"
  }'

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

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

URL

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

ID сообщения как часть пути URL. Он должен быть целым числом и принадлежать рабочему пространству вашего API-ключа.

Тело запроса

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

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

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

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

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

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

Python
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"
}
ПолеТипОписание
statusintegerКод статуса сообщения. См. таблицу ниже.
status_textstringНазвание статуса: Created, Sent, Failed, Cancelled или Expired.
messagestringТо же значение, что и status_text.
errorstring or nullПричина ошибки отправки. Присутствует всегда; пустое ("" или null), если ошибки нет.

Значения статуса#

statusstatus_textЗначение
0CreatedВ очереди или запланировано, ожидает отправки.
1SentОтправлено с вашего номера WhatsApp.
2FailedНе удалось отправить, или отправка была прервана. Причина указана в error. Если error равно Sending was interrupted and may have been delivered. Check WhatsApp before resending., у получателя сообщение, возможно, уже есть, поэтому не отправляйте его повторно автоматически.
3CancelledОтменено до отправки, например через API отмены сообщений.
4ExpiredНе отправлено до истечения срока 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.