Перейти к содержанию
23 минут чтения
Тема: Практика Telegram Mini Apps · shareMessage · Карточки товаров · PHP

Как добавить кнопку «Поделиться» в Telegram Mini App

Для примера пользователь магазина отправит другу карточку синей кружки: название, публичную цену и ссылку. Сервер подготовит сообщение через Bot API, а Mini App откроет выбор чата по кнопке «Поделиться». Пользователь сам решает, куда отправить карточку, и может закрыть окно. В сообщение не попадут его корзина, адрес и сведения о заказе.

Что именно отправляет кнопка «Поделиться»

Связка состоит из двух операций: сервер создаёт PreparedInlineMessage для конкретного пользователя, затем браузер передаёт его ID в shareMessage. Этот ID не равен message_id из обычной отправки ботом. Создание заготовки ещё не отправляет сообщение в чужой чат и не означает, что пользователь чем-то поделился.

В статье используем публичную карточку товара. Тот же порядок подходит для приглашения на мероприятие или обезличенного результата расчёта. Для каждого типа заранее определите разрешённые поля. Превращать произвольный JSON из клиентского экрана в сообщение опасно: вместе с видимым названием в объекте могут находиться телефон, персональная скидка или токен доступа.

  • Сервер принимает только идентификатор публичного объекта и самостоятельно собирает сообщение.

  • ID пользователя берётся из проверенного initData, а не из тела POST.

  • Перед отправкой показываем текст, который получит друг.

  • Отмена окна не запускает sendMessage и не записывается как успешная отправка.

Здесь не нужен запрос requestWriteAccess: он относится к праву бота писать пользователю, а не к выбору чата для подготовленной карточки. Не запрашивайте лишнее разрешение как условие кнопки «Поделиться».

Подготовим Mini App и сервер

Нужен отдельный тестовый бот, PHP 8.3+ с cURL и HTTPS-сайт. Создайте папку public для публичных файлов; common.php, auth.php, telegram.php и card.php оставьте на уровень выше. База данных для этого примера не требуется: каталог из двух товаров задан на сервере, а заготовку хранит Telegram.

Окружение · значения процесса
BOT_TOKEN=TOKEN_FROM_BOTFATHER
PUBLIC_SHOP_URL=https://shop.example.com

Настройте эти переменные в PHP-FPM. Самостоятельный PHP не загружает .env автоматически. PUBLIC_SHOP_URL замените на действующий адрес своего магазина; страницы /products/mug-blue и /products/notebook должны быть публичными и показывать актуальную цену. Токен бота в HTML не вставляется.

В BotFather настройте кнопку меню на HTTPS-адрес share.html. Открывайте страницу через эту кнопку Mini App: просто открыть URL в браузере недостаточно для авторизации. shareMessage требует поддержки версии 8.0; ниже есть проверка и запасной вариант с обычной публичной ссылкой.

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;
}

