WhatsApp API

С чего начать за 30 секунд

• Каждый номер = свой ключ api_key. Он приходит в каждом входящем событии и им же вы скачиваете файлы и отправляете ответы. Вручную сопоставлять «номер → ключ» не нужно.
• Входящие. Мы отправляем POST на ваш адрес (webhook URL) при каждом новом сообщении — в удобном плоском формате.
• Исходящие. Вы отправляете POST на https://my.goflow.kz/api/messages с заголовком X-API-Key.
• Куда отвечать — всегда в chat_id из входящего. Кто написал — всегда в sender (телефон).

Подключение номера

1. Подключите номер. Официальный (WhatsApp Business API) — в разделе «Интеграции», обычный — по QR-коду в разделе «Мои номера». Вебхук работает одинаково на обоих.
2. Включите модуль «Вебхук / API» (без него раздел с ключом скрыт).
3. Откройте в кабинете «Настройки → API и вебхуки», выберите номер в списке сверху и заполните блок «Вебхук»:
   • Включить webhook — отправлять ли события на ваш адрес.
   • URL — куда мы шлём входящие, например https://your-n8n.com/webhook/abc.
   • Входящие сообщения — получать ли их в вебхук (если выключить, придут только служебные события вроде подключения).
   • Звонки — получать ли события входящих звонков (по умолчанию выключено; см. раздел «Входящий звонок»).
   • Только лиды с рекламы — присылать не всю переписку, а только сообщения с меткой рекламы Meta. Есть у официальных номеров. 🔴 Метка приходит лишь с первым сообщением человека, поэтому его следующие сообщения в вебхук не поедут (см. раздел «Метка рекламы»).
   • События сделок — присылать событие, когда сделку завели или она сменила этап (по умолчанию выключено, включаем по запросу). Там же выбираются этапы, которые вам нужны, и отдельная галочка «Новый лид» (см. раздел «События сделок»).

   Настройки относятся к выбранному номеру. Нажмите «Сохранить настройки вебхука» — они применяются сразу.

4. api_key номера показан на той же странице, в блоке «Ключ доступа» (значок «глаз» / «копировать»).

Поведение номера (необязательно, только для номера по QR-коду)

У номера, подключённого по QR-коду, есть отдельные настройки самого приложения WhatsApp: отклонять входящие звонки, игнорировать группы (тогда сообщения из групп вообще не приходят), всегда быть онлайн, отмечать сообщения прочитанными и т.д. Они живут на карточке номера в разделе «Мои номера», кнопка ⚙️ Настройки.

У официального номера (WhatsApp Business API) этих настроек нет и быть не может: там телефоном распоряжается Meta, а не кабинет. Групповые сообщения по этому пути не приходят вовсе.

Входящие сообщения (вебхук)

Когда на ваш номер приходит сообщение, мы отправляем на ваш URL запрос:

POST{ваш webhook URL}, Content-Type: application/json

Поля верхнего уровня

Поля внутри data

Примеры

Текстовое сообщение (личка):

{
  "event": "message",
  "instance": "+77001234567",
  "api_key": "5ed944...",
  "data": {
    "chat_id": "77009876543",
    "sender": "77009876543",
    "sender_name": "Aigerim",
    "is_group": false,
    "message_id": "3EB0...",
    "from_me": false,
    "timestamp": 1780336892,
    "message_type": "text",
    "text": "Здравствуйте, заказ готов?"
  }
}

Сообщение в группе с упоминанием:

{
  "event": "message",
  "instance": "+77001234567",
  "api_key": "5ed944...",
  "data": {
    "chat_id": "120363000000000000@g.us",
    "sender": "77009876543",
    "sender_name": "Aigerim",
    "is_group": true,
    "group_name": "Доставка · смена",
    "message_id": "...",
    "from_me": false,
    "message_type": "text",
    "text": "@77001234567 принимай заказ",
    "mentions": ["77001234567"]
  }
}

Картинка с подписью:

{
  "event": "message",
  "instance": "+77001234567",
  "api_key": "5ed944...",
  "data": {
    "chat_id": "77009876543",
    "sender": "77009876543",
    "is_group": false,
    "message_id": "2A52...",
    "message_type": "image",
    "text": "Вот чек",
    "caption": "Вот чек",
    "mime_type": "image/jpeg",
    "media_url": "https://my.goflow.kz/api/messages/media/2A52..."
  }
}

