Подключение бота и API

1. Код клика приходит в бот

Кнопка переходника ведёт на https://t.me/<бот>?start=<префикс><код>. Код — последние 8 символов (латиница и цифры). Бот получает /start ad_c8Fk2pQx — сохраните его рядом с пользователем.

WhatsApp: код приходит в тексте первого сообщения. Max: параметр start. VK: параметр ref сообщения. Сайт: ?clck=<код> (или подстановка {click_id} в адресе). Telegram-канал по чужой пригласительной ссылке код не передаёт — для каналов есть режим «с учётом подписок» (ниже).

Salebot, BotHelp, Leadtex, Puzzlebot, SmartSender — вебхуки без программиста · Директ: оплата за конверсии

Telegram-канал с учётом подписок

Сделайте бота сервиса администратором канала (право «Приглашать пользователей») и привяжите канал в кабинете. Переходник с назначением «Telegram-канал с учётом подписок» выдаёт каждому клику свою пригласительную ссылку — вступление по ней становится событием subscribe, выход — unsubscribe, через 1, 7 и 30 дней — retained_1d, retained_7d, retained_30d. Они уходят в Метрику как обычные события (цели clck_subscribe, clck_retained_7d…).

Вариант «подарок за подписку»: кнопка ведёт в бота сервиса, он показывает «Подписаться» и «Проверить подписку» и после проверки присылает ваш подарок — текст, ссылку или файл.

2. Событие отправляется в Clck.now

POST https://clck.now/api/v1/events
Authorization: Bearer ck_…
Content-Type: application/json

{"click_id": "ad_c8Fk2pQx", "event": "paid", "value_minor": 99000, "currency": "RUB", "external_id": "order-1842"}
ПолеЧто это
click_idкод клика или весь start-параметр с префиксом
eventlead, paid или своё имя: латиница в нижнем регистре, цифры, _
value_minorсумма в копейках (необязательно)
currencyISO 4217, по умолчанию RUB
external_idваш номер заказа; повтор с тем же номером не создаёт второе событие (ответ 200, "duplicate": true)
chat_user_idid пользователя в мессенджере — для чатов Метрики (необязательно)
occurred_atвремя события, ISO 8601 или unix (необязательно, иначе — время запроса)

Ответы: 201 — создано, 200 — повтор, 400 — ошибка в теле, 401 — неверный ключ, 404 — клик не найден в проекте. GET /api/v1/clicks/<код> — проверить код.

3. Метрика и Директ

Создайте в Метрике цель типа «JavaScript-событие» с идентификатором clck_paid (для события lead — clck_lead; другой идентификатор можно задать в проекте). Получите OAuth-токен с правом на управление счётчиком и вставьте его в кабинете вместе с номером счётчика. Раз в 10 минут события выгружаются офлайн-конверсиями — по ClientID, если он был получен на странице, иначе по yclid. События по кликам старше 21 дня не выгружаются. Нажатие кнопки на странице — цель clck_click.

Пример: бот на aiogram 3

import aiohttp
from aiogram import Router
from aiogram.filters import CommandStart, CommandObject

router = Router()
CLCK_KEY = "ck_…"

@router.message(CommandStart())
async def start(message, command: CommandObject):
    if command.args:
        await db.save_click(message.from_user.id, command.args)   # e.g. "ad_c8Fk2pQx"
    await message.answer("Здравствуйте!")

async def on_paid(user_id, order_id, amount_minor):
    click = await db.click_of(user_id)
    if not click:
        return
    async with aiohttp.ClientSession() as s:
        await s.post("https://clck.now/api/v1/events",
                     headers={"Authorization": f"Bearer {CLCK_KEY}"},
                     json={"click_id": click, "event": "paid", "value_minor": amount_minor,
                           "currency": "RUB", "external_id": str(order_id)})