# telegraph: a fluent Telegram bot client for Laravel applications

> Telegraph is a MIT licensed Laravel package that wraps the Telegram bot API in a fluent facade, so a message with an inline keyboard is one chained call, and the bot registry, the keyboards and the generated markup live in the application's own database. The judgement is that the package earns its place when a Laravel application needs to talk to Telegram, and that its cost is the persistence layer and the abstraction between you and the bot API.

**defstudio/telegraph** — Telegraph is a Laravel package for fluently interacting with Telegram Bots

- Repository: https://github.com/defstudio/telegraph
- Stars: 820 · Forks: 142
- Language: PHP
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/defstudio-telegraph

## One chained call instead of a bot API request

Telegraph is a Laravel package for fluently interacting with Telegram bots, made by def:studio, and the pitch is in the shape of the code rather than in a list of features. Instead of assembling a request to the Telegram bot API by hand, you chain calls on a facade. The README shows the shape with a message, an inline keyboard and a send in one expression:

```php
Telegraph::message('hello world')
    ->keyboard(Keyboard::make()->buttons([
            Button::make('Delete')->action('delete')->param('id', '42'),
            Button::make('open')->url('https://test.it'),
    ]))->send();
```

Two kinds of button appear there, one bound to a callback action with a parameter, and one that is just a link, which is the same distinction the Telegram API itself draws between a callback query and an inline URL. The fluent chain is the library's whole idea, and it is a familiar shape to anyone who has used Laravel, which is why the package needs no explanation of its conventions.

## Installing, migrations and the two optional publishes

Installation goes through Composer, and the package name is defstudio/telegraph:

```bash
composer require defstudio/telegraph
```

Then the migrations have to be published and run, because the bot registry lives in the database:

```bash
php artisan vendor:publish --tag="telegraph-migrations"
```

```bash
php artisan migrate
```

Two further publishes are optional. The configuration file is published with the telegraph-config tag, and the translation file with the telegraph-translations tag:

```bash
php artisan vendor:publish --tag="telegraph-config"
```

```bash
php artisan vendor:publish --tag="telegraph-translations"
```

That order matters, because the config file is where the Telegram credentials and the default chat live, and the README is explicit about the sequence of use: a bot has to be created through Telegram and added to a chat, a group or a channel before the facade can do anything, and first-time users are pointed at a full tutorial for building a first Telegram bot with Telegraph.

## Sending the first message

Once the bot exists and the setup is done, the facade is the whole interface, and the smallest useful call is a single line:

```php
Telegraph::message('this is great')->send();
```

The documentation for the package is extensive and lives on its own site at docs.defstudio.it/telegraph, with the quickstart tutorial linked from the README. The thing to understand about the architecture is that Telegraph is not a thin HTTP client with a nicer syntax, it is a package that maintains state. The bot and the chat it belongs to are records in your application's database, which is what lets the package offer higher level objects than a raw API call, and also what makes it a heavier dependency than a plain HTTP request would be. That trade is the decision to make, since a one off message from a queued job does not need a database table to hold a bot token.

## The repository is a Laravel package with the usual parts

The tree follows the conventions of the framework, which is what you would expect from a package that wants to be indistinguishable from something you wrote yourself. There is src for the package code, config for the published configuration, database for the migrations, resources for the views and translations, routes, tests, and a docs directory. Alongside them sit composer.json, phpunit.xml.dist for the test runner, phpstan.neon for static analysis and .php-cs-fixer.dist.php for code style, plus an .editorconfig, a CHANGELOG.md, a LICENSE.md and an x-ray.yml file, which is the configuration for the static analysis and code coverage service the project uses. The CI badges at the top of the README confirm that all three of those checks run on every push, with separate workflows for the tests, for code style and for static analysis. The test suite itself is built on Pest, and the README carries a Pest Laravel Expectations banner, so the testing style is the modern one rather than the older PHPUnit assertions, even though the phpunit configuration file is still present to drive it.

## Translations, credits and how to report a problem

The README closes with the parts of a project that are not code but matter for adoption. The translators are credited by name and language, with Spanish, Russian, Dutch, Arabic, Portuguese, Persian and German listed, which tells you a lot about who is using a Telegram package for a PHP framework. The main credits name Fabio Ivona and the def:studio team, along with individual contributions including a Pest badge, a documentation fix and an upgrade. Two paths are documented for problems. Contributions follow the guide in the .github directory, and security vulnerabilities follow the repository's own security policy, which is linked rather than reproduced, and that separation is the right one, since a vulnerability report should not become a public issue. The documentation also points to a changelog file for what changed recently and a social account for updates about the package.

## Licence, release pace and where the package fits

The licence is the MIT License, with the text in the LICENSE.md file, which is the permissive choice you would expect for a package that ends up in other people's applications. On maintenance, the tags move often, with v1.72.0 on 2026-07-16, v1.72.1 on 2026-09-07 and v1.73.0 on 2026-09-30, and the last push was on 2026-10-15 with the repository not archived, so the package is being maintained and released on a steady cycle. That cadence is a consideration for anyone building on it, since a fluent facade is the kind of surface that shifts between minor versions, and the CHANGELOG.md is the file to read before an upgrade. The comparison to make is not with another Laravel package but with the two alternatives, calling the Telegram HTTP API directly from your own code, which is less code and no state, or running the bot as a separate service, which is more code and better isolation. Telegraph sits between the two, and it makes sense when the bot is a first class part of the application, with its chat records joined to the application's own records.

## Conclusion

telegraph fits a Laravel application that needs a Telegram bot as a feature rather than as a separate service, especially one where the bot identity and its chat have to be stored alongside the application's own records, since Telegraph keeps them in your database. It is the wrong choice for a script that only sends a one off message, where the plain Telegram HTTP API is less code than a package, and it is a poor fit if you want the bot API exposed verbatim, because the fluent facade deliberately reshapes the calls. Before you adopt it, read the quickstart tutorial on building your first bot with Telegraph, publish the config file and read it, and check the CHANGELOG.md, because the package releases often and the facade surface is what will change if you upgrade.

## FAQ

### How do I install the Telegraph Laravel package?

Run composer require defstudio/telegraph, publish the migrations with php artisan vendor:publish --tag="telegraph-migrations" and then run php artisan migrate. The configuration and translation files are optional and are published with the telegraph-config and telegraph-translations tags.

### How do I send a message with Telegraph?

The facade does it, so Telegraph::message('this is great')->send(), optionally chained with a keyboard built from Keyboard and Button. The bot must already exist and have been added to a chat, group or channel, and the README points first-time users at a build your first Telegram bot with Telegraph tutorial.

### Which languages does Telegraph ship translations for?

The README credits translators for Spanish, Russian, Dutch, Arabic, Portuguese, Persian and German. The translation file is published with the telegraph-translations tag, so you can also edit it yourself before publishing it into your application.

## Sources

- [defstudio/telegraph on GitHub](https://github.com/defstudio/telegraph)
- [Issues](https://github.com/defstudio/telegraph/issues)
- [License: MIT](https://github.com/defstudio/telegraph/blob/main/LICENSE)
- [README](https://github.com/defstudio/telegraph/blob/main/README.md)
- [Releases](https://github.com/defstudio/telegraph/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/defstudio-telegraph