• Документ: то же, но message_type:"document", mime_type:"application/pdf", file_name:"Меню.pdf".
• Видео / гифка: message_type:"video", mime_type:"video/mp4".
• Голосовое: message_type:"audio", mime_type:"audio/ogg; codecs=opus".

Реакция на сообщение:

{
  "event": "reaction",
  "instance": "+77001234567",
  "api_key": "...",
  "data": {
    "chat_id": "120363...@g.us",
    "sender": "77009876543",
    "is_group": true,
    "emoji": "🔥",
    "target_message_id": "2AF1..."
  }
}

• Локация: message_type:"location" + latitude, longitude, location_name, address.
• Контакт: message_type:"contact" + contact_name, vcard.

Подключение / отключение номера:

{
  "event": "connection",
  "instance": "+77001234567",
  "api_key": "...",
  "data": { "state": "connected" }
}

Входящий звонок (вебхук)

Если в разделе «API и вебхуки» у номера включён тумблер «Звонки» (по умолчанию выключен), при входящем звонке на ваш URL приходит событие:

POST{ваш webhook URL}, поле event: "call"

Поля внутри data

Пример

{
  "event": "call",
  "instance": "+77001234567",
  "api_key": "5ed944...",
  "data": {
    "caller": "77009876543",
    "chat_id": "77009876543",
    "caller_resolved": true,
    "call_id": "00F8B01F0BC18EF2...",
    "status": "offer",
    "is_video": false,
    "is_group": false,
    "timestamp": 1781716572
  }
}

Метка рекламы Click-to-WhatsApp

Если вы крутите рекламу Meta с кнопкой «Написать в WhatsApp», вместе с первым сообщением человека мы передаём вам метку клика — по ней рекламный кабинет Meta понимает, какое объявление привело покупателя.

Метка лежит в data.referral обычного события message. Отдельный адрес для неё настраивать не нужно — вебхук у номера один.

Поля внутри referral

Объект мы отдаём в том виде, в каком его присылает Meta, ничего не достраивая. Набор полей зависит от объявления: у видео-креатива приходит одно, у картинки другое. Обязательным не является ни одно поле — в наших данных из 1240 объектов у 58 не было даже ctwa_clid, хотя source_type был ad. Проверяйте наличие поля перед чтением; чаще всего приходят ctwa_clid и source_id.

Пример

{
  "event": "message",
  "instance": "+77001234567",
  "api_key": "5ed944...",
  "provider": "waba",
  "data": {
    "chat_id": "77009876543",
    "sender": "77009876543",
    "sender_name": "Руслан",
    "message_id": "wamid.HBgL...",
    "from_me": false,
    "timestamp": 1788372604,
    "message_type": "text",
    "text": "Здравствуйте, интересует доставка",
    "referral": {
      "ctwa_clid": "AQAA...",
      "source_id": "120212345678901234",
      "source_type": "ad",
      "source_url": "https://fb.me/...",
      "headline": "Доставка за 30 минут",
      "media_type": "image"
    }
  }
}

• Метка бывает только на официальных номерах (WhatsApp Business API). На номере, подключённом по QR-коду, её не будет — Meta её туда не передаёт.
• Пришёл человек не с рекламы — поля referral в событии просто нет. Само сообщение приходит как обычно.
• Конверсии в Meta мы за вас не отправляем. Мы даём метку; отправка продажи в Conversions API — ваш шаг. Телефон Meta принимает только в виде SHA-256, хешируйте его у себя из поля sender.

События сделок (вебхук)

Когда сделку завели или она переехала на другой этап, мы присылаем на ваш адрес событие deal — и сами подкладываем в него метку рекламы того человека. Связывать сделку с номером и выяснять, откуда пришёл клиент, вам не нужно: метку клика видим только мы.

Работает с двумя CRM: provider: "amocrm" и provider: "goflow" (CRM внутри GoFlow).

POST{ваш webhook URL}, поле event: "deal"

Как включить

