Справка по REST API v1

Используйте наше внешнее REST API для интеграции рассылок, уведомлений и уведомлений о заказах в ваши CRM, CMS или кастомные скрипты.

⚠️ Внимание: Вы не вошли в систему. В примерах кода ниже используются стандартные плейсхолдеры. Войдите в панель, чтобы автоматически подставить свои реальные данные.

1 Авторизация запросов

Все запросы к внешнему API должны быть авторизованы с помощью вашего уникального ключа X-API-Key. Этот ключ должен передаваться в качестве HTTP-заголовка при каждом запросе.

Формат заголовка:
X-API-Key: <ВАШ_X_API_KEY>

2 Отправка текстового сообщения

POST /api/v1/send-text

Помещает текстовое сообщение в очередь для отправки через подключенный аккаунт.

Параметры JSON-запроса

Параметр Тип Обязательный Описание
instance_id string Да Идентификатор подключенного WhatsApp аккаунта (instance_id).
to string Да Телефон получателя без плюса и знаков (напр. 79001234567).
message string Да Текст отправляемого сообщения.

Формат ответа (200 OK)

{
  "message_id": 412,
  "status": "queued"
}

2.1 Отправка изображения

POST /api/v1/send-image

Отправляет изображение по указанному URL с необязательной подписью.

Параметры JSON-запроса

Параметр Тип Обязательный Описание
instance_id string Да Идентификатор подключенного WhatsApp аккаунта.
to string Да Телефон получателя (10-15 цифр).
url string Да Публичная прямая ссылка на изображение.
caption string Нет Подпись к изображению.

Формат ответа (200 OK)

{
  "message_id": 413,
  "status": "queued"
}

2.2 Отправка видео

POST /api/v1/send-video

Отправляет видеофайл по указанному URL с необязательной подписью.

Параметры JSON-запроса

Параметр Тип Обязательный Описание
instance_id string Да Идентификатор подключенного WhatsApp аккаунта.
to string Да Телефон получателя.
url string Да Публичная прямая ссылка на видеофайл.
caption string Нет Подпись к видео.

Формат ответа (200 OK)

{
  "message_id": 414,
  "status": "queued"
}

2.3 Отправка аудио

POST /api/v1/send-audio

Отправляет аудиофайл (музыку или голосовую заметку).

Параметры JSON-запроса

Параметр Тип Обязательный Описание
instance_id string Да Идентификатор подключенного WhatsApp аккаунта.
to string Да Телефон получателя.
url string Да Публичная прямая ссылка на аудиофайл (напр. mp3, ogg, wav).
ptt boolean Нет Если true, аудио отправится как голосовое сообщение (PTT).

Формат ответа (200 OK)

{
  "message_id": 415,
  "status": "queued"
}

2.4 Отправка документа

POST /api/v1/send-doc

Отправляет произвольный файл/документ (PDF, DOCX, XLSX, ZIP и др.).

Параметры JSON-запроса

Параметр Тип Обязательный Описание
instance_id string Да Идентификатор подключенного WhatsApp аккаунта.
to string Да Телефон получателя.
url string Да Публичная прямая ссылка на документ.
filename string Нет Имя файла при отображении у получателя (напр. Заказ.pdf). Если не указано, берется из URL.
caption string Нет Подпись к документу.
mimetype string Нет MIME-тип документа. Если не указан, автоматически определяется по расширению.

Формат ответа (200 OK)

{
  "message_id": 416,
  "status": "queued"
}

3 Проверка статуса сообщения

GET /api/v1/messages/{id}

Возвращает текущую информацию о сообщении и его статусе доставки.

Возможные статусы:

  • • pending — ожидает обработки в Redis очереди.
  • • processing — отправка выполняется прямо сейчас.
  • • sent — сообщение успешно отправлено адресату в WhatsApp.
  • • failed — произошла ошибка при отправке. Причина пишется в поле error.

Формат ответа (200 OK)

{
  "id": 412,
  "status": "sent",
  "error": null,
  "sent_at": "2026-05-29T12:05:14.000000Z"
}

4 Лимиты и особенности

Ограничения отправки (Rate Limiting) Для предотвращения блокировки вашего WhatsApp-аккаунта серверами WhatsApp, на отправку сообщений через каждый аккаунт установлено жесткое ограничение: **не более 30 запросов в минуту**. При превышении этого лимита API вернет ошибку 429 Too Many Requests.
Гарантия доставки Если WhatsApp-сервис временно недоступен или сокет находится в режиме переподключения, Laravel автоматически попробует отправить сообщение повторно с использованием экспоненциальной задержки. В очереди настроено максимум 3 попытки отправки.

5 Вебхуки статуса доставки (Delivery Webhooks)

POST Указанный вами Webhook URL

Если для WhatsApp аккаунта настроен **Webhook URL** в панели управления, наша платформа будет автоматически отправлять POST-запрос с JSON-телом при изменении статуса доставки сообщения на sent (отправлено) или failed (ошибка).

Формат JSON-уведомления

{
  "event": "message.status",
  "message_id": 412,
  "instance_id": "inst_JiLbYzvtPUen",
  "to": "79001234567",
  "status": "sent", // "sent" или "failed"
  "error": null, // Текст ошибки, если статус "failed"
  "sent_at": "2026-05-29T12:05:14.000000Z"
}

Параметры песочницы

Код для интеграции