/** @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;
}

Запросы страницы передают исходную строку Telegram.WebApp.initData в заголовке X-Telegram-Init-Data. Сервер проверяет HMAC и срок действия и берёт Telegram ID только из подписанных данных. В этом небольшом примере нет cookie-сессии: каждый POST заново авторизуется, поэтому отдельный CSRF-токен не нужен. Не включайте разрешающий CORS, не переносите авторизацию в query string и не сохраняйте этот заголовок в журналах.

Через десять минут после запуска сервер попросит открыть Mini App заново. Это выбранный срок нашего примера, а не лимит Telegram. Для долгой работы обменяйте проверенный initData на серверную сессию с CSRF-защитой по отдельному руководству. Проверка подписи подтверждает пользователя, но не назначает ему права сотрудника.

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

function miniUser(string $raw, string $token, int $now): int
{
    if ($raw === '' || strlen($raw) > 16384) {
        throw new InvalidArgumentException('Open Mini App again');
    }
    $fields = [];
    foreach (explode('&', $raw) as $part) {
        $pair = explode('=', $part, 2);
        if (count($pair) !== 2) {
            throw new InvalidArgumentException('Invalid initData');
        }
        $key = urldecode($pair[0]);
        if (array_key_exists($key, $fields)) {
            throw new InvalidArgumentException('Duplicate initData field');
        }
        $fields[$key] = urldecode($pair[1]);
    }
    $hash = $fields['hash'] ?? '';
    unset($fields['hash']);
    ksort($fields, SORT_STRING);
    $lines = [];
    foreach ($fields as $key => $value) {
        $lines[] = $key.'='.$value;
    }
    $secret = hash_hmac('sha256', $token, 'WebAppData', true);
    $expected = hash_hmac('sha256', implode("\n", $lines), $secret);
    $date = $fields['auth_date'] ?? '';
    if (!preg_match('/^[a-f0-9]{64}$/D', $hash) || !hash_equals($expected, $hash)
        || !ctype_digit($date) || (int) $date < $now - 600 || (int) $date > $now + 30) {
        throw new InvalidArgumentException('Expired or invalid initData');
    }
    $user = json_decode($fields['user'] ?? '', true, 16, JSON_THROW_ON_ERROR);
    if (!is_array($user) || !is_int($user['id'] ?? null) || $user['id'] < 1) {
        throw new InvalidArgumentException('Missing Telegram user');
    }
    return $user['id'];
}

function authenticatedUser(): int
{
    if (($_SERVER['REQUEST_METHOD'] ?? '') !== 'POST') {
        reply(['error' => 'POST required'], 405);
    }
    $raw = $_SERVER['HTTP_X_TELEGRAM_INIT_DATA'] ?? '';
    try {
        return miniUser(is_string($raw) ? $raw : '', setting('BOT_TOKEN'), time());
    } catch (InvalidArgumentException|JsonException) {
        reply(['error' => 'Откройте Mini App заново'], 401);
    }
}

Соберём только публичную карточку

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

/** @return array{sku:string,title:string,text:string,url:string} */
function publicCard(string $sku): array
{
    // Replace this catalog with a SELECT of public fields and publication status.
    $products = [
        'mug-blue' => ['title' => 'Синяя кружка, 350 мл', 'price' => 650],
        'notebook' => ['title' => 'Блокнот для заметок', 'price' => 390],
    ];
    $product = $products[$sku] ?? null;
    if ($product === null) {
        throw new DomainException('Товар не опубликован');
    }
    $base = rtrim(setting('PUBLIC_SHOP_URL'), '/');
    if (!str_starts_with($base, 'https://')) {
        throw new RuntimeException('HTTPS public shop URL required');
    }
    $url = $base.'/products/'.rawurlencode($sku);
    return ['sku' => $sku, 'title' => $product['title'],
        'text' => $product['title']."\nЦена на момент подготовки: ".$product['price']." ₽\n".$url,
        'url' => $url];
}

/**
 * @param array{sku:string,title:string,text:string,url:string} $card
 * @return array<string,mixed>
 */
function preparedPayload(int $user, array $card): array
{
    return [
        'user_id' => $user,
        'result' => [
            'type' => 'article', 'id' => hash('sha256', $card['sku'].'|'.$card['text']),
            'title' => $card['title'],
            'input_message_content' => ['message_text' => $card['text']],
            'reply_markup' => ['inline_keyboard' => [[['text' => 'Открыть товар', 'url' => $card['url']]]]],
        ],
        'allow_user_chats' => true, 'allow_group_chats' => true,
        'allow_bot_chats' => false, 'allow_channel_chats' => false,
    ];
}

В рабочем проекте замените массив на выборку разрешённых полей товара с условием is_published. Для закрытого товара верните 404, даже если пользователь знает его SKU. Ссылка строится из серверной настройки домена; URL из браузера не принимается, чтобы кнопку магазина нельзя было подменить ссылкой на чужой ресурс.

У результата тип article, а текст находится в input_message_content.message_text. Parse mode не задаётся: название вроде «Кружка <лето>» останется обычным текстом. ID результата ограничен хешем; он нужен для описания результата и не заменяет ID PreparedInlineMessage из ответа Telegram.

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

