--- metadata: - name: generator content: Diplodoc Platform v5.48.2 alternate: - https://yandex.com.tr/dev/metrika/en/management/chats-transfer-data.md - https://yandex.com.tr/dev/metrika/ru/management/chats-transfer-data.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.com.tr/dev/metrika/en/llms.txt # Passing chat data ## Step 1. Preparing data {#data} Prepare data to ensure that chats are linked to site sessions or ad clicks. - **If you use a chat tracking service**, install the code provided to you. It automatically retrieves and transmits the [required Yandex Metrica IDs](*idds). - **If you use custom integration**, transmit one or multiple IDs from this list: - `ClientID`: The main user ID in Yandex Metrica. We recommend transmitting it each time when a chat originates from a site session. - `UserID`: [Your internal user ID](*userid). - `Yclid`: The Yandex Direct click ID. Useful when a user goes to a messenger directly, without visiting the site. - `PurchaseID`: The order ID used if a [chat is linked to a specific transaction](*rare). If no ID is transmitted, the uploaded event is considered **unattributed** and isn't linked to any session or click. ## Step 2. Add your own chat ID to messenger links Do this to explicitly match the chat to Yandex Metrica IDs from Step 1 when a new conversation is initiated. [Recommended algorithm](*rec): 1. Generate a [unique chat ID](*unique) on your side. 2. The code snippet installed on your site will add this ID to each messenger link: - **Telegram bot** — through a [deeplink](*deep): a user won't see the ID, but the bot will receive it when contacted for the first time. - **Personal accounts in Telegram/WhatsApp/Viber** — through a first message template pre-filled with the [ID](*idex). 3. After a conversation begins, the service retrieves the chat ID from the deeplink or first message and matches it with previously collected [Yandex Metrica IDs](*mids). The service then establishes a strong `chat-ID` ↔ `Yandex Metrica IDs` link, which is sufficient for correct attribution. ## Step 3. Preparing conversion data {#csv} Conversion data is sent in [CSV format](*csv): #| || **Columns** | **Description** || || **Required** || || `DateTime` | Date and time of the conversion in [Unix Time Stamp](*unix) format. || || `ChatPlatform` | Chat platform: `whatsapp`, `telegram`, `viber`. The value is transmitted in lowercase letters. || || `ChatUsername` / `ChatUserID` / `PhoneNumber` | Conversation partner IDs. Pass at least one of these parameters in each row. || || **Required for linking a chat to a session** — specify at least one of these IDs. || || `UserId` | Site user ID assigned by the site owner. || || `ClientID` | Site user ID assigned by Yandex Metrica. || || `Yclid` | Yandex Direct-assigned ID of a click on a Yandex Direct ad. The click ID is passed in the ad URL. || || `PurchaseID` | Purchase ID from E-commerce.|| || **Optional** || || `ChatAnswered` | `1` — the chat was replied to, `0` — there was no reply. || || `Tag` | Up to 100 characters long. You can specify multiple tags separated by commas.|| || `Price` | Chat [cost](*price), with a full stop (`.`) as the decimal separator. || || `Currency` | Currency code in three-letter ISO 4217 format. Examples: `RUB`, `USD`. || || `URL`| Full URL of the site page where the chat was initiated.|| || `MessengerTrackerURL`| Technical link to the conversation in your tracking system. || |# ## Step 4. Sending data {#upload} Create a CSV file with the data and transmit it using the method [POST /management/v1/counter/{counterId}/offline_conversions/upload?type=CHATS](https://yandex.com.tr/dev/metrika/en/management/openapi/chats/upload_chats.md). Make sure to include the OAuth token and the tag ID in your input data. We recommend that you also automate your API queries using modules available in your programming language. {% note info %} The data will appear in Yandex Metrica reports within 2 hours of upload. {% endnote %} ## Updating data for a single chat {#idempotency} The [re-upload](*new) of the same chat conversion is determined by the combination of key fields: `DateTime` + `ChatPlatform` + `(ChatUsername/ChatUserID/PhoneNumber)`. If these values match, an existing entry is updated. For example, if you add `ChatAnswered=1` and the `Price` value later. When updating, use exactly the same `DateTime` (second-to-second) that you specified when creating the conversion. If you change any component of a key, a new conversion will be created. ## Examples {#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]: Seconds, UTC [*price]: Value [*new]: Update [*idds]: For example, `ClientID` from `_ym_uid`, if necessary — `UserID`, for traffic from Yandex Direct — `Yclid`. [*userid]: If the `UserID` function is enabled. [*rare]: This is a rare case. [*rec]: This algorithm is used by chat tracking services and works with custom integration, too. [*unique]: For example, `CT8F2A9`. [*deep]: Launch parameter [*idex]: For example, a technical tag at the end of a message. [*mids]: `ClientID`, `UserID`, `Yclid`