Новое Safe Mode прогревает новые номера и снижает риск блокировки в WhatsApp. Подробнее →

Maytapi/Документация//webhook

/webhookСобытия в реальном времени в JSON

WhatsApp Webhook API

Получайте на свой сервер входящие сообщения WhatsApp, статусы доставки и прочтения и изменения состояния сессии в момент, когда они происходят. Укажите один адрес — все подключённые номера будут отправлять туда события в JSON.

  • входящие сообщения
  • статусы доставки и прочтения
  • состояние сессии
  • один адрес для всех номеров
Вебхуки WhatsApp для статусов доставки и прочтения
Настройки вебхука в консоли Maytapi и входящее сообщение WhatsApp, доставленное на вебхук
События

Четыре типа событий, один эндпоинт

У каждого события есть поле type, поэтому один эндпоинт может обрабатывать сообщения, статусы и изменения состояния для всех ваших номеров.

  • type: message

    Входящие сообщения

    Текст, изображения, видео, аудио, документы, геолокации и контакты, отправленные на ваш номер, с отправителем и id диалога.

  • type: ack

    Статусы доставки и прочтения

    Узнавайте, когда отправленное сообщение доставлено, дошло до телефона, прочитано, прослушано или удалено.

  • type: status

    Состояние сессии

    Получайте уведомление, когда телефон активен, ждёт сканирования QR, простаивает или сообщает об ошибке.

  • live chat

    События LiveChat

    Если вы используете API вместе с LiveChat, события операторов приходят на тот же вебхук.

  • phone_id

    Маршрутизация нескольких номеров

    Каждое событие содержит product_id и phone_id, поэтому один эндпоинт обслуживает все номера аккаунта.

  • reply

    Готовый адрес для ответа

    Входящие сообщения содержат адрес reply: ответ клиенту — это один POST-запрос.

Настройка

Вебхук настраивается одним запросом

Один раз отправьте свой HTTPS-адрес на /setWebhook. После этого каждый телефон вашего продукта отправляет события на этот адрес в JSON.

  • ✓Один адрес для всех подключённых номеров
  • ✓Простой JSON через HTTPS POST
  • ✓Меняйте в любое время в панели или через API
curl -X POST "https://api.maytapi.com/api/$PID/setWebhook" \
  -H "x-maytapi-key: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"webhook": "https://example.com/maytapi/webhook"}'
Поток событий

Сообщения и статусы сразу

Клиент пишет — ваш сервер узнаёт. Вы отправляете сообщение — статусы доставки и прочтения приходят за секунды, без постоянных опросов.

  • ✓Верните HTTP 200, чтобы подтвердить событие
  • ✓При большом объёме обрабатывайте события асинхронно
  • ✓Связывайте статусы с сообщениями по msgId
message"type": "text", "text": "Мой заказ уже отправлен?"
ack · delivered"ackCode": 1, "ackType": "delivered"
ack · reached"ackCode": 2, "ackType": "reached"
ack · seen"ackCode": 3, "ackType": "seen"
status"status": "active"
Формат

Как выглядит событие

События — это компактные JSON-объекты. Поле type подсказывает, как его обработать; product_id и phone_id — к какому аккаунту и номеру оно относится.

  • ✓message: текст, медиа, геолокация, vCard и другое
  • ✓ack: ход доставки с ackCode и ackType
  • ✓status: active, qr-code, idle, phone-error, loading, disabled
{
  "type": "message",
  "product_id": "1a2b3c4d-…",
  "phone_id": 12345,
  "user": {
    "id": "7916xxxxx67@c.us",
    "name": "Customer",
    "phone": "7916xxxxx67"
  },
  "message": {
    "id": "3EB081AF26FADE6416D8",
    "type": "text",
    "text": "Is my order shipped?",
    "fromMe": false
  },
  "conversation": "7916xxxxx67@c.us",
  "receiver": "7916xxxxx21",
  "timestamp": 1574081887,
  "reply": "https://api.maytapi.com/api/1a2b3c4d-…/12345/sendMessage"
}
Статусы

Доставка и прочтение по кодам

События ack показывают, на каком этапе каждое отправленное сообщение. Если они не нужны, отключите их через /setAckPreference и получайте только входящие.

  • ✓Для голосовых сообщений приходит и статус прослушивания
  • ✓Удалённые сообщения тоже отражаются
ackTypeackCodeЗначение
delivered1Доставлено на серверы WhatsApp
reached2Дошло до телефона получателя
seen3Прочитано получателем
played4Голосовое сообщение прослушано
deleted5Удалено пользователем
Ответ

Отвечайте прямо из события

Входящие сообщения содержат готовый адрес reply. Быстро подтвердите вебхук и отправьте ответ — простой шаблон для автоответов и чат-ботов.

  • ✓Работает с любым языком и фреймворком
  • ✓Свои сообщения отфильтруйте по message.fromMe
app.post("/maytapi/webhook", express.json(), async (req, res) => {
  res.sendStatus(200); // acknowledge first

  const event = req.body;
  if (event.type !== "message" || event.message.fromMe) return;

  await fetch(event.reply, {
    method: "POST",
    headers: { "x-maytapi-key": TOKEN, "Content-Type": "application/json" },
    body: JSON.stringify({
      to_number: event.conversation,
      type: "text",
      message: "Thanks! We received your message."
    })
  });
});
Сценарии

Что команды строят на вебхуке

  • Синхронизация с CRM и helpdesk

    Каждое входящее сообщение WhatsApp автоматически становится тикетом или записью в CRM.

  • Чат-боты и ИИ-агенты

    Передавайте входящие сообщения боту или ИИ-агенту и отвечайте в реальном времени через reply.

  • Контроль доставки

    Сохраняйте статусы доставки и прочтения, чтобы знать, какие уведомления о заказах клиенты действительно видели.

  • Мониторинг сессий

    Оповещайте команду, когда номеру нужно новое сканирование QR или он сообщает об ошибке.

  • Автоматизация без кода

    Направьте вебхук в n8n или Make и стройте сценарии без бэкенда.

  • Общий ящик

    Распределяйте диалоги с нескольких номеров между нужными сотрудниками.

FAQ

Вопросы о вебхуках WhatsApp

Задайте любой вопрос поддержке в WhatsApp. Среднее время ответа — меньше 24 часов.

Центр помощи →
Что такое вебхук WhatsApp?

Вебхук — это адрес на вашем сервере, на который Maytapi отправляет HTTPS POST-запрос каждый раз, когда на вашем номере WhatsApp что-то происходит: новое входящее сообщение, статус доставки или прочтения, изменение состояния сессии.

Какие события приходят на вебхук?

Входящие сообщения (type: message), статусы доставки и прочтения (type: ack), изменения состояния сессии (type: status) и, если вы используете API вместе с LiveChat, события чата.

Нужен ли публичный HTTPS-адрес?

Да. Вебхук должен быть доступен из интернета. Во время разработки локальный сервер можно открыть через туннель, например ngrok.

Может ли один вебхук обслуживать несколько номеров?

Да. Вебхук задаётся для продукта, а каждое событие содержит phone_id, поэтому один эндпоинт обслуживает все номера аккаунта.

Можно ли отключить статусы доставки и прочтения?

Да. Вызовите /setAckPreference с ack_delivery = false — на вебхук будут приходить только входящие сообщения и изменения состояния.

Начните работать с WhatsApp API

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

Без одобрения, без шаблонов, без карты. Все эндпоинты открыты на три дня.