Вебхуки

Вебхуки позволяют узнавать о событиях, которые происходят на стороне Wazzup. Например, что у сообщения изменился статус на «Доставлено» или канал «Не авторизован», а значит, канал надо переподключить.

Wazzup отправляет вебхуки на ваш HTTP‑endpoint. Нужно подписываться на вебхуки по конкретному дочернему аккаунту с использованием client_access_token в заголовке: Authorization: Bearer <client_access_token>

Поддерживаемые события

• message.add — получено входящее сообщение от клиента;
• message.status_update — обновился статус исходящего сообщения. Например, с «Доставлено» на «Прочитано»;
• message.delete — сообщение удалено;
• message.edit — сообщение отредактировано. Приходит только по сообщениям на каналах, которые поддерживают редактирование;
• waba_template.status_update — изменился статус модерации шаблона WABA. Статус модерации показывает, можно ли использовать шаблон;
• channel.status_update — изменился статус канала;
• channel.create — канал создан;
• channel.delete — канал удалён;
• channel.qr_update — обновился QR, код подключения → необходимо отобразить новый код клиенту. Приходит для WhatsApp, Telegram Personal, Viber;
• channel.waba_tier_update — изменился уровень (tier) WABA. Уровень показывает, сколько переписок можно начинать первым в течение 24 часов;
• group_chat.memberships_update — изменился состав группового чата WhatsApp или участник чата переименован;
• group_chat.update — изменилась информация о групповом чате;
• crm_entities.contact_add — нужно создать новый контакт;
• crm_entities.deal_add — нужно создать новую сделку;
• messages_dump.status_update — получить выгрузку сообщений.

Подписывайтесь только на события, которые обрабатывает ваша система.

Подписаться на вебхуки

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

Пример запроса:

curl -L 'https://tech.wazzup24.com/v2/webhooks'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer <client_access_token>'
-d '{
"data": [
{
"url": "https://webhook.site/73796fab-2e6d-492a-b68e-061d825b7db5",
"event": "message.add"
},
{
"url": "https://webhook.site/73796fab-2e6d-492a-b68e-061d825b7db5",
"event": "message.status_update"
}
]
}'

Пример ответа:

{
"data": [
{
"id": "d6c04-7623-43ae-a024-7b36c4004c13",
"url": "https://webhook.site/73796fab-2e6d-492a-b68e-061d825b7db5",
"event": "message.add"
},
{
"id": "b0a26-10d9-4d47-8cda-892c9b471a05",
"url": "https://webhook.site/73796fab-2e6d-492a-b68e-061d825b7db5",
"event": "message.status_update"
}
],
"meta": {
"timestamp": 1759494767
}
}

Результат: Создана подписка на события message.add и message.status_update. Вебхуки будут приходить на адрес https://webhook.site/73796fab-2e6d-492a-b68e-061d825b7db5.

В ответе содержится id подписки — ID нужно для управления вебхуками в других методах.

Изменение подписки на вебхуки

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

Пример:

curl -L -X PATCH 'https://tech.wazzup24.com/v2/webhooks'
-H 'Authorization: Bearer <client_access_token>'
-H 'Content-Type: application/json' -d '{
"data": [
{
"id": "42cdd-a0a6-40fd-b55b-040e7c605d0a",
"url": "https://webhook.site/1d2c6a79-d709-4d00-ad24-856e3d8edfd5",
"event": "message.delete"
}
]
}'

Пример ответа:

{
"data": [
{
"id": "d6c04-7623-43ae-a024-7b36c4004c13",
"url": "https://webhook.site/new-webhook-url",
"event": "message.delete"
}
],
"meta": {
"timestamp": 1759483585
}
}

Результат: Для подписки с id: 411d6c04-7623-43ae-a024-7b36c4004c13 обновлен url для получения вебхуков.

Получить список подписок на вебхуки

Пример:

curl -L 'https://tech.wazzup24.com/v2/webhooks' -H 'Authorization: Bearer <client_access_token>'

Пример ответа:

{
"data": [
{
"id": "891cdbf4-07bd-4c24-942b-27d5c820c879",
"url": "https://webhook.site/3d76c4a6-f1ab-4090-a766-3f9a07bca714",
"event": "channel.status_update"
},
{
"id": "1e35de57-ca04-45ba-a345-67f0d8b11138",
"url": "https://webhook.site/3d76c4a6-f1ab-4090-a766-3f9a07bca714",
"event": "channel.create"
},
{
"id": "ccbe0af3-2f12-4e6e-8c35-78fe3c9d3714",
"url": "https://webhook.site/3d76c4a6-f1ab-4090-a766-3f9a07bca714",
"event": "channel.update"
}
],
"meta": {
"timestamp": 1759483435
}
}

Результат: Список всех подписок на вебхуки для дочернего аккаунта.

Удалить подписку на вебхук

Пример:

curl -L -X DELETE 'https://tech.wazzup24.com/v2/webhooks'
-H 'Authorization: Bearer <client_access_token>'
-H 'Content-Type: application/json'
-d '{
"data": [
{
"id": "dbf4-07bd-4c24-942b-27d5c820c879"
}
]
}'

Пример ответа:

{
"data": null,
"meta": {
"timestamp": 1759483702
}
}

Результат: Подписка с id: dbf4-07bd-4c24-942b-27d5c820c879 удалена. Вы больше не получаете вебхуки с этим событием.

Структура вебхука

{
"event": "message.add" | "message.status_update" | "message.delete" | "message.edit" | "channel.status_update" | "channel.delete" | "channel.create" | "channel.qr_update" | "channel.waba_tier_update" | "waba_template.status_update" | "group_chat.memberships_update" | "group_chat.update",
"data": [],
"meta": {
"idempotency_key": UUIDv4,
"timestamp": Unix timestamp в секундах
}
}

Внутри поля data содержится само событие. Структура событий:

message.add

{
"message_id": "a14325c0-97c0-43dd-917e-f0ad7460b6a9",
"channel_id": "a14325c0-97c0-43dd-917e-f0ad7460b6a9",
"direction": "inbound",
"quoted_message_id": "90126ace-fc10-44ed-90de-c30c3802fcf5" | null,
"timestamp": 1762340622177,
"crm_user_id": "123" | null,
"status": "sent",
"recipient": {
"chat_id": "7999999999",
"username": "my_tg_user",
"phone": "79851112233",
"chat_type": "telegram",
"name": "Tg User"
},
"text": "Привет!",
"attachment": {
"url": "https://some.url/photo.jpg",
"name": "photo.jpg",
"mimetype": "image/jpeg",
"size": 14832,
"sha1": "123456abcdf"
},
"template": {
"id": "2b1c3d4e-5f67-890a-bcde-f123456789ab",
"values": [ "Привет" ],
"buttons": [
{ "text": "Да", "payload": "yes" },
{ "text": "Нет", "payload": "no" }
]
}
}

{
  "event": "message.add",
  "data": [
    {
      "message_id": "a5e8ba61-bc6c-41fe-9598-db7a9cbfbcbd",
      "chat_id": "221601332",
      "channel_id": "5f3f029a-8e76-4203-9434-fd490f8db848",
      "direction": "inbound",
      "quoted_message_id": null,
      "timestamp": 1776953557938,
      "crm_user_id": null,
      "text": "Hello",
      "status": "accepted",
      "sender": {
        "chat_type": "telegram",
        "chat_id": "221601332",
        "name": "Test Testovich",
        "username": "testaccount",
        "phone": 79111234567 
     } 
      "recipient": {
        "chat_id": "221601332",
        "chat_type": "telegroup",
        "avatar": null,
        "username": null,
        "phone": null,
        "name": "Групповой чат",
        "profile_id": null,
        "advert": null
      }
    }
  ],
  "meta": {
    "idempotency_key": "9ef07b18-e95f-4ba1-9981-63d95d8ed468",
    "timestamp": 1776953558
  }
}