1. Галочка «События сделок» в кабинете: «Настройки → API и вебхуки», блок «Вебхук» (по умолчанию выключена).
2. Там же выберите этапы, которые вам нужны — до пяти. Пока не выбран ни один этап, события о смене этапа не идут: мы не шлём поток, которого вы не просили.
3. Нужно событие и на свежую сделку — включите отдельную галочку «Новый лид». Она к выбору этапов не привязана: лид может неделю висеть в «Неразобранном» и не сменить ни одного этапа. 🔴 Работает только с amoCRM — в CRM GoFlow сигнала о создании сделки нет, оттуда всё приходит как смена этапа.
4. Для amoCRM нужна ещё подписка на события на стороне вашего аккаунта — её делаем мы, напишите в поддержку.

Поля внутри data

Пример

{
  "event": "deal",
  "instance": "+77001234567",
  "api_key": "5ed944...",
  "provider": "amocrm",
  "data": {
    "action": "stage_changed",
    "seq": 3,
    "deal_id": "36552269",
    "deal_name": "Заявка с сайта",
    "phone": "77009876543",
    "ctwa_clid": "AQAA...",
    "ad_source_id": "120212345678901234",
    "stage": "Ждём оплаты",
    "stage_id": "87138154",
    "old_stage_id": "87138150",
    "pipeline": "Продажи",
    "pipeline_id": "11096386",
    "status": "open",
    "amount": 450000,
    "currency": "KZT",
    "changed_at": 1788740706,
    "is_group": false,
    "from_me": false,
    "attribution": {
      "ctwa_clid": "AQAA...",
      "ad_source_id": "120212345678901234",
      "utm_source": "tiktok",
      "utm_medium": "cpc",
      "utm_campaign": "zhalyuzi_astana",
      "utm_id": "120251659317580123",
      "from": "120251659317580123",
      "ttclid": "E.C.P...",
      "meta_fbc": "fb.1.1788...",
      "first_message_hint": "tiktok",
      "first_message_city": "Астана"
    },
    "meta_capi": {
      "ctwa_clid": "AQAA...",
      "whatsapp_business_account_id": "2968294326953602",
      "event_time": 1788740706,
      "action_source": "business_messaging",
      "messaging_channel": "whatsapp",
      "fbc": "fb.1.1788...",
      "fbp": null,
      "ad_id": "120251659317580123"
    }
  }
}

Блок attribution

Весь маркетинговый профиль лида одним плоским списком: utm_source, utm_medium, utm_campaign, utm_content, utm_term, utm_id, utm_referrer, referrer, from, roistat, gclid, yclid, fbclid, gclientid, ym_uid, ym_counter, четыре openstat_*, ttclid, meta_fbc, meta_fbp, source_url, form, landing, ip, ip_location, ga_client_id, ym_client_id, google_gbraid, google_wbraid, ctwa_clid, ad_source_id, first_message_hint, first_message_city.

Подсказка по первому сообщению

Блок meta_capi

Готовый кусок для отправки конверсии в ваш Facebook своими руками: ctwa_clid, whatsapp_business_account_id, event_time, action_source, messaging_channel, fbc, fbp, ad_id. Отправьте его в Conversions API, ничего не пересобирая.

Телефона в нём нет: Meta принимает его только хешированным по SHA-256, и хешировать нужно у себя — из поля phone того же события.

Что важно знать заранее

• Истории не будет. События идут с момента включения; смены этапа, случившиеся раньше, задним числом не придут — такой истории нет ни у нас, ни в amoCRM.
• Доставка идёт темпом до 60 событий в минуту на компанию, очередь до 2000, событие старше 10 минут не отправляем. Массовый перенос сделок не завалит ваш сервер, но и не доедет мгновенно.
• Три попытки. Если ваш приёмник не ответил (сеть, таймаут, 5xx), повторим дважды; на 4xx повторять не будем. Дальше событие теряется — amoCRM свои события не повторяет. Пропуск виден по seq.

Доставка: повторы, дубли и сроки

Мы гарантируем доставку «хотя бы раз». Это значит, что одно и то же событие может прийти к вам дважды, и ваш сценарий обязан быть к этому готов.

