--- metadata: - name: generator content: Diplodoc Platform v5.54.1 alternate: - https://yandex.com/dev/metrika/en/management/chats-transfer-data.md - https://yandex.com/dev/metrika/ru/management/chats-transfer-data.md - href: ru/management/chats-transfer-data.md type: text/markdown title: Markdown version - href: ../llms.txt type: text/markdown title: llms.txt --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/metrika/ru/llms.txt # Передача данных о чатах ## Шаг 1. Подготовка данных {#data} Подготовка позволяет обеспечить привязку чата к визиту на сайте или к рекламному клику. - **При использовании сервиса чат-трекинга** — установите предоставленный код. Он самостоятельно считывает и передает [нужные идентификаторы Метрики](*idds). - **При собственной интеграции** — передавайте один или несколько идентификаторов: - `ClientID` — основной идентификатор посетителя Яндекс Метрики. Рекомендуем передавать его каждый раз, когда чат начался после визита на сайт. - `UserID` — [ваш внутренний идентификатор пользователя](*userid). - `Yclid` — идентификатор клика Яндекс Директа, актуален, когда пользователь переходит сразу в мессенджер, не открывая сайт. - `PurchaseID` — идентификатор заказа, если [чат относится к конкретной транзакции](*rare). Если ни один идентификатор не передан, событие будет загружено как **неатрибутированное** — без привязки к визиту/клику. ## Шаг 2. Включайте собственный идентификатор чата в ссылки на мессенджеры Это позволяет при старте диалога однозначно сопоставить чат с идентификаторами Яндекс Метрики из шага 1. [Рекомендуемая схема](*rec): 1. Сгенерируйте на своей стороне [уникальный идентификатор чата](*unique). 2. Код на сайте встраивает этот идентификатор в каждую ссылку на мессенджер: - **Telegram-бот** — через [deeplink](*deep): идентификатор пользователю не отображается, но бот получает его при первом обращении; - **Личные аккаунты Telegram/WhatsApp/Viber** — через заранее подготовленный шаблон первого сообщения, в который подставляется [идентификатор](*idex). 3. После начала диалога ваш сервис извлекает идентификатор чата из deeplink или из первого сообщения и сопоставляет его с собранными ранее [идентификаторами Метрики](*mids). В итоге появится устойчивая связка `chat-ID` ↔ `идентификаторы Метрики` — этого достаточно для корректной атрибуции. ## Шаг 3. Подготовка данных о конверсиях {#csv} Данные о конверсиях передаются в [CSV-формате](*csv): #| || **Колонки** | **Описание** || || **Обязательные** || || `DateTime` | Дата и время конверсии в формате [Unix Time Stamp](*unix). || || `ChatPlatform` | Платформа чата: `whatsapp`, `telegram`, `viber`. Значение передается строчными буквами. || || `ChatUsername` / `ChatUserID` / `PhoneNumber` | Идентификаторы собеседника. Передавайте хотя бы один из этих параметров в каждой строке. || || **Обязательные для привязки к визиту** — укажите хотя бы один из этих идентификаторов. || || `UserId` | Идентификатор посетителя сайта, назначенный владельцем сайта. || || `ClientID` | Идентификатор посетителя сайта, назначенный Яндекс Метрикой. || || `Yclid` | Идентификатор клика по рекламному объявлению Яндекс Директа, который назначается Яндекс Директом. Передается в URL объявления. || || `PurchaseID` | Идентификатор покупки из Электронной коммерции.|| || **Необязательные** || || `ChatAnswered` | `1` — есть ответ, `0` — нет ответа. || || `Tag` | Метка до 100 символов. Вы можете указать несколько через запятую.|| || `Price` | [Стоимость](*price) чата, десятичным разделителем является точка (`.`). || || `Currency` | Валюта в трехбуквенном формате ISO 4217. Например, `RUB`, `USD`. || || `URL`| Полный адрес страницы сайта, откуда начался чат.|| || `MessengerTrackerURL`| Техническая ссылка на диалог в вашей трекинг-системе. || |# ## Шаг 4. Передача данных {#upload} Сформируйте CSV-файл с информацией и передайте его с помощью метода [POST /management/v1/counter/{counterId}/offline_conversions/upload?type=CHATS](https://yandex.com/dev/metrika/ru/management/openapi/chats/upload_chats.md). Укажите во входных данных OAuth-токен и номер счетчика. Также рекомендуем генерировать запросы к API в автоматическом режиме с помощью модулей языка программирования. {% note info %} Данные появятся в отчетах Яндекс Метрики в течение 3 часов после их загрузки. {% endnote %} ## Обновление данных по одному чату {#idempotency} [Повторная загрузка](*new) той же чат-конверсии определяется комбинацией ключевых полей: `DateTime` + `ChatPlatform` + `(ChatUsername/ChatUserID/PhoneNumber)`. Если эти значения совпадают, существующая запись обновится. Например, если вы догружаете `ChatAnswered=1` и `Price` позже. При обновлении используйте секунду-в-секунду тот же `DateTime`, который вы использовали при создании конверсии. Если вы измените любой компонент ключа, будет создана новая конверсия. ## Примеры {#example} {% list tabs %} - CSV ```csv 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 ```curl curl -X POST \ -H "Authorization: OAuth " \ -F "file=@offline_chats.csv" \ "https://api-metrika.yandex.net/management/v1/counter//offline_conversions/upload?type=CHATS&comment=October%20batch" ``` - Python ```python translate=no import requests url = "https://api-metrika.yandex.net/management/v1/counter/{counterId}/offline_conversions/upload?type=CHATS" headers = {"Authorization": "OAuth "} with open("offline_chats.csv", "rb") as f: r = requests.post(url.format(counterId=""), headers=headers, files={"file": f}) print(r.status_code, r.text) ``` {% endlist %} [*csv]: UTF-8 [*unix]: секунды, UTC [*price]: ценность [*new]: обновление [*idds]: например, `ClientID` из `_ym_uid`; при необходимости — `UserID`; для трафика из Яндекс Директа — `Yclid` [*userid]: если включена функция `UserID` [*rare]: редкий сценарий [*rec]: эту схему применяют сервисы чат-трекинга, вы можете использовать ее при собственной интеграции [*unique]: например, `CT8F2A9` [*deep]: параметр запуска [*idex]: например, техническая метка в конце сообщения [*mids]: `ClientID`, `UserID`, `Yclid`