{
  "event": "message.add",
  "data": [
    {
      "message_id": "a5e8ba61-bc6c-41fe-9598-db7a9cbfbcbd",
      "chat_id": "221601332",
      "channel_id": "5f3f029a-8e76-4203-9434-fd490f8db848",
      "direction": "outbound",
      "quoted_message_id": null,
      "timestamp": 1776953557938,
      "crm_user_id": "1",
      "text": "111111111112",
      "status": "accepted",
      "recipient": {
        "chat_id": "221601332",
        "chat_type": "cian",
        "avatar": "https://store.dev-wazzup24.com/f0099ac6204c37af8cf80136d910f87520887d3b",
        "username": "139032710",
        "phone": null,
        "name": "Контакт номер 1",
        "profile_id": "139032710",
        "advert": {
          "id": 326650834,
          "url": "https://cian.ru/sale/flat/326650834/",
          "sha1": "e920b6e6b46756d4761d1bcc1e281fcf3279dea7",
          "type": "offer",
          "price": "7 350 000 ₽",
          "title": "1-комн. кв., 45,3 м², 7/7 этаж",
          "userId": 133889346,
          "externalId": "2299893155",
          "locationTitle": "Магаданская область, Магадан, улица Берзина, 12"
        }
      }
    }
  ],
  "meta": {
    "idempotency_key": "9ef07b18-e95f-4ba1-9981-63d95d8ed468",
    "timestamp": 1776953558
  }
}

message.add
│
├── message_id *
├── channel_id *
├── direction *
├── quoted_message_id
├── timestamp *
├── status *
├── crm_user_id
├── sender
│ ├── chat_type *
│ ├── chat_id *
│ ├── name
│ ├── username
│ └── phone
├── recipient *
│ ├── chat_type *
│ ├── chat_id
│ ├── username
│ ├── phone
│ ├── profile_id *
│ └── advert *
├── text
├── attachment
│ ├── url *
│ ├── name
│ ├── mimetype
│ ├── size
│ └── sha1
├── template
│ ├── id *
│ ├── values[]
│ └── buttons[]
│ ├── text *
│ └── payload *
└── referral
├── source_url
├── source_type
├── source_id
├── headline
├── body
├── media_type
├── image_url
├── video_url
├── thumbnail_url
└── ctwa_clid

sender (объект)

recipient (объект)

attachment (объект)

template (объект)

referral (объект)

advert (объект)

message.status_update

{
"message_id": UUIDv4 | null,
"request_id": UUIDv4 | null,
"status": "accepted" | "sent" | "delivered" | "read" | "failed",
"reason": string | null
}

Возможные значения reason в зависимости от status.

При status: "accepted" | "sent" | "delivered" | "read" — reason всегда null

При status: "failed" — reason показывает причину ошибки.

message.delete

{
"message_id": UUIDv4,
"crm_user_id": string | null,
"timestamp": Unix timestamp в миллисекундах
}

message.edit

{
"message_id": UUIDv4,
"crm_user_id": string | null,
"timestamp": Unix timestamp в миллисекундах
"text": string, // опционально
"old_text": string, // опционально
"attachment": {},
"old_attachment": {}
}

waba_template.status_update

{
"template_id": UUIDv4,
"status": "APPROVED" | "PENDING" | "REJECTED" | "PAUSED" | "DISABLED",
"timestamp": unix epoch,
}

channel.status_update

{
"channel_id": UUIDv4,
"status": "active" | "disabled" | "init",
"reason": string | null
}

Возможные значения reason в зависимости от status:

• При status: "active" — reason всегда null
• При status: "init" — reason: wait_for_password, wait_for_code, qr, sync или null
• При status: "disabled" — reason: blocked, not_enough_money, rejected, unauthorized, foreignphone, qridle, openelsewhere или null

channel.delete

{
"channel_id": UUIDv4,
"timestamp": Unix timestamp в миллисекундах,
}

channel.create

{
"channel_id": UUIDv4,
"timestamp": Unix timestamp в миллисекундах,
}

channel.qr_update

{
"channel_id": UUIDv4,
"qr_code": string,
"platform": 'whatsapp' | 'telegram_api' | 'viber'
}

channel.waba_tier_update

Meta* присваивает аккаунтам WhatsApp Business уровни tier — они показывают, сколько 24-часовых переписок можно начать сутки.

{
"channel_id": UUIDv4,
"tier": "TIER_0" | "TIER_1K" | "TIER_10K" | "TIER_100K" | "TIER_UNLIMITED",
}

Возможные значения:

• TIER_0: 250 переписок,
• TIER_1K: 1000 переписок,
• TIER_10K: 10 000 переписок,
• TIER_100K: 100 000 переписок,
• TIER_UNLIMITED: без ограничений.

group_chat.memberships_update

{
"meta": {
"idempotency_key": "945ff8a4-bb3c-45f7-8d1a-b40f7ce2fb",
"timestamp": 1760690824
},
"data": [
{
"group_id": "3c67afca-6cbf-4517-b120-c4a83dbd41",
"members": [
{
"group_member_id": "c705786d-bba5-43f9-9b-5f6f5d4ba623",
"name": "Маша",
"avatar_url": null,
"status": "in_group" | "invited" | "unknown" | "deleted" | "not_exists" |
}
]
}
],
"event": "group_chat.memberships_update"
}