• Дубли отсекайте по data.message_id — он один и тот же у повторов. Это единственный надёжный ключ: время, текст и отправитель у двух разных сообщений могут совпасть, а message_id — нет.
• Если ваш адрес не ответил, мы повторяем доставку: сначала трижды подряд в течение минуты, затем через 1, 5 и 30 минут и через 2 часа. Считается любой ответ 2xx; всё остальное — неудача.
• Ответ 4xx повторов не вызывает. Такой код означает ошибку в вашем обработчике (не тот путь, не прошла авторизация), и повторять её бессмысленно. Починив приёмник, нажмите «Переотправить» в кабинете: «Настройки → API и вебхуки», блок «Вебхук». Кнопка появляется только когда недоставленные события действительно есть.
• Недоставленное храним 7 дней. После этого переотправить его нечем.
• Порядок событий не гарантирован. Повторная доставка идёт в фоне, поэтому сообщение, ушедшее со второй попытки, может прийти позже следующего за ним. Ориентируйтесь на data.timestamp, а не на порядок запросов.
• Ссылка media_url может заработать на несколько секунд позже самого события. Файл мы забираем у WhatsApp вторым шагом, уже после того, как отдали вам сообщение. Получили 404 {"error":"media not ready, retry shortly"} — повторите через пару секунд.
• Ссылка на файл живёт 7 дней с момента получения сообщения. Нужен файл дольше — скачайте и сохраните его у себя.

Номер отвалился (connection.update)

Официальный номер может перестать работать не по вашей вине, и молча: в переписке это выглядит как «клиенты перестали писать». Чтобы это было видно сразу, мы отправляем отдельное событие.

{
  "event": "connection.update",
  "provider": "waba",
  "instance": "+77001234567",
  "api_key": "5ed944...",
  "data": {
    "state": "close",
    "reason": "inactivity",
    "message": "WhatsApp снял привязку номера сам: приложение WhatsApp Business на телефоне не открывали около двух недель. Подключите номер заново в разделе «Интеграции».",
    "phone": "+77001234567"
  }
}

История переписки одним файлом (history.ready)

При подключении официального номера WhatsApp отдаёт переписку за последние полгода — ту, что велась с телефона до подключения. Мы собираем её в один файл и присылаем событие со ссылкой. Отдельно запрашивать ничего не нужно.

Событие

{
  "event": "history.ready",
  "provider": "waba",
  "instance": "+77001234567",
  "api_key": "5ed944...",
  "data": {
    "history": true,
    "phone": "+77001234567",
    "url": "https://my.goflow.kz/api/webhook/history/export",
    "messages_count": 4312,
    "threads_count": 187,
    "media_count": 54,
    "period": { "from": "2026-03-25T09:14:00.000Z", "to": "2026-09-23T18:02:00.000Z" },
    "expires_at": "2026-09-30T21:00:00.000Z",
    "message": "Переписка за прошлый период готова: 4312 сообщений. Забрать файл можно в течение 7 дней."
  }
}

Что внутри файла

Те же самые события, что приходят вам на вебхук, сложенные в массив events и отсортированные по времени. Отдельного разбора не нужно: прогоните их тем же обработчиком, что и живые сообщения.

{
  "history": true,
  "format": "goflow-waba-events-v1",
  "number": "+77001234567",
  "generated_at": "2026-09-23T18:05:00.000Z",
  "messages_count": 4312,
  "threads_count": 187,
  "media_count": 54,
  "period": { "from": "2026-03-25T09:14:00.000Z", "to": "2026-09-23T18:02:00.000Z" },
  "events": [
    {
      "event": "message",
      "provider": "waba",
      "instance": "+77001234567",
      "data": {
        "history": true,
        "chat_id": "77009876543",
        "sender": "77009876543",
        "sender_name": "Айдана",
        "from_me": false,
        "message_id": "wamid.HBgL...",
        "timestamp": 1774512840,
        "message_type": "image",
        "text": "Вот фото",
        "media_url": "https://my.goflow.kz/api/webhook/history/media/wamid.HBgL...",
        "mime_type": "image/jpeg"
      }
    }
  ]
}

curl -s -H "X-API-Key: 5ed944..." \
  "https://my.goflow.kz/api/webhook/history/export" \
  -o history.json

