Передача данных о чатах

Шаг 1. Подготовка данных

Подготовка позволяет обеспечить привязку чата к визиту на сайте или к рекламному клику.

• При использовании сервиса чат-трекинга — установите предоставленный код. Он самостоятельно считывает и передает нужные идентификаторы Метрики.

• При собственной интеграции — передавайте один или несколько идентификаторов:

  • ClientID — основной идентификатор посетителя Яндекс Метрики. Рекомендуем передавать его каждый раз, когда чат начался после визита на сайт.

  • UserID — ваш внутренний идентификатор пользователя.

  • Yclid — идентификатор клика Яндекс Директа, актуален, когда пользователь переходит сразу в мессенджер, не открывая сайт.

  • PurchaseID — идентификатор заказа, если чат относится к конкретной транзакции.

Если ни один идентификатор не передан, событие будет загружено как неатрибутированное — без привязки к визиту/клику.

Шаг 2. Включайте собственный идентификатор чата в ссылки на мессенджеры

Это позволяет при старте диалога однозначно сопоставить чат с идентификаторами Яндекс Метрики из шага 1.

Рекомендуемая схема:

1. Сгенерируйте на своей стороне уникальный идентификатор чата.

2. Код на сайте встраивает этот идентификатор в каждую ссылку на мессенджер:

   • Telegram-бот — через deeplink: идентификатор пользователю не отображается, но бот получает его при первом обращении;

   • Личные аккаунты Telegram/WhatsApp/Viber — через заранее подготовленный шаблон первого сообщения, в который подставляется идентификатор.

3. После начала диалога ваш сервис извлекает идентификатор чата из deeplink или из первого сообщения и сопоставляет его с собранными ранее идентификаторами Метрики.

В итоге появится устойчивая связка chat-ID ↔ идентификаторы Метрики — этого достаточно для корректной атрибуции.

Шаг 3. Подготовка данных о конверсиях

Данные о конверсиях передаются в CSV-формате:

Шаг 4. Передача данных

Сформируйте CSV-файл с информацией и передайте его с помощью метода POST /management/v1/counter/{counterId}/offline_conversions/upload?type=CHATS. Укажите во входных данных OAuth-токен и номер счетчика.

Также рекомендуем генерировать запросы к API в автоматическом режиме с помощью модулей языка программирования.

Обновление данных по одному чату

Повторная загрузка той же чат-конверсии определяется комбинацией ключевых полей:

DateTime + ChatPlatform + (ChatUsername/ChatUserID/PhoneNumber).

Если эти значения совпадают, существующая запись обновится. Например, если вы догружаете ChatAnswered=1 и Price позже.

При обновлении используйте секунду-в-секунду тот же DateTime, который вы использовали при создании конверсии. Если вы измените любой компонент ключа, будет создана новая конверсия.

Примеры

ClientID,DateTime,ChatPlatform,ChatUsername,ChatUserID,PhoneNumber,ChatAnswered,Tag,Price,Currency,URL,MessengerTrackerURL
133591247640966458,1687005600,whatsapp,,,"+71234567890",1,"WhatsApp Lead",1500.00,RUB,https://example.com/product/123,
133591247640966458,1687092000,telegram,"john_doe",123456789,,0,"TG Chat",,,,

curl -X POST \
-H "Authorization: OAuth <TOKEN>" \
-F "file=@offline_chats.csv" \
"https://api-metrika.yandex.net/management/v1/counter/<COUNTER_ID>/offline_conversions/upload?type=CHATS&comment=October%20batch"

import requests
url = "https://api-metrika.yandex.net/management/v1/counter/{counterId}/offline_conversions/upload?type=CHATS"
headers = {"Authorization": "OAuth <TOKEN>"}
with open("offline_chats.csv", "rb") as f:
    r = requests.post(url.format(counterId="<COUNTER_ID>"), headers=headers, files={"file": f})
print(r.status_code, r.text)