Прямой Диалог документация
/
На сайт Войти в панель
Документация / Передача данных в «Прямой Диалог»

Метки: эндпоинт проверки посетителя

Метка — это решение сайта «этого посетителя показать иначе»: цвет строки в «Кто на сайте», полоса у карточки диалога, бейдж, подъём наверх списка. Решение принимает ваш сервер, чат только отображает.

Запрос #

POST с JSON-телом на адрес, указанный в панели. Приходит, когда у посетителя изменился набор ключей, истёк ttl прошлого ответа или пришло уведомление. Посетителей без ключей чат не проверяет.

ЗаголовокЗначение
Content-Typeapplication/json
X-DD-TimestampUnix-время отправки, секунды
X-DD-Signaturesha256= + hex HMAC-SHA256 от строки <timestamp>.<сырое тело> на серверном секрете
User-AgentDirectDialog-Marks/2
{
  "event": "visitor.marks",
  "version": 2,
  "site": "shop.ru",
  "visitor": {
    "id": 1842,
    "first_seen_at": "2026-08-02T09:14:05.000Z",
    "session_started_at": "2026-09-14T10:02:41.000Z"
  },
  "keys": [
    { "key": "user:98765", "verified": true }
  ],
  "data": [
    { "key": "plan", "value": "Бизнес", "verified": false }
  ]
}

Проверка подписи #

Эндпоинт публичный, поэтому две проверки выполняются до любой работы с данными — свежесть и подпись над сырым телом запроса (пересериализация JSON изменила бы байты и сломала бы сравнение).

$body = file_get_contents('php://input');
$ts   = $_SERVER['HTTP_X_DD_TIMESTAMP'] ?? '';
$sig  = $_SERVER['HTTP_X_DD_SIGNATURE'] ?? '';

if (!ctype_digit($ts) || abs(time() - (int)$ts) > 300) { fail(401, 'stale'); }

$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $body, DD_SERVER_SECRET);
if (!hash_equals($expected, $sig)) { fail(401, 'bad_signature'); }

Ответ #

200, Content-Type: application/json, UTF-8, не больше 64 КБ, за 3 секунды. Массив marks обязателен, даже пустой.

{
  "ttl": 3600,
  "marks": [
    {
      "key": "vip",
      "priority": 10,
      "expires_at": "2027-03-26T00:00:00Z",
      "tooltip": "Клиент с годовой подпиской",
      "live_row_bg": "#aaddcc6b",
      "live_row_bg_dark": "#2e7d6440",
      "chat_rail_bottom": "#2e9e7a",
      "badge": { "text": "Бизнес", "color": "#2e9e7a" },
      "counter_icon": "⭐️",
      "max_prefix": "⭐ Приоритетный"
    }
  ]
}

Ничего не показываем: { "ttl": 900, "marks": [] }

Поля метки #

ПолеЧто делаетОграничения
keyИмя метки: vip, paid, debtorобязательно, [a-z0-9_-], до 48 символов
priorityБольше 0 — посетитель поднимается вверх «Кто на сайте» и списка диалогов (оператор может выключить подъём у себя). Из нескольких меток в каждом поле побеждает метка с бо́льшим приоритетомцелое −1000…1000, по умолчанию 0
expires_atМетка гаснет сама в этот момент, без нового запросаISO-8601; в прошлом или нечитаемое — метка отброшена
live_row_bgФон строки в «Кто на сайте»только hex: #rgb, #rgba, #rrggbb, #rrggbbaa
live_row_bg_hoverФон при наведении. Не задан — чат затемнит основной самhex
chat_rail_bottomПолоса по нижней грани карточки диалогаhex
…_darklive_row_bg_dark, live_row_bg_hover_dark, chat_rail_bottom_dark — для тёмной темы панелиhex; не заданы — берётся светлый вариант
badge{text, color} — плашка в «Кто на сайте» и в шапке диалогаtext до 40 символов, color — hex
tooltipПодсказка при наведениидо 200 символов
counter_iconЗначок для счётчика в шапке «Кто на сайте»: «Сейчас на сайте 12 (⭐️ 3)»до 16 символов
max_prefixПервая строка карточки нового диалога в мессенджере MAXдо 60 символов

Меток в ответе — не больше 10. Тексты выводятся как обычный текст, лишняя длина обрезается. Цвет принимается только в hex: значение уходит в CSS панели, и любой другой синтаксис игнорируется.

Как чат трактует ответ #

ОтветЧто делает чат
200 + marksЗаменяет метки посетителя присланными (пустой массив — снимает все). Следующая плановая проверка через ttl секунд (значение зажимается в 300…86400, по умолчанию 3600)
не-2xx, редирект, таймаут, не JSON, нет marksПрежние метки остаются, повтор через 10 минут

Не можете ответить достоверно — отвечайте ошибкой, а не пустым списком. База недоступна, файл не читается, сторонний сервис молчит — верните 503: прежние метки сохранятся. Пустой marks — это «у него ничего нет», и выделение снимется со всех.

Рекомендуемые ttl: посетитель с меткой — 3600, без метки — 900. При работающем уведомлении изменение доедет раньше, ttl — страховка.

Требования к эндпоинту #