Перейти к содержанию
30 минут чтения
Тема: Практика Telegram Bot API · Реферальная программа · PHP · SQLite

Как сделать реферальную программу в Telegram-боте

Для примера магазин начисляет пригласившему 100 внутренних баллов, когда новый клиент совершает оплаченную покупку от 1000 рублей. Запуск бота по ссылке лишь связывает пользователей. Начисление выполняется позже, по данным заказа на сервере. Соберём ссылки, обработку /start, журнал баллов и восстановление после сбоя.

Сначала определим правила начисления

Реферальная ссылка отвечает на вопрос «кто пригласил», но сама по себе не подтверждает покупку. Разделите три факта: первое знакомство пользователя с ботом, привязка к пригласившему и выполнение условия награды. Тогда повторный /start или повтор события оплаты не превращается в новые баллы.

  • Привязка возможна только при первом личном сообщении нового пользователя. Существующим клиентам поздняя ссылка не меняет пригласившего.

  • Для одного приглашённого в программе first-purchase-v1 предусмотрена одна награда. Условие — оплаченная покупка от 1000 рублей после привязки.

  • При полном возврате заказа награда отменяется отдельной отрицательной операцией. Повторная покупка после отмены не даёт новую награду в этой версии программы.

  • Баллы в примере — внутренний учёт. Списание на покупки и вывод денег здесь не реализованы.

Опубликуйте эти правила рядом со ссылкой. Если бизнес хочет окно атрибуции, период ожидания после покупки или бонус за несколько заказов, сначала измените правило и ключ уникальности. Нельзя просто убрать UNIQUE ради нового сценария: это одновременно откроет повторные начисления.

Если у вас уже есть пользователи, перенесите их ID в members до включения программы. Иначе приложение посчитает первого после запуска программы посетителя новым, хотя он давно покупает в магазине. Для существующей CRM признак «новый клиент» лучше брать из её проверенного реестра.

Создадим таблицы и подключение

Пример рассчитан на один бот и одну базу SQLite на локальном диске сервера, PHP 8.3+ с расширениями PDO SQLite и cURL. Публичный корень сайта — только папка public/; остальные PHP-файлы, база и Composer-зависимости находятся уровнем выше. Для нескольких ботов добавьте идентификатор бота во все ключи уникальности. Не размещайте SQLite на общей сетевой папке нескольких серверов.

Окружение · пример значений
BOT_TOKEN=TOKEN_FROM_BOTFATHER
BOT_DB_PATH=/srv/referrals/private/bot.sqlite
WEBHOOK_SECRET=RANDOM_SECRET_FROM_PASSWORD_MANAGER
WEBHOOK_URL=https://example.com/webhook.php
BOT_USERNAME=YourShopBot

Это настоящие переменные окружения процесса: настройте их и для PHP-FPM, и для CLI. Обычный PHP не читает .env автоматически. Создайте закрытую папку private/, дайте пользователю приложения право записи в неё и запретите доступ из веба. Токен и секрет webhook не должны попадать в браузер, репозиторий или логи. В примерах ниже все команды выполняются из корня отдельного учебного приложения.

Понадобятся таблицы участников, неизменяемых привязок, заказов, наград и операций по балансу. Суммы заказов храним целыми копейками: 100000 — это 1000 рублей. Таблица rewards фиксирует основание, reward_log — движение баллов. Отмена не стирает первоначальную запись.

SQL · schema.sql
CREATE TABLE members (
    user_id INTEGER PRIMARY KEY, code TEXT NOT NULL UNIQUE, joined_at INTEGER NOT NULL
);
CREATE TABLE referrals (
    invitee INTEGER PRIMARY KEY REFERENCES members(user_id),
    inviter INTEGER NOT NULL REFERENCES members(user_id),
    bound_at INTEGER NOT NULL, CHECK(invitee <> inviter)
);
CREATE TABLE orders (
    id TEXT PRIMARY KEY, user_id INTEGER NOT NULL REFERENCES members(user_id),
    amount INTEGER NOT NULL CHECK(amount > 0), paid_at INTEGER NOT NULL,
    status TEXT NOT NULL CHECK(status IN ('paid','refunded'))
);
CREATE TABLE rewards (
    id INTEGER PRIMARY KEY, program TEXT NOT NULL,
    invitee INTEGER NOT NULL, inviter INTEGER NOT NULL,
    order_id TEXT NOT NULL REFERENCES orders(id), points INTEGER NOT NULL,
    created_at INTEGER NOT NULL, reversed_at INTEGER,
    UNIQUE(program, invitee)
);
CREATE TABLE reward_log (
    id INTEGER PRIMARY KEY, reward_id INTEGER NOT NULL REFERENCES rewards(id),
    user_id INTEGER NOT NULL, delta INTEGER NOT NULL,
    action TEXT NOT NULL CHECK(action IN ('award','reverse')), created_at INTEGER NOT NULL,
    UNIQUE(reward_id, action)
);
CREATE TABLE updates (id INTEGER PRIMARY KEY);
PHP · common.php
<?php
declare(strict_types=1);

