Passing chat data

Step 1. Preparing 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.

• 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.

  • 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.

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:

1. Generate a unique chat ID on your side.

2. The code snippet installed on your site will add this ID to each messenger link:

   • Telegram bot — through a deeplink: 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.

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.

The service then establishes a strong chat-ID ↔ Yandex Metrica IDs link, which is sufficient for correct attribution.

Step 3. Preparing conversion data

Conversion data is sent in CSV format:

Step 4. Sending data

Create a CSV file with the data and transmit it using the method POST /management/v1/counter/{counterId}/offline_conversions/upload?type=CHATS. 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.

Updating data for a single chat

The re-upload 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

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)