Вебхуки о необходимости создать контакт, сделку: crm_entities.contact_add и crm_entities.deal_add 

Отправляем, когда нужно создать контакт или сделку в CRM. Это происходит в 3 случаях:

Кейс 1: в п. 3 настроек интеграции выбрано «Нового клиента получает первый ответивший менеджер».

Пишет новый клиент. Сотрудник ему отвечает. Wazzup отправляет вебхук о создании нового контакта и сделки на первое исходящее, если из CRM загружены воронки с этапами.

Кейс 2: в п. 3 настроек интеграции выбрано «Менеджеры получают новых клиентов по очереди».

Пишет новый клиент. Wazzup отправляет вебхук о создании нового контакта и сделки на первое входящее, если из CRM загружены воронки с этапами.

Кейс 3: при нажатии на кнопку «+» в списке «Сделки» для создания сделки:

Мы проверяем, создан ли контакт у нас в базе.

Если контакт отсутствует, отправляем вебхук о необходимости создания контакта:

{
    "event": "crm_entities.contact_add",
    "data": [
        {
            "responsible_user_id": string,
            "name": string,
            "recipient":
                {
                    "chat_type": string,
                    "chat_id": string,
                    "username": "string",
                    "phone": "string"
                }[],
            "source": "auto" |   "by_user"
//auto — при входящем или исходящем, by_user — по кнопке
        }
    ],
    "meta": {
        "idempotency_key": string
        "timestamp": number
    }
}

После этого CRM должна создать контакт и вернуть JSON-объект с данными о контакте. Пример:

{
  "id": "string",
// id контакта в CRM, обязательный параметр
  "responsible_user_id": "string",
  "name": "string",
// имя контакта, обязательный параметр
  "recipient": [
    {
      "chat_type": "string",
      "chat_id": "string",
      "username": "string",
      "phone": "string"
    }
  ],
  "uri": "string"
// uri опционально. Ссылка на контакт в CRM, по которой переходит пользователь из списка «Сделки» в iframe чатов

}

Затем мы отправим вебхук о необходимости создания сделки.

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

{
    "event": "crm_entities.deal_add",
    "data": [
        {
            "responsible_user_id": string
            "pipeline_id": string,
            "stage_id": string,
            "contacts": string[],
            "source": "auto" | "by_user"
//auto — при входящем или исходящем, by_user — по кнопке
        }
    ],
    "meta": {
        "idempotency_key": string
        "timestamp": number
    }
}

После чего CRM должна создать сделку и вернуть JSON-объект с данными сделки. Пример:

{
    "id": "deal_123",
// id сделки в CRM, обязательный параметр
    "responsible_user_id": "user_456",
    "name": "Клиент",
    "contacts": ["contact_789", "contact_012"],
    "source": "auto",
    "closed": false,
    "uri": "https://crm.example.com/deals/deal_123"
// uri опционально. Ссылка на сделку в CRM, по которой переходит пользователь из списка «Сделки» в iframe чатов
  }

messages_dump.status_update

В вебхуке приходит ссылка на выгрузку сообщений. Чтобы создать задачу на выгрузку, используйте метод POST /v2/messages/messages_dump

Рекомендации по надёжности

• Отвечайте быстро 200 OK, остальную обработку делайте асинхронно.
• Ретраи. При временных ошибках доставки мы можем повторить отправку (количество попыток и интервалы могут меняться). Делайте обработку идемпотентной.
• Защита. Размещайте endpoint за HTTPS.
• Лимиты. Не выполняйте тяжёлую работу синхронно в обработчике вебхука — используйте очередь/фоновую обработку.

Быстрый чек‑лист

1. Разверните публичный POST‑endpoint (HTTPS), принимайте application/json.
2. Храните логи: статус ответа, тело, заголовки.
3. Подпишитесь на события message.add и message.status_update — это минимум, чтобы понимать что сообщение отправлено и доставлено.
4. Проверьте сценарии: входящее сообщение → ваш сервис → ответ 200; исходящее сообщение → статус‑вебхуки.

*Запрещены и признаны экстремистскими на территории РФ