function setting(string $name): string
{
    $value = getenv($name);
    if ($value === false || $value === '') {
        throw new RuntimeException('Missing setting: '.$name);
    }
    return $value;
}

function database(): PDO
{
    $path = setting('BOT_DB_PATH');
    if (!is_file($path)) {
        throw new RuntimeException('Run init.php first');
    }
    $db = new PDO('sqlite:'.$path, options: [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
    $db->exec('PRAGMA foreign_keys=ON');
    $db->exec('PRAGMA busy_timeout=3000');
    return $db;
}

/** @param list<int|string|null> $values */
function sql(PDO $db, string $query, array $values = []): PDOStatement
{
    $statement = $db->prepare($query);
    $statement->execute($values);
    return $statement;
}

/** @return array<string, int|string|null>|null */
function row(PDOStatement $statement): ?array
{
    $result = $statement->fetch(PDO::FETCH_ASSOC);
    if ($result === false) {
        return null;
    }
    if (!is_array($result)) {
        throw new RuntimeException('Invalid database row');
    }
    foreach ($result as $key => $value) {
        if (!is_string($key) || !(is_int($value) || is_string($value) || $value === null)) {
            throw new RuntimeException('Invalid database field');
        }
    }
    return $result;
}

/**
 * @template T
 * @param callable(): T $action
 * @return T
 */
function atomic(PDO $db, callable $action): mixed
{
    $db->exec('BEGIN IMMEDIATE');
    try {
        $result = $action();
        $db->exec('COMMIT');
        return $result;
    } catch (Throwable $e) {
        $db->exec('ROLLBACK');
        throw $e;
    }
}

/** @return array<string, mixed> */
function jsonBody(): array
{
    $raw = file_get_contents('php://input', length: 65537);
    if ($raw === false || strlen($raw) > 65536) {
        throw new InvalidArgumentException('Request too large');
    }
    $data = json_decode($raw, true, 32, JSON_THROW_ON_ERROR);
    if (!is_array($data) || array_is_list($data)) {
        throw new InvalidArgumentException('Expected JSON object');
    }
    $result = [];
    foreach ($data as $key => $value) {
        if (!is_string($key)) {
            throw new InvalidArgumentException('Invalid JSON key');
        }
        $result[$key] = $value;
    }
    return $result;
}

/** @param array<string, mixed> $data */
function reply(array $data, int $status = 200): never
{
    http_response_code($status);
    header('Content-Type: application/json; charset=utf-8');
    header('Cache-Control: no-store');
    echo json_encode($data, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);
    exit;
}
PHP · init.php
<?php
declare(strict_types=1);
require __DIR__.'/common.php';
if (PHP_SAPI !== 'cli') {
    exit(1);
}
$path = setting('BOT_DB_PATH');
if (file_exists($path)) {
    throw new RuntimeException('Database already exists');
}
$schema = file_get_contents(__DIR__.'/schema.sql');
if ($schema === false) {
    throw new RuntimeException('Missing schema.sql');
}
$db = new PDO('sqlite:'.$path, options: [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
$db->exec('PRAGMA foreign_keys=ON');
$db->exec($schema);
echo "Database created\n";
Shell · создание базы
php init.php

Создадим код приглашения и неизменяемую привязку

Персональный код — 24 шестнадцатеричных символа. Получится ссылка вида https://t.me/YourShopBot?start=ref_...: это обычный start, не startapp. Код укладывается в ограничение Telegram и не раскрывает последовательный внутренний ID клиента. Бот обрабатывает команду после действия пользователя в Telegram; посещение ссылки в браузере не является регистрацией.

PHP · referrals.php
<?php
declare(strict_types=1);

function joinProgram(PDO $db, int $user, ?string $inviteCode, int $now): string
{
    return atomic($db, function () use ($db, $user, $inviteCode, $now): string {
        $member = row(sql($db, 'SELECT code FROM members WHERE user_id=?', [$user]));
        if ($member !== null) {
            return (string) $member['code'];
        }
        // Resolve before insertion: a new member cannot invite themselves.
        $inviter = $inviteCode === null ? null : row(sql($db,
            'SELECT user_id FROM members WHERE code=?', [$inviteCode]));
        $code = bin2hex(random_bytes(12));
        sql($db, 'INSERT INTO members(user_id,code,joined_at) VALUES(?,?,?)', [$user, $code, $now]);
        if ($inviter !== null && (int) $inviter['user_id'] !== $user) {
            sql($db, 'INSERT INTO referrals(invitee,inviter,bound_at) VALUES(?,?,?)',
                [$user, (int) $inviter['user_id'], $now]);
        }
        return $code;
    });
}

function awardOrder(PDO $db, string $orderId, int $now): bool
{
    return atomic($db, function () use ($db, $orderId, $now): bool {
        $order = row(sql($db, 'SELECT o.*,r.inviter,r.bound_at FROM orders o
            JOIN referrals r ON r.invitee=o.user_id WHERE o.id=?', [$orderId]));
        if ($order === null || $order['status'] !== 'paid' || (int) $order['amount'] < 100000
            || (int) $order['paid_at'] < (int) $order['bound_at']) {
            return false;
        }
        $inserted = sql($db, 'INSERT INTO rewards(program,invitee,inviter,order_id,points,created_at)
            VALUES(?,?,?,?,100,?) ON CONFLICT(program,invitee) DO NOTHING',
            ['first-purchase-v1', (int) $order['user_id'], (int) $order['inviter'], $orderId, $now])->rowCount();
        if ($inserted === 0) {
            return false;
        }
        $reward = (int) $db->lastInsertId();
        sql($db, 'INSERT INTO reward_log(reward_id,user_id,delta,action,created_at) VALUES(?,?,100,?,?)',
            [$reward, (int) $order['inviter'], 'award', $now]);
        return true;
    });
}

function refundOrder(PDO $db, string $orderId, int $now): void
{
    atomic($db, function () use ($db, $orderId, $now): void {
        sql($db, "UPDATE orders SET status='refunded' WHERE id=?", [$orderId]);
        $reward = row(sql($db, 'SELECT * FROM rewards WHERE order_id=? AND reversed_at IS NULL', [$orderId]));
        if ($reward === null) {
            return;
        }
        sql($db, 'INSERT INTO reward_log(reward_id,user_id,delta,action,created_at) VALUES(?,?,?,?,?)',
            [(int) $reward['id'], (int) $reward['inviter'], -(int) $reward['points'], 'reverse', $now]);
        sql($db, 'UPDATE rewards SET reversed_at=? WHERE id=?', [$now, (int) $reward['id']]);
    });
}

function rewardHistory(PDO $db, int $user): string
{
    $sum = row(sql($db, 'SELECT COALESCE(SUM(delta),0) AS total FROM reward_log WHERE user_id=?', [$user]));
    $text = 'Баланс: '.(int) ($sum['total'] ?? 0)." баллов\nПоследние операции:\n";
    $statement = sql($db, 'SELECT delta,action,created_at FROM reward_log WHERE user_id=? ORDER BY id DESC LIMIT 10', [$user]);
    while (($entry = row($statement)) !== null) {
        $text .= gmdate('Y-m-d H:i', (int) $entry['created_at']).' UTC: '
            .($entry['action'] === 'award' ? 'начисление' : 'отмена').' '.(int) $entry['delta']."\n";
    }
    return $text;
}

Функция joinProgram сначала смотрит существующего участника. Если запись есть, она возвращает его код и не меняет связи. Для нового участника пригласивший ищется до вставки: собственный ещё не созданный код невозможно использовать. Дополнительные проверки invitee ≠ inviter стоят и в коде, и в базе.

Параллельные первые сообщения сериализуются транзакцией. Побеждает первый зафиксированный вход, а не тот, который пользователь считает последним. Это выбранная модель атрибуции; расскажите о ней поддержке, чтобы оператор не обещал сменить пригласившего задним числом. Переходы по другим ссылкам можно хранить как аналитику отдельно от награды.

Подключим команды бота

PHP · telegram.php
<?php
declare(strict_types=1);

/**
 * @param array<string, mixed> $params
 * @return array{state: string, result?: mixed, code?: int, retry_after?: int}
 */
function telegram(string $method, array $params, bool $multipart = false): array
{
    $curl = curl_init('https://api.telegram.org/bot'.setting('BOT_TOKEN').'/'.$method);
    curl_setopt_array($curl, [
        CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 3, CURLOPT_TIMEOUT => 8,
        CURLOPT_POSTFIELDS => $multipart ? $params : json_encode($params, JSON_THROW_ON_ERROR),
        CURLOPT_HTTPHEADER => $multipart ? [] : ['Content-Type: application/json'],
    ]);
    $raw = curl_exec($curl);
    $status = (int) curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
    if (!is_string($raw) || $status >= 500) {
        return ['state' => 'unknown'];
    }
    $data = json_decode($raw, true);
    if (!is_array($data)) {
        return ['state' => 'unknown'];
    }
    if (($data['ok'] ?? null) === true) {
        return ['state' => 'ok', 'result' => $data['result'] ?? null];
    }
    if (($data['ok'] ?? null) !== false || !is_int($data['error_code'] ?? null)) {
        return ['state' => 'unknown'];
    }
    $parameters = $data['parameters'] ?? null;
    $delay = is_array($parameters) ? ($parameters['retry_after'] ?? null) : null;
    return ['state' => 'rejected', 'code' => $data['error_code'],
        'retry_after' => is_int($delay) && $delay > 0 ? $delay : 60];
}

/** @return array<string, mixed> */
function incomingUpdate(): array
{
    $secret = $_SERVER['HTTP_X_TELEGRAM_BOT_API_SECRET_TOKEN'] ?? '';
    if (($_SERVER['REQUEST_METHOD'] ?? '') !== 'POST' || !is_string($secret)
        || !hash_equals(setting('WEBHOOK_SECRET'), $secret)) {
        reply(['error' => 'Forbidden'], 403);
    }
    return jsonBody();
}
PHP · public/webhook.php
<?php
declare(strict_types=1);
require dirname(__DIR__).'/common.php';
require dirname(__DIR__).'/telegram.php';
require dirname(__DIR__).'/referrals.php';
$update = incomingUpdate();
$message = $update['message'] ?? null;
$chat = is_array($message) ? ($message['chat'] ?? null) : null;
$from = is_array($message) ? ($message['from'] ?? null) : null;
if (!is_int($update['update_id'] ?? null) || !is_array($message) || !is_array($chat)
    || !is_array($from) || ($chat['type'] ?? '') !== 'private'
    || !is_int($from['id'] ?? null) || ($chat['id'] ?? null) !== $from['id']) {
    reply(['ok' => true]);
}
$user = $from['id'];
$text = is_string($message['text'] ?? null) ? $message['text'] : '';
$inviteCode = preg_match('/^\/start(?:@[a-zA-Z0-9_]+)? ref_([a-f0-9]{24})$/D', $text, $match) ? $match[1] : null;
$db = database();
// Every first private message fixes whether this user arrived by referral.
$code = joinProgram($db, $user, $inviteCode, time());
$answer = $text === '/balance' ? rewardHistory($db, $user) :
    'Ваша ссылка: https://t.me/'.setting('BOT_USERNAME').'?start=ref_'.$code
    ."\n100 баллов за нового клиента после оплаченной покупки от 1000 рублей. Баланс: /balance";
if (sql($db, 'INSERT OR IGNORE INTO updates(id) VALUES(?)', [$update['update_id']])->rowCount() === 1) {
    $result = telegram('sendMessage', ['chat_id' => $user, 'text' => $answer]);
    if ($result['state'] !== 'ok') {
        error_log('referral_reply_'.$result['state'].' update='.$update['update_id']);
    }
}
reply(['ok' => true]);

Обработчик принимает только личные сообщения и берёт ID из from.id, проверяя соответствие личному чату. Любое первое сообщение создаёт участника, поэтому нельзя сначала пользоваться ботом, а потом получить статус приглашённого через /start. /balance показывает только историю текущего пользователя — ID получателя из текста команды не принимается.

Повтор update_id не меняет привязку и не отправляет ещё один автоматический ответ. Отправка находится после записи фактов в базу. Если ответ потерян, пользователь может запросить /balance или снова написать боту; финансовая часть от ответа Telegram не зависит.

Зарегистрируйте прямой webhook Telegram следующим CLI-скриптом. Здесь принимаются только обновления message; если у бота уже есть обработчики других событий, сохраните их в общем обработчике и в allowed_updates, вместо установки второго webhook. Один бот не использует одновременно этот webhook и getUpdates.

PHP · setup-webhook.php
<?php
declare(strict_types=1);
require __DIR__.'/common.php';
require __DIR__.'/telegram.php';
if (PHP_SAPI !== 'cli') {
    exit(1);
}
$url = setting('WEBHOOK_URL');
if (!str_starts_with($url, 'https://')) {
    throw new RuntimeException('HTTPS webhook required');
}
$result = telegram('setWebhook', [
    'url' => $url, 'secret_token' => setting('WEBHOOK_SECRET'),
    'allowed_updates' => ['message'],
]);
if ($result['state'] !== 'ok') {
    throw new RuntimeException('Webhook not confirmed');
}
echo "Webhook configured\n";
Shell · настройка webhook
php setup-webhook.php

Начислим бонус после подтверждённого действия

awardOrder читает существующий заказ из серверной таблицы. Здесь нет HTTP-маршрута «начислить мне бонус» и нет доверия к сумме из браузера. Ваш обработчик подтверждённой оплаты сначала сохраняет orders с проверенным владельцем, суммой и paid_at, затем после commit вызывает awardOrder. Связь владельца заказа с Telegram должна уже быть проверена, например по привязке аккаунта сайта.

PHP · вызов из серверного обработчика после commit
<?php
declare(strict_types=1);
// common.php и referrals.php уже подключены приложением.
// $orderId получен из проверенного платёжного события и найден в вашей БД.
// Это точка интеграции, а не публичный обработчик произвольного POST.
awardOrder($db, $orderId, time());

Уникальность (program, invitee) защищает от двух разных событий и даже от двух разных подходящих заказов одного приглашённого. Добавление награды и строки +100 происходит одной транзакцией: нет окна, где право на награду занято, а баланс ещё не увеличен. Telegram update_id для этого недостаточен — оплаты могут приходить из другого источника.

Встроенный пример orders — минимальная модель магазина. Он не заменяет проверку подписи платёжного провайдера и сверку суммы с ценой на сервере. Для Stars точка вызова находится после successful_payment, как показано в статье об оплате цифрового доступа. Не начисляйте бонус по экрану «Оплачено» в Mini App.

Восстановим пропущенное начисление

Между сохранением оплаты и вызовом функции процесс может остановиться. Поэтому нужен способ найти оплаченные заказы без награды. Следующий CLI-скрипт обходит подходящие записи небольшими партиями; его можно запускать раз в минуту. Несколько запусков не умножают баллы благодаря тому же ограничению в БД.

PHP · reconcile.php
<?php
declare(strict_types=1);
require __DIR__.'/common.php';
require __DIR__.'/referrals.php';
if (PHP_SAPI !== 'cli') {
    exit(1);
}
$db = database();
// Work in bounded batches. Terminal/ineligible orders are excluded from selection.
$statement = sql($db, "SELECT o.id FROM orders o JOIN referrals r ON r.invitee=o.user_id
    WHERE o.status='paid' AND o.amount>=100000 AND o.paid_at>=r.bound_at
    AND NOT EXISTS (SELECT 1 FROM rewards w WHERE w.program='first-purchase-v1' AND w.invitee=o.user_id)
    ORDER BY o.paid_at,o.id LIMIT 100");
$ids = [];
while (($order = row($statement)) !== null) {
    $ids[] = (string) $order['id'];
}
$statement->closeCursor();
foreach ($ids as $id) {
    awardOrder($db, $id, time());
}
echo "Reconciled\n";
Shell · повторная обработка
php reconcile.php

Ответ Reconciled означает завершение партии, а не наличие начисления для каждого заказа. Посмотрите rewards и reward_log: заказы ниже порога, до привязки, без пригласившего и уже награждённые должны оставаться без новой записи. При большом объёме добавьте индексы, курсор обхода и наблюдение за отставанием, сохраняя атомарное правило начисления.

Отменим награду и сохраним историю

refundOrder вызывается из доверенного обработчика подтверждённого полного возврата. Он меняет статус заказа и добавляет −100 в одной транзакции. Если возврат пришёл раньше попытки начисления, awardOrder увидит refunded и ничего не выдаст. Если позже — баланс вернётся к прежнему значению. Повтор возврата не добавит вторую отрицательную операцию.

В примере начисленные баллы нельзя тратить, поэтому отрицательный остаток после возврата не возникает. При добавлении списаний нужно заранее определить поведение для уже потраченного бонуса: долг, лимит списания или резерв до окончания периода возврата. Частичный возврат также требует отдельного правила — механически вызывать полный откат для любого refund неверно.

Сумма reward_log — источник баланса. В истории пользователя не показываются Telegram ID приглашённых, состав их покупок и суммы заказов. Сотрудник может видеть связь с order_id в закрытом интерфейсе, но для поддержки полезнее номер операции, причина и время, чем выгрузка персональных данных.

Прогоним пример без реальных покупок

Для первой проверки используйте отдельную пустую базу. Следующий файл создаёт двух вымышленных участников, тестовый оплаченный заказ, дважды вызывает начисление и дважды — возврат. Он работает только в CLI при DEMO_MODE=1. Не оставляйте демонстрационные заказы в рабочей базе.

PHP · demo.php
<?php
declare(strict_types=1);
require __DIR__.'/common.php';
require __DIR__.'/referrals.php';
if (PHP_SAPI !== 'cli' || getenv('DEMO_MODE') !== '1') {
    exit(1);
}
$db = database();
$now = time();
$code = joinProgram($db, 1001, null, $now);
joinProgram($db, 1002, $code, $now);
sql($db, "INSERT INTO orders(id,user_id,amount,paid_at,status) VALUES('demo-order',1002,150000,?,'paid')
    ON CONFLICT(id) DO NOTHING", [$now]);
awardOrder($db, 'demo-order', $now);
awardOrder($db, 'demo-order', $now);
echo rewardHistory($db, 1001);
refundOrder($db, 'demo-order', $now);
refundOrder($db, 'demo-order', $now);
echo rewardHistory($db, 1001);
Shell · тест на отдельной базе
DEMO_MODE=1 php demo.php

В первом выводе баланс должен быть 100 и одна операция начисления, во втором — 0 и ровно две операции: +100 и −100. Повтор demo.php не даст новую награду, поскольку тот же заказ уже возвращён. Для повторения исходного сценария создайте новую тестовую базу, а не очищайте рабочую.

  • Существующий пользователь открывает собственную ссылку: referrals не пополняется.

  • Новый пользователь приходит по коду A, затем по коду B: пригласивший остаётся A.

  • Два обработчика одновременно вызывают awardOrder для одного заказа: появляется одна награда и одна строка +100.

  • Два разных заказа одного приглашённого проходят обработку: в этой программе награда всё равно одна.

  • Сбой сразу после сохранения orders исправляется запуском reconcile.php.

  • Заказ со статусом refunded и заказ меньше 100000 копеек не увеличивают баланс.

Telegram ID обозначает аккаунт, а не уникального человека. Запрет самоприглашения одного ID не остановит владельца нескольких аккаунтов. Для ценных вознаграждений полезны проверяемое полезное действие, ограничения программы и ручная проверка подозрительных серий; не обещайте абсолютную защиту от накрутки одной проверкой /start.

Где здесь помогает BotGate

Связи пользователей и журнал баллов остаются в вашей БД; BotGate может использоваться для обмена сообщениями с Telegram. Если после начисления добавите уведомление, сбой отправки не должен отменять уже зафиксированный бонус или приводить к повторному начислению. Разделяйте награду и её доставку по руководству о дублях.

Первичные источники: deep linking Telegram, транзакции SQLite. Для источников без бонусной программы есть отдельная статья про start-параметры; для подключения транспорта — документация BotGate.