# Bot State, SQLite, Files and Scheduled Work

> Persist state across webhook requests and handle media without confusing IDs and paths.

**Category:** Bot Development  
**URL:** https://docs.botlify.cloud/bot-state-and-storage  
**Platform:** Botlify Cloud (https://botlify.cloud)  

---

## A request is not a permanent process

Do not keep a user’s conversation state only in a PHP variable. Separate webhook requests and cron runs need shared persistent storage. Use a bot-local SQLite database or another explicitly configured store. A static variable can cache within a request but does not replace durable storage.

## SQLite example

This snippet uses PHP PDO and needs no Telegram loader. chatId must come from a validated update or a configured target. Store chat IDs as text when combining numeric IDs and usernames.

```php
$db = new PDO('sqlite:' . __DIR__ . '/database.db', null, null, [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
    PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
]);
$db->exec('PRAGMA journal_mode = WAL');
$db->exec('PRAGMA busy_timeout = 5000');
$db->exec('CREATE TABLE IF NOT EXISTS user_state (
    chat_id TEXT PRIMARY KEY,
    state TEXT NOT NULL,
    updated_at INTEGER NOT NULL
)');
$stmt = $db->prepare('INSERT INTO user_state(chat_id, state, updated_at)
    VALUES (?, ?, ?)
    ON CONFLICT(chat_id) DO UPDATE SET state=excluded.state, updated_at=excluded.updated_at');
$stmt->execute([(string)$chatId, 'awaiting_name', time()]);
```

WAL allows concurrent readers but SQLite still has writer contention. Keep transactions short; do not wait for Telegram/network responses while holding a database write transaction. busy_timeout is a wait limit, not a guarantee against locks. Schedule schema migrations carefully and use prepared statements for user-controlled values.

## Replay handling and duplicate work

Use update_id to recognize repeated Telegram deliveries, but do not mark an update permanently complete before its durable work succeeds. For payments, grants and other non-repeatable actions, store an operation key and state transition in a transaction. An outbound timeout can mean the operation completed but the response was lost. Blindly repeating it can duplicate side effects.

## File identifiers are different

| Value | Use |
| --- | --- |
| file_id | Reuse/download through the same bot; preserve the original media type. |
| file_unique_id | Identify/deduplicate a file; not usable for sending or downloading. |
| file_path | Telegram remote path returned by getFile; not a local disk path. |
| local_path | Botlify download helper’s local filesystem result, possibly null. |
| custom_emoji_id | Custom emoji identifier; not interchangeable with a message effect ID. |

Keep file_id with bot identity, original filename and MIME type. An ID from another bot cannot simply be copied into the new bot’s media store. The native download helper returns local_path, direct_tg_url, url and file_name; check local_path before processing. A direct Telegram file URL contains credentials and must not be exposed.

## Local uploads and cleanup

Use known paths under the bot workspace for local media. Do not turn user text into arbitrary filesystem paths. Multipart albums use attach:// references to top-level CURLFile values. Clean up only files created for your task; do not delete a shared database or another task’s output. See the [media and file recipes](/tg-native-helpers) for complete examples.

## Cron work and locking

A cron task should finish after its bounded work. Avoid an endless loop. Where overlapping runs would duplicate work, use a lock and durable progress records. PHP file locks coordinate cooperating processes; they are not an operation ledger. A normal PHP cron does not need tg_all_fun. Add it only if the cron calls native Telegram helpers.

## Configuration scope

Platform MySQL errors concern the platform configuration, while PDO SQLite errors in a bot concern its own database. Never copy platform database passwords into hosted bots. OPcache caches PHP bytecode; Redis/APCu extensions being enabled do not automatically create your application’s persistent state.
