Queued Messages

Telegraph can send a Telegram API request immediately or hand it to Laravel's queue system.

This page covers outbound requests from your application to Telegram. For heavy work triggered by incoming updates, see Background Webhook Processing.

Send immediately

send() performs the HTTP request during the current process and returns its response:

$response = Telegraph::message('hello')->send();

This is useful when the caller needs the Telegram response before it can continue. The caller also waits for the network request to finish.

Dispatch through Laravel queues

dispatch() creates a queued job for the outbound Telegram API request:

Telegraph::message('hello')->dispatch();

Without an argument, Laravel uses the default queue configured for the application's default queue connection. Make sure the host application uses an asynchronous queue driver and runs queue workers. With the sync driver, the job still runs in the current process.

Pass a queue name to route the request to a specific queue:

Telegraph::message('Your export is ready')
    ->dispatch('telegram-interactive');

The queue belongs to the host Laravel application. Telegraph does not configure the queue connection, start workers, or require a particular queue driver.

Use a fixed set of queues

For bots that serve interactive traffic and send bulk notifications, use a small, fixed set of queues:

// Replies and other user-facing responses.
Telegraph::message('Done')
    ->dispatch('telegram-interactive');

// Scheduled or bulk notifications.
Telegraph::message('Weekly summary')
    ->dispatch('telegram-broadcasts');

Avoid creating a queue name for every bot, chat, or user. Workers consume explicitly configured queue names, so dynamic names make worker configuration, capacity planning, and monitoring harder.

Queue names separate workloads; they do not apply Telegram rate limits. They also do not guarantee that requests for the same chat will be processed in order when multiple workers are active. If ordering matters, the host application must coordinate it explicitly.

Allocate worker capacity

Running more than one worker lets Laravel process queued requests concurrently. To ensure broadcasts cannot consume all available workers, reserve capacity with separate worker pools:

php artisan queue:work --queue=telegram-interactive

php artisan queue:work --queue=telegram-broadcasts

Run the required number of each process under Supervisor, systemd, a container orchestrator, or another process monitor. Scale the interactive pool for response latency and the broadcasts pool for throughput.

A single worker can listen to both queues in priority order:

php artisan queue:work --queue=telegram-interactive,telegram-broadcasts

Laravel checks telegram-interactive first in this configuration. This is useful for simple deployments, but it does not reserve worker capacity for broadcasts and a continuously busy interactive queue can delay them.

See the official Laravel queue documentation for queue connections, workers, process monitors, and failed jobs.

Optional Horizon setup

Laravel Horizon is an optional dashboard and worker configuration system for Redis queues. It is configured by the host application and is not a Telegraph dependency.

When each workload needs reserved capacity, define separate Horizon supervisors instead of relying on one auto-balanced supervisor:

'environments' => [
    'production' => [
        'telegram-interactive' => [
            'connection' => 'redis',
            'queue' => ['telegram-interactive'],
            'balance' => 'auto',
            'minProcesses' => 2,
            'maxProcesses' => 4,
        ],

        'telegram-broadcasts' => [
            'connection' => 'redis',
            'queue' => ['telegram-broadcasts'],
            'balance' => 'auto',
            'minProcesses' => 1,
            'maxProcesses' => 2,
        ],
    ],
],

Each supervisor reserves its own minimum capacity and scales only within its maximum. Choose process counts from observed load and infrastructure limits. Horizon's auto balancing reallocates workers according to queue load; it does not enforce Telegram rate limits or strict priority between queues.

Telegram limits and 429 responses

Worker concurrency controls how quickly your application starts requests; it is not a Telegram API rate limiter. Telegram's current broadcasting guidance recommends avoiding more than one message per second in a single chat, limits groups to 20 messages per minute, and describes roughly 30 messages per second for free bulk broadcasts. Treat these as Telegram guidance, not guarantees made by Telegraph.

When flood control is exceeded, Telegram may return HTTP 429. Its Bot API ResponseParameters can include retry_after, the number of seconds to wait before repeating the request.

The current Telegraph queued request job performs one HTTP request. It does not inspect a 429 response or automatically release and retry the job using retry_after. If the application sends enough traffic to require throttling or retries, implement those controls in the host application and make repeated operations idempotent.

Operational checks

Monitor queue depth, queue wait time, and failed-job count for each fixed queue. These metrics reveal head-of-line blocking without recording Telegram request payloads.

Do not include bot tokens, full Telegram API URLs, message content, or chat and user identifiers in shared queue logs or dashboards.

Telegraph 1 v1