Importing chats

If users prefer to get information or place orders using messengers (WhatsApp, Telegram, or Viber) when interacting with your website, you can track such contacting via chat events and link them to user actions on the site.

Importing chats helps you:

• Learn how many chat conversions you've had.
• Assess their quality: for example, find out how many chats haven't been answered.
• Evaluate the results. For example, you can see if a conversation resulted in a purchase.
• Get a better picture of your interactions with customers and see if the ad channels that lead to conversations in messengers are effective.

How to track chats in Yandex Metrica

To collect data, use chat tracking services or a custom solution, and then transmit chat data to Yandex Metrica using the API.

Yandex Metrica tracks chats using goals: when you upload chat conversion data for the first time, the service automatically creates a special Chat goal. This auto-goal then appears on the goal management page in the Yandex Metrica interface.

You don't need to create a separate goal manually: Yandex Metrica will recognize uploaded chat events and start counting conversions.

You can add the Chat goal to all Yandex Metrica reports. You'll be able to view conversion metrics (conversions, achieved goals, and so on) for this goal. It's also possible to use the goal and its conversions to optimize your ads, adjust this goal and its conversions so that they only trigger for specific chats, and add new goals of this type.

What chat data you can transmit

You can use the API or messenger tracking services to transmit basic and additional information about chats to Yandex Metrica. Required data includes the data that allows you to identify a chat event by time and messenger, as well as the IDs of a conversation. Additionally, you can transmit metrics used to assess the quality and value of chats.

For information about available data and how it's used in reports, read below.

Chat upload fields

Information	Required?	Description
Chat date and time (Unix time, UTC)	Yes	Used to record the chat event. Must be specified in the Unix timestamp format (UTC).
Chat platform (messenger: whatsapp, telegram, viber)	Yes	The name of a messenger. Acceptable values: whatsapp, telegram, and viber.
Chat IDs (username, ID, phone number)	Yes (at least one ID)	At least one of the following fields must be filled: ChatUsername, ChatUserID, or PhoneNumber.
Chat response (whether the user received a response)	No	Records whether an operator responded to the chat. Value: 1 or 0.
Chat tags	No	A text tag of up to 100 characters. Used for chat segmentation.
Conversion amount (chat value) and currency	No	Use it to transmit revenue data for a chat: a numeric value and an ISO 4217 currency code.
URL of the website page from which the chat was initiated	No	The URL of the page from which the user initiated the conversation.
Link from a messenger tracking service	No	A technical link to the chat in the tracking system, used for internal analysis.

How to transmit chat data

There are two ways to perform integration:

• Using chat tracking services

  The supplier provides a code, such as a widget or script, that you add to your website. The code snippet automatically collects the required IDs and prepares events for import into Yandex Metrica.

• Directly via the API

  For this method, follow the recommendations below.

Step 1. Collect user IDs

Goal: ensure that chats are linked to website sessions or ad clicks.

• If you use a chat tracking service

  Just install the code snippet provided to you. It automatically retrieves and transmits the required IDs to Yandex Metrica, including:

  • ClientID from _ym_uid.
  • UserID, if needed.
  • Yclid for traffic from Yandex Direct.

• If you use a custom integration

  Transmit one or multiple of the following IDs:

  • ClientID: The main identifier of a user in Yandex Metrica. We recommend that you send it if a chat originated from a website session.
  • UserID: Your internal user ID if the UserID feature is enabled.
  • Yclid: The ID of a click used in Yandex Direct. Useful when a user goes to a messenger directly, without visiting the website.
  • PurchaseID: The order ID used if a chat is linked to a specific transaction. This is a rare case.

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

Goal: explicitly match the chat to Yandex Metrica IDs from Step 1 when a new conversation is initiated.

We recommend the following algorithm, which is used by chat tracking services and works with custom integrations, too:

1. Generate a unique chat ID. For example, CT8F2A9.

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

   • Telegram bot: via a deeplink (launch parameter). A user won't see the ID, but the bot will receive it when contacted for the first time.
   • Personal accounts in Telegram, WhatsApp, or Viber: via a first message template pre-filled with the ID. For example, the ID can be passed as a technical tag at the end of a message.

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: ClientID, UserID, Yclid.

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

Step 3. Import events to Yandex Metrica

After the link is established, you can start transmitting chat events via the Yandex Metrica chat import API. Data format requirements (the event time, acceptable platform values, field structure, and so on) are described in the API specification.

Chat with us

---