> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yo-lead.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ticket attribution

> Track the source of a request using messenger referral metadata.

Acquisition metadata is exposed as an optional string-to-string `attribution` object in `data.ticket.attribution` from [ticket history](https://docs.yo-lead.com/api-reference/tickets/get-ticket-history.md), and in `data.ticket.attribution` in `ticket.created`, `message.incoming`, and `ticket.assignee_changed` [webhooks](https://docs.yo-lead.com/webhooks/events.md).

| Channel | Source | Keys |
| - | - | - |
| Telegram Bot | Incoming `/start` command argument | `payload` |
| MAX | `bot_started` event | `payload` |
| VK | Incoming message referral | `ref`, `ref_source` |
| Instagram | Ad or supported `OPEN_THREAD` referral | `ref`, `ad_id`, `source`, `type` |
| Messenger | Ad or supported `OPEN_THREAD` referral | `ref`, `ad_id`, `source`, `type` |
| WhatsApp | Ad referral | `source_id`, `source_type`, `source_url`, `ctwa_clid` |

Telegram Account and email do not supply attribution through these sources. Fields are optional; a missing object or key does not prove that a request is organic. Ignore unknown keys so your integration can accept future additions.

For example, a ticket created from a Telegram Bot start link can contain:

```json theme={null}
{
  "attribution": {
    "payload": "campaign_123"
  }
}
```

## Capture rules

* A new ticket captures only valid attribution from the event that creates it.
* Later messages do not replace or fill in attribution, even when the ticket initially had none.
* Reopening a ticket within the restore period preserves its attribution.
* A repeat request that creates a new ticket uses that event's metadata and does not inherit the previous ticket's values.

Values are not URL-decoded or parsed into campaign identifiers. Telegram removes the command and its separating whitespace before storing the argument as `payload`; a separate `start` key is not added. YoLead does not derive UTM fields or copy arbitrary provider fields.

The object supports up to 20 keys in lower snake case, at most 64 characters per key and 1024 UTF-16 code units per value. Invalid, blank, or oversized optional values are omitted independently without rejecting a valid message. An empty attribution object is omitted.

## Referral events in message history

A MAX bot start is represented as an incoming message with `Запуск бота`, followed by `payload: …` when available. Supported standalone Meta referrals use `Переход по ссылке` followed by available referral fields. Postbacks with a title use that title as their message text. Ordinary messages with text or supported attachments keep their original content.

Creating a ticket from a referral does not guarantee permission to reply. The channel provider still controls messaging permissions.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.