Цена в отправленном сообщении — снимок на момент подготовки, поэтому прямо подписываем её так. При изменении цены старые сообщения у друзей сами не обновятся. Финальная цена и наличие должны проверяться на странице товара и сервере оформления заказа.

Подготовим сообщение через Bot API

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];
}
PHP · public/prepare.php
<?php
declare(strict_types=1);
require dirname(__DIR__).'/common.php';
require dirname(__DIR__).'/auth.php';
require dirname(__DIR__).'/telegram.php';
require dirname(__DIR__).'/card.php';
$user = authenticatedUser();
try {
    $body = jsonBody();
    if (!is_string($body['sku'] ?? null) || !preg_match('/^[a-z0-9-]{1,40}$/D', $body['sku'])) {
        reply(['error' => 'Неверный товар'], 422);
    }
    $card = publicCard($body['sku']);
    $result = telegram('savePreparedInlineMessage', preparedPayload($user, $card));
    if ($result['state'] !== 'ok') {
        if (($result['code'] ?? 0) === 429) {
            header('Retry-After: '.($result['retry_after'] ?? 60));
            reply(['error' => 'Слишком много запросов. Попробуйте позже.'], 429);
        }
        reply(['error' => 'Не удалось подготовить карточку. Повторите подготовку.'], 502);
    }
    $prepared = $result['result'] ?? null;
    if (!is_array($prepared) || !is_string($prepared['id'] ?? null)
        || !is_int($prepared['expiration_date'] ?? null) || $prepared['expiration_date'] <= time()) {
        reply(['error' => 'Получен неверный ответ Telegram'], 502);
    }
    reply(['id' => $prepared['id'], 'expires_at' => $prepared['expiration_date'],
        'valid_for' => max(0, $prepared['expiration_date'] - time()), 'preview' => $card['text'], 'url' => $card['url']]);
} catch (DomainException $e) {
    reply(['error' => $e->getMessage()], 404);
} catch (InvalidArgumentException|JsonException) {
    reply(['error' => 'Неверный JSON'], 422);
}

savePreparedInlineMessage получает user_id, result и разрешённые типы чатов. При JSON-запросе result передаём вложенным объектом: наш транспорт сериализует весь запрос один раз. Не превращайте вложенный объект в строку без необходимости и не отправляйте токен Telegram из браузера.

Из ответа возвращаем только ID, срок действия, публичный предпросмотр и ссылку. Срок берём из expiration_date; не придумываем «заготовка живёт ровно сутки». Дополнительно сервер отдаёт valid_for, чтобы интерфейс не полагался на правильно выставленные часы телефона. Перед самым вызовом всё равно проверяем, что срок не вышел.

Таймаут подготовки отличается от таймаута отправки сообщения: savePreparedInlineMessage не доставляет карточку получателю. Повторная явная подготовка допустима — получится ещё одна заготовка, но не лишнее сообщение другу. При 429 отдаём Retry-After, чтобы кнопка не создавала бесконечные повторные запросы.

В рабочем приложении ограничьте частоту подготовки по авторизованному пользователю и добавьте короткий кэш по пользователю, объекту и версии содержимого. Не делайте один глобальный prepared_id на весь товар: заготовка выдана конкретному user_id. Не храните её в общем HTML-кэше, который обслуживает всех посетителей.

Откроем окно отправки после нажатия

