Botlify Runtime: From Webhook to Bot Code

Raw MD
Understand entrypoints, environment, sandbox, PHP versions and request lifecycles.

Hosted webhook lifecycle

Telegram delivers an update to the platform webhook. The gateway resolves the bot, sets the child-bot context, loads platform bootstrap, prepares tracking and error handling, audits the entrypoint, and enters the bot sandbox before executing index.php. Hosted code reads the update from php://input. It should inspect the update shape before accessing a message: updates also include callback queries, edited messages and other event types.

The gateway uses HTTP acknowledgements and error handling to avoid endless failed-update loops in handled error paths. A 200 response is not proof that your bot’s business action succeeded. Keep a durable record of important operations and distinguish “update received” from “payment/order fulfilled”.

Environment and credentials

NamePurpose
BOT_TOKENCurrent hosted bot credential. Never put it in public examples, logs or browser code.
BOT_USERNAMEBot username provided by the hosted environment.
ADMIN_CHAT_IDConfigured bot administrator/owner fallback used by the runtime.
OWNER_CHAT_IDPlatform owner identifier for this bot.
BOT_IDBot identifier supplied by platform metadata.
PHP
$token = (string)(getenv('BOT_TOKEN') ?: '');
$adminId = (string)(getenv('ADMIN_CHAT_ID') ?: '');
// Validate only what your operation requires; do not print credentials.

The sandbox exports the bot variables into the process environment. Native token resolution supports an explicit token, bot-specific constants/context and the environment, with a guard against falling back to platform credentials in a child context. Prefer omitting the optional token in ordinary hosted helper calls. If writing standalone PHP, provide your own environment: PHP does not universally parse .env files automatically.

Paths and data boundaries

Use __DIR__ for files belonging to the bot. Do not infer disk paths from SCRIPT_FILENAME or DOCUMENT_ROOT: the sandbox virtualizes those values. The platform MySQL database is different from a bot’s SQLite database.db. Child bot code must not call platform database helpers or depend on platform secrets.

Sandbox-aware code

The current audit blocks shell/process execution, eval, several system inspection functions, directory enumeration and variable function calls. Use direct known function calls and known file paths. PHP/cURL HTTP requests and the native helper calls are normal integration paths. A rejected function is not fixed by turning a PHP extension on. Consult the sandbox reference for the current restrictions; do not assume all PHP functions are permitted merely because PHP provides them.

Cron is a separate entrypoint

A Botlify child cron runs through the platform scheduler and sandbox, with its own entry file and query parameters. It does not receive a Telegram message update by default. Native-helper cron code calls tg_all_fun at the start; ordinary file/database cron code does not need it. A direct command such as php my-job.php runs standalone PHP, not the hosted runtime. Calling Botlify’s master cron from cPanel is different from directly calling an arbitrary bot file.

Actual PHP version matters

A hosting selector, web URL and CLI cron can use different PHP versions/configurations. Compare PHP_VERSION and PHP_SAPI in the actual execution path. Extension checks and OPcache state from one URL do not prove the cron worker uses the same settings. PHP 8.2+ is the project target; the exact deployed version is a hosting detail.

Related guides

Loader and cron examples · Persistence and files · Diagnose runtime errors