https://github.com/juliaaplavin/telegramclient.jl
Julia client for Telegram API using TDLib.
https://github.com/juliaaplavin/telegramclient.jl
messaging tdlib telegram telegram-api
Last synced: 4 months ago
JSON representation
Julia client for Telegram API using TDLib.
- Host: GitHub
- URL: https://github.com/juliaaplavin/telegramclient.jl
- Owner: JuliaAPlavin
- License: mit
- Created: 2024-02-18T18:00:22.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2025-10-26T12:55:17.000Z (8 months ago)
- Last Synced: 2025-10-31T00:39:50.051Z (8 months ago)
- Topics: messaging, tdlib, telegram, telegram-api
- Language: Julia
- Homepage:
- Size: 25.4 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Overview
Julia wrapper for the Telegram library [TDLib](https://core.telegram.org/tdlib):
> TDLib (Telegram Database Library) is a cross-platform, fully functional Telegram client. We designed it to help third-party developers create their own custom apps using the Telegram platform.
Relies on `TDLib_jll` package to provide TDLib binaries.
# Usage
```julia-repl
julia> cd(joinpath(@__DIR__, "../test/")) # assuming tdlib already run in test dir, it won't ask for auth code again
```
`TelegramClient.jl` doesn't export anything, so simply import the package and use qualified function names:
```julia-repl
julia> import TelegramClient as TG
```
Some methods can be executed without even creating a `Client`:
```julia-repl
julia> TG.execute_method(:setLogVerbosityLevel, new_verbosity_level=0) |> copy
Dict{Symbol, Any} with 1 entry:
Symbol("@type") => "ok"
julia> TG.execute_method(:getLogVerbosityLevel) |> copy
Dict{Symbol, Any} with 2 entries:
:verbosity_level => 0
Symbol("@type") => "logVerbosityLevel"
```
Authentication parameters can be filled in manually in the `AuthParameters` struct or read from a JSON file:
```json
{
"api_id": ***,
"api_hash": "***",
"phone_number": "***"
}
```
Here, we read it from file:
```julia-repl
julia> import JSON3
julia> auth_file = "auth_params.json";
julia> auth_parameters = JSON3.read(read(auth_file, String), TG.AuthParameters);
```
Create a client with these auth parameters:
```julia-repl
julia> tg = TG.Client(; auth_parameters);
```
Alternatively, an auto-closing wrapper is provided:
```julia
julia> TG.Client(; auth_parameters) do tg
...
end
```
Currently, this wrapper does nothing in the end as there are no functions to close the client in the TDLib API. However, this may change in the future.
Settings can be set by passing them to the constructor: `TG.Client(settings=TG.Settings(...))`. Default values:
```julia-repl
julia> Dict(TG.Settings())
Dict{Symbol, Any} with 10 entries:
:use_message_database => false
:database_directory => "tdlib"
:system_version => "Linux"
:use_secret_chats => false
:use_file_database => false
:device_model => "Desktop"
:application_version => "1.0"
:system_language_code => "en"
:use_chat_info_database => false
:enable_storage_optimizer => true
```
Now we can call an API method:
```julia-repl
julia> TG.send_method(tg, :getOption, name="version")
```
and receive its result:
```julia-repl
julia> TG.receive(tg, timeout=1) |> copy
Dict{Symbol, Any} with 4 entries:
:value => Dict{Symbol, Any}(:value=>"1.7.4", Symbol("@type")=>"…
:name => "version"
Symbol("@client_id") => 1
Symbol("@type") => "updateOption"
```
Timeouts are always specified in seconds.
The created `Client` is not ready to use yet:
```julia-repl
julia> TG.is_ready(tg)
false
```
Having created a `Client`, perform its connection and authorization workflow:
```julia-repl
julia> TG.connect_authorize(tg, timeout_each=1);
```
This may ask for the authentication code if connecting for the first time. By default, the code is asked interactively via `Base.prompt()`. This can be changed in an `AuthParameters` field: `AuthParameters(..., get_authentication_code=() -> Base.prompt("Authentication code"))`.
The client is finally ready:
```julia-repl
julia> TG.is_ready(tg)
true
```
Now, one can call any API methods with `send`, `send_method`, `execute`, `execute_method`, and receive responses or updates with `receive`.
```julia-repl
julia> cd(joinpath(@__DIR__, "../docs/")) # restore current dir
```
# Reference
#
**`TelegramClient.connect_authorize`** — *Method*.
```julia
connect_authorize(client::Any; timeout_each)
```
Perform the TDLib connection and authorization sequence.
`client` must contain valid authorization parameters. `timeout_each` is the timeout for each internal `receive` call. Returns all events received in the process, in case they are useful for the application.
#
**`TelegramClient.execute`** — *Method*.
```julia
execute(query::Dict) -> JSON3.Object
```
Call TDLib `execute` function, converting the input to JSON and the result from JSON.
#
**`TelegramClient.execute_method`** — *Method*.
```julia
execute_method(method::Symbol, params::Dict) -> JSON3.Object
```
Convenience function: calls `execute` with `"@type"=method` added to provided params.
#
**`TelegramClient.is_ready`** — *Method*.
```julia
is_ready(client::TelegramClient.Client) -> Bool
```
Returns whether the client is ready to use: connected and authorized.
#
**`TelegramClient.receive`** — *Method*.
```julia
receive(client::TelegramClient.Client; kwargs...)
```
Call TDLib `receive` function with the specified `timeout`, converting the result from JSON.
Compared to the `receive()` method, this raises an error when the response doesn't correspond to the provided `client`.
#
**`TelegramClient.receive`** — *Method*.
```julia
receive(; timeout)
```
Call TDLib `receive` function with the specified `timeout`, converting the result from JSON.
Note that `receive` may return an event for any `Client`, if multiple are created. Either check this yourself, or use the `receive(client)` method.
#
**`TelegramClient.send`** — *Method*.
```julia
send(client::TelegramClient.Client, query::Dict)
```
Call TDLib `send` function, converting the input to JSON. Doesn't return anything.
#
**`TelegramClient.send_method`** — *Method*.
```julia
send_method(client::TelegramClient.Client, method::Symbol, params::Dict)
```
Convenience function: calls `send_method` with `"@type"=method` added to provided params.
#
**`TelegramClient.AuthParameters`** — *Type*.
* `api_id::Int64`
* `api_hash::String`
* `phone_number::String`
* `encryption_key::String`
* `get_authentication_code::Function`
* `get_password::Function`
TDLib authentication parameters.
Obtain the API ID and hash from Telegram, and put it here together with your account phone number.
#
**`TelegramClient.Client`** — *Type*.
* `settings::TelegramClient.Settings`
* `auth_parameters::TelegramClient.AuthParameters`
* `tdlib_id::Int64`
* `is_authorized::Bool`
* `is_connected::Bool`
* `last_state::Union{Nothing, String}`
Telegram client struct.
Contains TDLib settings, authentication parameters, and its current state.
#
**`TelegramClient.Settings`** — *Type*.
* `database_directory::String`
* `use_file_database::Bool`
* `use_chat_info_database::Bool`
* `use_message_database::Bool`
* `enable_storage_optimizer::Bool`
* `use_secret_chats::Bool`
* `system_language_code::String`
* `device_model::String`
* `system_version::String`
* `application_version::String`
TDLib settings. They are sent to the library as-is.