HTML и JavaScript · public/share.html
<!doctype html>
<html lang="ru"><meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Поделиться товаром</title>
<script src="https://telegram.org/js/telegram-web-app.js"></script>
<style>
body{font:17px system-ui;padding:16px;color:var(--tg-theme-text-color,#111);background:var(--tg-theme-bg-color,#fff)}
button,input{padding:14px;margin:12px 0;width:100%;box-sizing:border-box;font:inherit}
pre{white-space:pre-wrap;overflow-wrap:anywhere;font:inherit}button{min-height:48px}
</style>
<h1>Поделиться товаром</h1>
<p>Друг получит только эту публичную карточку:</p>
<pre id="preview">Подготовка…</pre>
<button id="prepare">Подготовить заново</button>
<button id="share" disabled>Поделиться</button>
<label>Публичная ссылка <input id="link" readonly aria-label="Публичная ссылка"></label>
<p id="status" role="status" aria-live="polite"></p>
<script>
const tg = window.Telegram?.WebApp;
const el = id => document.getElementById(id);
let prepared = null, preparing = false, sharing = false;
let retryAt = 0;
const supported = Boolean(tg?.isVersionAtLeast('8.0') && typeof tg.shareMessage === 'function');
async function prepare() {
  if (preparing || sharing) return;
  if (performance.now() < retryAt) {el('status').textContent = 'Подождите перед повтором.'; return;}
  preparing = true; prepared = null;
  el('share').disabled = true; el('prepare').disabled = true;
  const started = performance.now();
  try {
    const response = await fetch('prepare.php', {method:'POST',
      headers:{'Content-Type':'application/json','X-Telegram-Init-Data':tg?.initData || ''},
      body:JSON.stringify({sku:'mug-blue'})});
    if (response.status === 429) retryAt = performance.now() + Number(response.headers.get('Retry-After') || 60) * 1000;
    const data = await response.json();
    if (!response.ok) throw new Error(data.error || 'Ошибка подготовки');
    prepared = {id:data.id, deadline:started + Math.max(0, data.valid_for - 5) * 1000};
    el('preview').textContent = data.preview; el('link').value = data.url;
    el('share').disabled = !supported;
    el('status').textContent = supported ? 'Карточка готова. Выберите «Поделиться».' : 'Обновите Telegram или выделите и скопируйте публичную ссылку.';
  } catch (error) {el('status').textContent = error.message;}
  finally {preparing = false; el('prepare').disabled = false;}
}
el('prepare').onclick = prepare;
el('link').onclick = () => el('link').select();
el('share').onclick = () => {
  if (sharing || !prepared || !supported) return;
  if (performance.now() >= prepared.deadline) {
    el('share').disabled = true; prepared = null;
    el('status').textContent = 'Срок карточки истёк. Подготовьте её заново.'; return;
  }
  sharing = true; el('share').disabled = true; el('prepare').disabled = true;
  try {
    tg.shareMessage(prepared.id, sent => {
      sharing = false; el('share').disabled = false; el('prepare').disabled = false;
      el('status').textContent = sent ? 'Telegram подтвердил отправку карточки.' : 'Отправка не подтверждена: окно закрыто или произошла ошибка. Можно повторить.';
    });
  } catch (error) {
    sharing = false; prepared = null; el('prepare').disabled = false;
    el('status').textContent = 'Не удалось открыть отправку. Подготовьте карточку заново.';
  }
};
tg?.ready(); prepare();
</script></html>

Страница сначала готовит карточку и показывает текст. Кнопка «Поделиться» становится доступной после успешного ответа. Нативное окно открывается непосредственно по нажатию, без промежуточного сетевого запроса. Пока окно открыто, повторное нажатие заблокировано.

Публичная карточка синей кружки за 650 ₽ в HTML-примере, выбор получателя и сообщение с кнопкой Открыть товар; отмена не означает отправку.
Публичная карточка синей кружки за 650 ₽ в HTML-примере, выбор получателя и сообщение с кнопкой Открыть товар; отмена не означает отправку.
Увеличенный фрагмент HTML статьи с тестовой карточкой. Выбор чата и сообщение показаны схемой, не снимками Telegram. Домен магазина условный.

Когда срок истёк, предлагаем подготовить карточку заново. Новая заготовка может содержать изменившуюся цену или описание: пользователь снова увидит предпросмотр перед отправкой. Кнопка повторной подготовки также полезна после ошибки Telegram; автоматической серии вызовов здесь нет.

На старом клиенте отображается публичная ссылка в поле для выделения и копирования. Это более скромный сценарий: пользователь сам вставляет её в сообщение, а приложение не получает подтверждения отправки. Не вызывайте shareMessage без проверки версии и не маскируйте копирование ссылки сообщением «Карточка отправлена».

Отмена, ошибка и аналитика

Callback shareMessage передаёт признак успешной отправки. true позволяет показать подтверждение Telegram. false нельзя надёжно трактовать только как осознанную отмену: интерфейс пишет, что отправка не подтверждена, и разрешает повтор. Если клиент выбросил исключение до открытия окна, заготовка сбрасывается и предлагается подготовка заново.

Не вызывайте от имени бота sendMessage после false, чтобы «дослать» карточку: пользователь мог специально отказаться, а выбранного получателя у вашего сервера вообще нет. Закрытие Mini App до callback также оставляет результат неизвестным. Не превращайте отсутствие события в доказанную ошибку доставки.

Для продуктовой аналитики можно различать подготовку, нажатие и callback с подтверждением. Эти события приходят из клиентского JavaScript, их можно подделать. Не начисляйте деньги или реферальные баллы за такой callback. Для реферальной программы основанием служит подтверждённое действие нового клиента на сервере.

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

Приглашение или расчёт без утечки личных данных

Для приглашения отправляйте общедоступную страницу события или реферальный код, предназначенный для распространения. Нельзя использовать вместо него одноразовую ссылку входа в кабинет, QR-билет для прохода или URL восстановления пароля: получатель получит соответствующее право, а сообщение может быть переслано дальше.

Для результата расчёта заведите отдельную публичную версию: тип услуги, ориентировочная сумма и краткие параметры без ФИО, адреса, телефона и внутренних комментариев. Публичный идентификатор должен быть случайным, а сервер — возвращать только поля этой версии. Приватный заказ остаётся за проверкой владельца, как в статье о ссылках на товары и заказы.

Видимая пользователю карточка не всегда совпадает с тем, что разрешено распространять. Например, цена по персональному договору или индивидуальная скидка могут быть доступны владельцу, но не его друзьям. Поэтому publicCard — отдельная серверная функция с белым списком полей, а не сериализация всей модели заказа.

Уже отправленное сообщение и его копии нельзя считать отзываемыми вместе с истечением prepared_id. Истечение запрещает дальнейшее использование заготовки, но не удаляет сообщения в чужих чатах. Не помещайте туда данные, которые вы обещаете автоматически скрыть через час.

Проверим подготовку и отправку

  • Откройте Mini App тестовым аккаунтом. Убедитесь, что предпросмотр совпадает с сообщением, отправленным в свой тестовый чат.

  • Подмените user_id и text в POST: сервер должен их игнорировать, используя подписанного пользователя и каталог.

  • Передайте неизвестный SKU: получите 404 без заготовки. Поддельный или просроченный initData должен дать 401.

  • Закройте окно выбора чата: интерфейс не сообщает об успешной отправке и не отправляет ничего ботом.

  • Откройте страницу двумя пользователями: каждому готовится свой ID. Не копируйте prepared_id между аккаунтами.

  • Проверьте ветку истечения, подставив прошедший deadline только в тестовой копии интерфейса: окно не вызывается до повторной подготовки.

  • Проверьте старый клиент или отключённую поддержку shareMessage: остаётся доступная для копирования публичная ссылка.

В автоматических тестах подменяйте ответ savePreparedInlineMessage и callback интерфейса. Реальное окно выбора чата и фактическое сообщение проверяются отдельно в Telegram на iPhone и Android; HTTP 200 вашего prepare.php этого не доказывает.

BotGate и документация методов

BotGate может выступать транспортом серверного запроса к Bot API. Подготовка полей, проверка initData и решение о публичности данных остаются в вашем приложении; shareMessage вызывается в клиенте Telegram. Параметры подключения сервиса приведены в документации. Подключение шлюза не заменяет подтверждение пользователя в окне отправки.

Первичные источники: shareMessage, savePreparedInlineMessage, PreparedInlineMessage и expiration_date, InlineQueryResultArticle.