# что есть и до какого числа — без скачивания самого файла
curl -s -H "X-API-Key: 5ed944..." https://my.goflow.kz/api/webhook/history

Чего в истории нет

• data.history: true стоит у каждого события. По нему отличайте перенос от живого сообщения: отвечать, слать уведомления и будить ботов на переписке полугодовой давности не нужно.
• Вложения — только за последние две недели. Так отдаёт WhatsApp, и изменить это нельзя. У остальных сообщений вместо файла приходит текст «📎 Вложение не перенесено: файл старше 14 дней, WhatsApp его больше не отдаёт».
• Групповых чатов нет. WhatsApp не отдаёт их при этом способе подключения.
• Реакций, правок и удалений нет. Их не отдаёт WhatsApp.
• is_forwarded и is_voice в истории всегда false, а цитат и меток рекламы нет: этих признаков WhatsApp в истории не передаёт. У живых сообщений они работают как обычно.
• Файл и вложения живут 7 дней — столько же, сколько сама переписка у нас. После этого ссылки отвечают 410, и восстановить файл нечем: WhatsApp отдаёт историю только в первые сутки после подключения номера.
• Поля api_key внутри файла нет, в отличие от живых событий: файл вы уже скачали своим ключом, и дублировать его тысячами копий незачем. За вложениями ходите с тем же ключом в заголовке.

Скачивание файлов

В сообщениях с файлом приходит media_url вида https://my.goflow.kz/api/messages/media/<message_id>. Скачайте его методом GET с заголовком X-API-Key (ключ берётся из того же входящего — поле api_key):

curl -s -H "X-API-Key: 5ed944..." \
  "https://my.goflow.kz/api/messages/media/2A52E6BE20A64E177479" \
  -o file.bin

• В ответ приходит сам файл. Для документов имя файла указано в заголовке Content-Disposition (русские имена поддерживаются).
• Крупные файлы (до ~50 МБ) скачиваются в фоне. Если дёрнуть ссылку слишком рано, придёт 404 {"error":"media not ready, retry shortly"} — повторите через пару секунд.
• Файла больше нет → 410 {"error":"media_deleted"}. Срок хранения истёк: на тарифах, где мы переписку только передаём, вложения и сами сообщения удаляются через 7 дней. Повторять запрос бессмысленно.
• Файл забрать не удалось → 410 {"error":"media_not_received"}. Скачать его у WhatsApp не получилось, и он уже не появится: само сообщение у вас есть, файла к нему не будет. Бывает редко.
• Оба ответа 410 — окончательные. Ответ 404 означает «ещё в пути», 410 — «было и больше нет»; различайте их в своём сценарии, иначе он будет повторять запрос вечно.
• Без ключа или с чужим ключом → 401.

Отправка сообщений

POSThttps://my.goflow.kz/api/messages с заголовком X-API-Key: <ключ номера>.

Ответ при успехе: { "ok": true, "message_id": "..." }

to — куда: номер 77009876543 (личка) или 120363...@g.us (группа). Берите его из chat_id входящего.

Текст

curl -X POST https://my.goflow.kz/api/messages \
  -H "X-API-Key: 5ed944..." \
  -H "Content-Type: application/json" \
  -d '{ "to": "77009876543", "text": "Ваш заказ готов 👨‍🍳" }'

Файл

media — это публичная ссылка на файл или строка base64.

curl -X POST https://my.goflow.kz/api/messages \
  -H "X-API-Key: 5ed944..." \
  -H "Content-Type: application/json" \
  -d '{ "to": "77009876543",
        "media": "https://site.kz/photo.jpg",
        "mediatype": "image",
        "caption": "Ваш чек" }'

mediatype: image · video · audio · document.

С упоминанием (тег в группе)

Нужны оба поля: @номер в тексте и номер в mentioned:

curl -X POST https://my.goflow.kz/api/messages \
  -H "X-API-Key: 5ed944..." \
  -H "Content-Type: application/json" \
  -d '{ "to": "120363000000000000@g.us",
        "text": "@77009876543 готово",
        "mentioned": ["77009876543"] }'

Упомянуть всех (@all)

