When to use this

Send users a https://t.me/yourbot?start=ref_abc link and pick up the payload server-side. Useful for referral codes, magic-login tokens, and product deep-links. The framework builds the URL and the CommandStart filter extracts the payload on receipt.

Solution

use Gruven\PhpBotGram\Filters\CommandStart;
use Gruven\PhpBotGram\Filters\CommandObject;
use Gruven\PhpBotGram\Types\Message;
use Gruven\PhpBotGram\Utils\DeepLinking;

// Building the link.
$link = DeepLinking::createStartLink($bot, payload: 'ref_abc', encode: false);
// → https://t.me/yourbot?start=ref_abc

// Handling the incoming /start with payload.
$dispatcher->message->register(
    static function (Message $event, CommandObject $command): void {
        $payload = $command->args ?? '';
        $event->answer("Welcome! Your ref code: {$payload}")->emit();
    },
    filters: [new CommandStart(deepLink: true)],
);

DeepLinking::createStartLink caches the bot's username via a WeakMap so subsequent calls don't re-hit getMe . Pass encode: true (or a custom encoder) to base64 arbitrary payloads — raw payloads are limited to [A-Za-z0-9_-] and 64 characters. On receipt, the CommandObject injected by CommandStart carries the unencoded payload in $command->args .

Pitfalls

• Telegram caps the raw payload at 64 ASCII characters. Anything outside [A-Za-z0-9_-] throws InvalidArgumentException . Use encode: true for arbitrary strings.
• createStartLink requires the bot to have a username — bots without one (rare) throw LogicException from the first call.
• The payload arrives after the /start token. Use CommandStart not plain Command so the framework normalises the parse.
• See Filters for CommandObject semantics.