Maytapi/Документация//webhook
/webhookСобытия в реальном времени в JSONWhatsApp Webhook API
Получайте на свой сервер входящие сообщения WhatsApp, статусы доставки и прочтения и изменения состояния сессии в момент, когда они происходят. Укажите один адрес — все подключённые номера будут отправлять туда события в JSON.
- входящие сообщения
- статусы доставки и прочтения
- состояние сессии
- один адрес для всех номеров

Четыре типа событий, один эндпоинт
У каждого события есть поле 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"}'await fetch(`https://api.maytapi.com/api/${PID}/setWebhook`, {
method: "POST",
headers: { "x-maytapi-key": TOKEN, "Content-Type": "application/json" },
body: JSON.stringify({ webhook: "https://example.com/maytapi/webhook" })
});import requests
requests.post(
f"https://api.maytapi.com/api/{PID}/setWebhook",
headers={"x-maytapi-key": TOKEN},
json={"webhook": "https://example.com/maytapi/webhook"},
timeout=10,
)$ch = curl_init("https://api.maytapi.com/api/$pid/setWebhook");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["x-maytapi-key: $token", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => json_encode(["webhook" => "https://example.com/maytapi/webhook"]),
]);
echo curl_exec($ch);Сообщения и статусы сразу
Клиент пишет — ваш сервер узнаёт. Вы отправляете сообщение — статусы доставки и прочтения приходят за секунды, без постоянных опросов.
- ✓Верните HTTP 200, чтобы подтвердить событие
- ✓При большом объёме обрабатывайте события асинхронно
- ✓Связывайте статусы с сообщениями по msgId
"type": "text", "text": "Мой заказ уже отправлен?""ackCode": 1, "ackType": "delivered""ackCode": 2, "ackType": "reached""ackCode": 3, "ackType": "seen""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"
}{
"type": "ack",
"product_id": "1a2b3c4d-…",
"data": [
{
"ackType": "seen",
"ackCode": 3,
"chatId": "7916xxxxx67@c.us",
"msgId": "3EB0A1B2C3D4E5F6",
"time": 1586874663
}
]
}{
"type": "status",
"pid": "1a2b3c4d-…",
"phone_id": 12345,
"status": "active"
}Доставка и прочтение по кодам
События ack показывают, на каком этапе каждое отправленное сообщение. Если они не нужны, отключите их через /setAckPreference и получайте только входящие.
- ✓Для голосовых сообщений приходит и статус прослушивания
- ✓Удалённые сообщения тоже отражаются
| ackType | ackCode | Значение |
|---|---|---|
| delivered | 1 | Доставлено на серверы WhatsApp |
| reached | 2 | Дошло до телефона получателя |
| seen | 3 | Прочитано получателем |
| played | 4 | Голосовое сообщение прослушано |
| deleted | 5 | Удалено пользователем |
Отвечайте прямо из события
Входящие сообщения содержат готовый адрес 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."
})
});
});@app.post("/maytapi/webhook")
def webhook():
event = request.get_json()
if event.get("type") == "message" and not event["message"]["fromMe"]:
requests.post(
event["reply"],
headers={"x-maytapi-key": TOKEN},
json={
"to_number": event["conversation"],
"type": "text",
"message": "Thanks! We received your message.",
},
timeout=10,
)
return "", 200Что команды строят на вебхуке
-
Синхронизация с CRM и helpdesk
Каждое входящее сообщение WhatsApp автоматически становится тикетом или записью в CRM.
-
Чат-боты и ИИ-агенты
Передавайте входящие сообщения боту или ИИ-агенту и отвечайте в реальном времени через reply.
-
Контроль доставки
Сохраняйте статусы доставки и прочтения, чтобы знать, какие уведомления о заказах клиенты действительно видели.
-
Мониторинг сессий
Оповещайте команду, когда номеру нужно новое сканирование QR или он сообщает об ошибке.
-
Автоматизация без кода
Направьте вебхук в n8n или Make и стройте сценарии без бэкенда.
-
Общий ящик
Распределяйте диалоги с нескольких номеров между нужными сотрудниками.
Вопросы о вебхуках 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

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