Перейти к содержимому

getVisitor

Обновлено 18 октября 2026

Содержание
  1. Параметры
  2. Пример запроса
  3. Пример ответа
  4. Поля ответа
  5. Ошибки
  6. Особенности
  7. Что дальше

Отдаёт карточку посетителя: номер обращения, откуда пришёл и какие страницы смотрел, UTM, устройство, язык, данные от сайта и журнал согласий. Удобно, чтобы показать оператору контекст обращения и источник заявки.
Запрос POST /v1/instances/{idInstance}/getVisitor
Ключ заголовок Authorization: Bearer {apiTokenInstance}
Тело JSON
Каналы чат на сайте

Параметры

Параметр Тип Обязательный Описание
chatId string да посетитель: "vq3k7m2x4a6b2c4d6e7f2g3h4"

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

Карточка посетителя:

curl

curl -X POST "$GRATIO_URL/v1/instances/$GRATIO_ID/getVisitor" \
  -H "Authorization: Bearer $GRATIO_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"chatId": "vq3k7m2x4a6b2c4d6e7f2g3h4"}'

Python

import os
import requests

BASE = f"{os.environ['GRATIO_URL']}/v1/instances/{os.environ['GRATIO_ID']}"
HEADERS = {"Authorization": f"Bearer {os.environ['GRATIO_TOKEN']}"}

url = f"{BASE}/getVisitor"
payload = {"chatId": "vq3k7m2x4a6b2c4d6e7f2g3h4"}
response = requests.post(url, json=payload, headers=HEADERS, timeout=60)
print(response.status_code, response.json())

Node.js

const { GRATIO_URL, GRATIO_ID, GRATIO_TOKEN } = process.env;
const base = `${GRATIO_URL}/v1/instances/${GRATIO_ID}`;
const auth = { Authorization: `Bearer ${GRATIO_TOKEN}` };

const url = `${base}/getVisitor`;
const payload = { chatId: "vq3k7m2x4a6b2c4d6e7f2g3h4" };
const response = await fetch(url, {
  method: "POST",
  headers: { ...auth, "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});
console.log(response.status, await response.json());

PHP

<?php
$base = getenv('GRATIO_URL') . '/v1/instances/' . getenv('GRATIO_ID');
$auth = 'Authorization: Bearer ' . getenv('GRATIO_TOKEN');
$url = $base . '/getVisitor';
$payload = ['chatId' => 'vq3k7m2x4a6b2c4d6e7f2g3h4'];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [$auth, 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
]);
$response = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL;
print_r($response);

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

Ответ 200 OK:

{
  "chatId": "vq3k7m2x4a6b2c4d6e7f2g3h4",
  "ref": "G-7K4MXQ",
  "name": "Мария",
  "chatName": "Мария",
  "firstPage": {"url": "https://school.ru/", "title": "Школа робототехники"},
  "lastPage": {"url": "https://school.ru/prices", "title": "Цены"},
  "utm": {"utm_source": "yandex", "utm_campaign": "autumn"},
  "referrer": "https://yandex.ru",
  "device": "mobile",
  "lang": "ru",
  "attributes": {"plan": "pro"},
  "suspect": false,
  "preview": false,
  "waitingSince": null,
  "createdAt": 1791823600,
  "lastSeenAt": 1791823890,
  "active": true,
  "consents": [
    {"kind": "notice", "version": "n3f1c0a9b2d4e6f70", "at": 1791823658, "withdrawn": false, "messageId": "i3f2b9c0a8e7d4c1b2a3f4e5d6c7b8a90", "page": "https://school.ru/prices"}
  ]
}

Поля ответа

Поле Тип Описание
ref string номер обращения: посетитель называет его, если продолжает разговор в мессенджере. Личность он не подтверждает
name, chatName string имя из формы; без него chatName — «Посетитель G-7K4MXQ»
firstPage, lastPage object первая и последняя страница: url, title
utm, referrer object, string метки и источник перехода; из параметров адреса остаются только utm_*, yclid, gclid
device, lang string mobile, tablet или desktop; язык браузера
attributes object данные от сайта — Gratio('setAttributes', …), до 20 полей. См. JS API окна на сайте
suspect boolean посетитель сверх предела новых с одного адреса или заполнил поле-ловушку: людей не будить, заявок не заводить
preview boolean посетитель из предпросмотра в кабинете
waitingSince integer или null с какого времени ждёт сотрудника после «Позвать сотрудника»
createdAt, lastSeenAt integer первый и последний визит, секунды Unix
active boolean false — посетитель завершил чат, не заходил 90 дней или удалён: с этого устройства в этот чат он больше не напишет
consents array журнал согласий — таблица ниже

Запись журнала согласий:

Поле Описание
kind notice — писал, видя строку уведомления; consent — отметил галочку
version версия текста: у уведомления — n…; новая версия появляется при смене текста или политики
at когда, секунды Unix
withdrawn true — запись об отзыве: посетителя удалили
messageId, page с какой репликой или формой и на какой странице дано согласие

Всё в карточке — со слов посетителя и сайта, Gratio это не проверяет.

Ошибки

Код code Когда Что делать
400 validation нет chatId или он не вида v… исправить chatId
400 not_found посетителя с таким chatId нет в этом канале проверить chatId
501 not_supported MAX, Telegram, WhatsApp, почта —

Общие правила — в статье Ответы и ошибки.

Особенности

  • Карточка отдаётся из базы Gratio: метод работает и пока Gratio обновляет сеансы каналов.
  • Имя посетителя для списка чатов — тот же chatName, что в уведомлениях и getContactInfo.

Что дальше

  • exportVisitor — всё о посетителе одним файлом по его просьбе.
  • deleteVisitor — удалить посетителя со всеми данными.
  • Реплика с сайта — те же сведения в каждой реплике.

Была ли статья полезна?

Похожие статьи