Посетитель написал в окне чата на сайте. Реплика приходит обычным incomingMessageReceived: текст — textMessage, файлы — imageMessage и documentMessage с подписанной ссылкой. У каждой реплики есть siteMessageData — откуда посетитель пишет.
typeWebhook |
incomingMessageReceived |
typeMessage |
textMessage, imageMessage, documentMessage |
| Флаг настроек | incomingWebhook |
| Каналы | чат на сайте |
Пример
Посетитель спрашивает о цене со страницы «Цены»:
{
"typeWebhook": "incomingMessageReceived",
"instanceData": {"idInstance": 7100000001, "wid": "sk3m7qz2a4bt6cdxy", "typeInstance": "site", "channel": "site"},
"timestamp": 1791823658,
"idMessage": "i3f2b9c0a8e7d4c1b2a3f4e5d6c7b8a90",
"senderData": {
"chatId": "vq3k7m2x4a6b2c4d6e7f2g3h4", "chatName": "Посетитель G-7K4MXQ", "chatType": "user",
"sender": "vq3k7m2x4a6b2c4d6e7f2g3h4", "senderName": "", "senderType": "user",
"senderContactName": "", "senderPhoneNumber": 0
},
"messageData": {
"typeMessage": "textMessage",
"textMessageData": {"textMessage": "Сколько стоит пробное?"},
"siteMessageData": {
"ref": "G-7K4MXQ",
"page": {"url": "https://school.ru/prices", "title": "Цены"},
"referrer": "https://yandex.ru",
"utm": {"utm_source": "yandex", "utm_campaign": "autumn"},
"device": "mobile",
"lang": "ru",
"attributes": {"plan": "pro"},
"consent": {"mode": "notice", "accepted": true, "version": "n3f1c0a9b2d4e6f70", "at": "2026-10-19T08:47:38+00:00"}
}
}
}
Поля siteMessageData
| Поле | Описание |
|---|---|
ref |
номер обращения: посетитель называет его, если продолжает разговор в мессенджере |
page |
страница, с которой написал: url и title |
referrer, utm |
источник перехода и метки. Из параметров адреса остаются только utm_*, yclid, gclid |
device, lang |
mobile, tablet или desktop; язык браузера |
attributes |
данные от сайта — Gratio("setAttributes", …), до 20 полей. См. JS API окна на сайте |
action |
"operator" — посетитель нажал «Позвать сотрудника»; текст реплики — настройка siteHandoffText |
consent |
согласие, данное с этой репликой, — ниже |
suspect |
true — первая реплика нового посетителя сверх предела с одного адреса или реплика с заполненным полем-ловушкой: людей не будить, заявок не заводить. Следующие реплики того же посетителя — без пометки |
preview |
true — реплика из предпросмотра в кабинете |
Всё это — со слов посетителя и сайта, Gratio это не проверяет. ref, page, referrer, utm, device, lang и attributes есть всегда, хотя бы пустые; action, consent, suspect и preview — только когда они есть.
Согласие
consent приходит с репликой, которой посетитель дал согласие:
| Поле | Описание |
|---|---|
mode |
notice — писал, видя строку уведомления (первая реплика при siteConsent: "notice"); chat — отметил галочку до первой реплики |
accepted |
true |
version |
версия текста согласия: у уведомления — n… |
at |
когда, время ISO 8601 |
shown |
версия, которую показывало окно, если она другая: окно было открыто до смены настроек. В журнале — текущая version |
Режимы согласия — в статье Настройки окна.
Файл
Посетитель приложил файл — imageMessage для JPEG, PNG, WebP, GIF или documentMessage для документа, с подписанной ссылкой downloadUrl, как в Файлы и альбомы. Файлы посетитель прикладывает после первой текстовой реплики, до 10 МБ и до 5 за раз.
Как обработать
Завести заявку с источником и не будить людей из-за подозрительных реплик:
def on_site_message(body: dict) -> None:
data = body["messageData"]
site = data.get("siteMessageData", {})
if site.get("suspect") or site.get("preview"):
return # без заявки и без звонка сотруднику
lead = find_or_create_lead(body["senderData"]["chatId"], ref=site.get("ref"),
source=site.get("utm", {}).get("utm_source"), page=site.get("page", {}).get("url"))
if site.get("action") == "operator":
call_operator(lead) # посетитель позвал сотрудника
find_or_create_lead и call_operator — ваш код.
Что дальше
- Ответ кнопкой и Ответ формой — другие реплики посетителя.
- getVisitor — карточка посетителя целиком.
- Чат на сайте через API — как отвечать посетителю.