Authorization, Callbacks and Bot Credentials

Raw MD
Actor checks, trusted data, credential boundaries and sandbox-aware code.

The runtime helps separate bot contexts. Your application must still decide which user can run each action. A callback button is an interface, not permission to execute the action it names.

Authorize using the actor

For a message command, the actor is message.from.id. For a callback, use callback_query.from.id. Do not use the chat ID as a substitute for the actor ID in a group. Channel posts may not contain an ordinary from user; handle that case explicitly.

Code example
$callback = $update['callback_query'] ?? null;
$message = $update['message'] ?? null;
$actorId = $callback['from']['id'] ?? $message['from']['id'] ?? null;
$adminId = (string)(getenv('ADMIN_CHAT_ID') ?: '');
$isAdmin = $adminId !== '' && $actorId !== null
    && (string)$actorId === $adminId;
if (!$isAdmin) {
    // Reject privileged actions before changing application state.
    return;
}

Use this pattern only around an admin route, not around every update if your bot is intended to serve regular users. If multiple administrators are supported, load the allowlist from trusted configuration or database state.

Acknowledge callbacks and validate actions

Code example
tg_all_fun();
$callback = $update['callback_query'] ?? null;
if ($callback !== null) {
    tg_answer_cb($callback['id']);
    $action = (string)($callback['data'] ?? '');
    if (!in_array($action, ['show_help', 'show_profile'], true)) {
        return;
    }
    // Route only allowed actions and scope profile data to callback.from.id.
}

Keep callback payloads compact. Treat embedded record IDs as untrusted input: verify that the actor owns or may access the record. Old buttons can remain in chat after state changes. Re-check state at execution time rather than trusting the time the button was created.

Some callbacks refer to inline messages rather than an ordinary message.chat/message_id pair. Handle inline_message_id separately. Do not assume every callback contains an accessible chat message.

Protect tokens and transport

Use the selected bot's environment. Do not commit tokens into example code or return them in JSON responses. Avoid logging complete request URLs: Telegram file-download URLs can contain the token. Keep .env outside published artifacts and preserve it during code deployment.

Plain PHP/cURL code should verify TLS peer and hostname. Enabling HTTPS protocol support is not the same as verifying the remote certificate. If a hosting certificate-chain problem occurs, repair the CA configuration rather than disabling verification in copied examples.

An optional token argument changes which bot sends a request. Ordinary hosted helper calls should generally use automatic active-bot resolution. Only explicitly pass a different token in a deliberately authorized multi-bot workflow.

Mini App trust boundary

Data received from a browser is not proof of Telegram identity. Validate init data using the correct bot token, enforce an appropriate auth_date freshness policy, and apply application authorization after validation. Do not infer order prices, account balances or admin status from user-controlled Mini App fields.

The existing tg_verify_init_data helper returns user data or null after its implemented checks. Read its actual behavior: a helper name does not imply every freshness/replay policy your application requires. Implement the missing application policy explicitly.

Sandbox-compatible code

Hosted scripts are audited for blocked operations. Shell/process execution, dynamic evaluation, several directory-enumeration operations and selected platform internals are blocked in the current sandbox. Use ordinary PHP with known paths and supported extensions; do not try to evade the audit by hiding function names.

The platform exposes a virtualized runtime context. Do not depend on private host paths, scan other users' folders or connect through the platform's internal database functions. A sandbox rejection is not an instruction to switch to an obfuscated implementation.

Test authorization explicitly

Test the same action as an administrator and a regular user. Confirm that unauthorized attempts produce no database write and no privileged API call. Also test stale callback data, missing from fields and deleted records. Never test ban/delete operations against unrelated production users.

See runtime guide, sandbox reference, and complete helper reference.