WhatsApp API

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

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

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

1. Подключите номер по QR-коду в кабинете → вкладка «Мои номера».
2. Включите модуль «Вебхук / API» (без него раздел с ключом скрыт).
3. На карточке номера нажмите ⚙️ Настройки и заполните блок Webhook:
   • Включить webhook — отправлять ли события на ваш адрес.
   • URL — куда мы шлём входящие, например https://your-n8n.com/webhook/abc.
   • Входящие сообщения — получать ли их в вебхук (если выключить, придут только служебные события вроде подключения).
   • Звонки — получать ли события входящих звонков (по умолчанию выключено; см. раздел «Входящий звонок»).
4. api_key номера показан на карточке (значок «глаз» / «копировать»).

Поведение номера (необязательно)

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

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

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

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

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

Поля внутри data

Примеры

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

{
  "event": "message",
  "receiver": "+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",
  "receiver": "+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",
  "receiver": "+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",
  "receiver": "+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",
  "receiver": "+77001234567",
  "api_key": "...",
  "data": { "state": "connected" }
}

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

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

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

Поля внутри data

Пример

{
  "event": "call",
  "receiver": "+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
  }
}

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

В сообщениях с файлом приходит 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"} — повторите через пару секунд.
• Без ключа или с чужим ключом → 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 того сообщения, которое отмечаем.
• Отмечает конкретное сообщение в момент вызова (а не всё подряд). Если хотите авто-чтение всех входящих — есть тумблер «Читать сообщения» в настройках номера.

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

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 на все номера. В каждом входящем будет receiver (какой номер получил) и api_key (которым отвечать). Ничего вручную сопоставлять не нужно.

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

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

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

В настройках номера включите тумблер «Игнорировать группы» — тогда групповые сообщения вообще не будут приходить на ваш URL.

Что в поле raw?

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

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

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