curl -X POST https://my.goflow.kz/api/messages \
  -H "X-API-Key: 5ed944..." \
  -H "Content-Type: application/json" \
  -d '{ "to": "120363000000000000@g.us",
        "text": "@all внимание",
        "mentions_everyone": true }'

Индикатор набора и отметка «прочитано»

Чтобы переписка выглядела по-человечески: отметить входящее прочитанным (синяя галочка) и показать «печатает…» перед ответом.

Печатает… (индикатор набора)

POSThttps://my.goflow.kz/api/messages/typing

curl -X POST https://my.goflow.kz/api/messages/typing \
  -H "X-API-Key: 5ed944..." \
  -H "Content-Type: application/json" \
  -d '{ "to": "77009876543", "state": "on" }'

• state: "on" — показать набор (по умолчанию), "off" — убрать.
• Один вызов держит индикатор около 5 секунд. Чтобы показывать дольше — вызовите ещё раз (повторяйте каждые ~5 сек нужное время, затем отправьте ответ).

Отметить прочитанным (синяя галочка)

POSThttps://my.goflow.kz/api/messages/read

curl -X POST https://my.goflow.kz/api/messages/read \
  -H "X-API-Key: 5ed944..." \
  -H "Content-Type: application/json" \
  -d '{ "to": "77009876543", "message_id": "3EB0..." }'

• to — это chat_id из входящего, message_id — id того сообщения, которое отмечаем.
• Отмечает конкретное сообщение в момент вызова (а не всё подряд). Если хотите авто-чтение всех входящих — есть тумблер «Читать сообщения» в настройках номера, но только у номера, подключённого по QR-коду (шестерёнка на карточке в разделе «Мои номера»). Это настройка самого приложения WhatsApp на телефоне; у официального номера (WhatsApp Business API) её нет и быть не может.

Готовый сценарий: ответить, тегнув отправителя в группе

1. Пришло входящее: is_group:true, chat_id:"120363...@g.us", sender:"77007654321".
2. Отвечаете: to = chat_id, text = "@77007654321 принял", mentioned = ["77007654321"].
3. Номер для тега берите из sender или mentions — там всегда реальные телефоны.

curl -X POST https://my.goflow.kz/api/messages \
  -H "X-API-Key: 5ed944..." \
  -H "Content-Type: application/json" \
  -d '{ "to": "120363000000000000@g.us",
        "text": "@77007654321 принял в работу",
        "mentioned": ["77007654321"] }'

Частые вопросы

Можно ли один сценарий на несколько номеров?

Да. Повесьте один и тот же webhook URL на все номера. В каждом входящем будет instance (какой номер получил) и api_key (которым отвечать). Ничего вручную сопоставлять не нужно.

Приходят ли статусы «доставлено / прочитано»?

Нет, в вебхук они не отправляются. Галочки доставки видны в нашем кабинете в разделе «Чаты».

Как отключить сообщения из групп?

Официальный номер (WhatsApp Business API): ничего включать не нужно — групповых сообщений по этому пути не приходит вовсе, Meta их не передаёт.

Номер по QR-коду: в настройках номера (шестерёнка на карточке в разделе «Мои номера») включите тумблер «Игнорировать группы» — тогда групповые сообщения вообще не будут приходить на ваш URL.

Как понять, из какого объявления пришёл лид?

Если человек нажал «Написать в WhatsApp» под рекламой Meta, в первом его сообщении придёт блок referral с ctwa_clid и ID объявления — см. раздел «Метка рекламы». Хотите видеть ещё и продажу по этому лиду — включите «События сделок»: метку мы подложим в событие сами.

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

Нет. События идут с момента, когда вы включили галочку. Истории смен этапа не существует ни у нас, ни в amoCRM, поэтому задним числом прислать нечего.

Что в поле raw?

Несколько вспомогательных полей сообщения: text, type, timestamp и quoted (если это ответ на сообщение — его текст, отправитель и id). Всё это есть и в data, так что для большинства задач достаточно data.

Будут ли готовые ноды для n8n?

Да, в планах — готовые ноды «приём входящих» и «отправка», чтобы не настраивать HTTP вручную. Пока используйте обычные HTTP-узлы по этой документации.