telega/client

Module provides a simple interface to the Telegram Bot API and uses httpc as a default HTTP client. If you want to use telega as a Telegram client, you can use only this module.

import telega/client
import telega/api

fn main() {
  ...
  let response = client.new(token) |> api.send_message(client, send_message_parameters)
  ...
}

Types

RequestQueueConfig

</>

pub type RequestQueueConfig {
  RequestQueueConfig(
    rules: List(RequestQueueRule),
    overall_rate: option.Option(Int),
    overall_limit: option.Option(Int),
    retry_delay: Int,
    max_retries: Int,
  )
}

Constructors

RequestQueueConfig(
  rules: List(RequestQueueRule),
  overall_rate: option.Option(Int),
  overall_limit: option.Option(Int),
  retry_delay: Int,
  max_retries: Int,
)

Arguments

overall_rate: Overall rate limit (requests per second)
overall_limit: Overall concurrent request limit
retry_delay: Default retry delay in milliseconds
max_retries: Maximum retries

RequestQueueRule

</>

pub type RequestQueueRule {
  RequestQueueRule(
    id: String,
    rate: Int,
    limit: Int,
    priority: Int,
  )
}

Constructors

```
RequestQueueRule(
  id: String,
  rate: Int,
  limit: Int,
  priority: Int,
)
```
Arguments

id

Rule identifier

rate

Maximum requests per time window

limit

Time window in milliseconds

priority

Priority (lower number = higher priority)

TelegramApiRequest

opaque </>

pub opaque type TelegramApiRequest

TelegramClient

opaque </>

pub opaque type TelegramClient

Values

default_request_queue_config

</>

pub fn default_request_queue_config() -> RequestQueueConfig

fetch

</>

pub fn fetch(
  request api_request: TelegramApiRequest,
  client client: TelegramClient,
) -> Result(response.Response(String), error.TelegaError)

Send a request to the Telegram Bot API.

It uses default rule for rate limiting (if request queue is enabled).

fetch_with_rule

</>

pub fn fetch_with_rule(
  request api_request: TelegramApiRequest,
  client client: TelegramClient,
  rule_id rule_id: String,
) -> Result(response.Response(String), error.TelegaError)

get_api_url

</>

pub fn get_api_url(client client: TelegramClient) -> String

get_queue_length

</>

pub fn get_queue_length(client client: TelegramClient) -> Int

Get the total number of requests waiting in the queue

Returns 0 if no queue is configured

get_token

</>

pub fn get_token(client: TelegramClient) -> String

Get the bot token from the client

is_queue_overheated

</>

pub fn is_queue_overheated(client client: TelegramClient) -> Bool

Check if the queue is overheated (any rule is at its rate limit)

Returns False if no queue is configured

new

</>

pub fn new(token token: String) -> TelegramClient

Create a new Telegram client. It uses httpc as a default HTTP client.

new_get_request

</>

pub fn new_get_request(
  client client: TelegramClient,
  path path: String,
  query query: option.Option(List(#(String, String))),
) -> TelegramApiRequest

new_post_request

</>

pub fn new_post_request(
  client client: TelegramClient,
  path path: String,
  body body: String,
) -> TelegramApiRequest

new_with_queue

</>

pub fn new_with_queue(
  token token: String,
) -> Result(TelegramClient, error.TelegaError)

Create a new Telegram client with default request queue configuration

This is a convenience function that creates a client with sensible default rate limiting settings for the Telegram Bot API.

set_fetch_client

</>

pub fn set_fetch_client(
  client client: TelegramClient,
  fetch_client fetch_client: fn(request.Request(String)) -> Result(
    response.Response(String),
    error.TelegaError,
  ),
) -> TelegramClient

Set the HTTP client to use.

set_max_retry_attempts

</>

pub fn set_max_retry_attempts(
  client client: TelegramClient,
  max_retry_attempts max_retry_attempts: Int,
) -> TelegramClient

Set the maximum number of times to retry sending a API message.

set_request_queue

</>

pub fn set_request_queue(
  client client: TelegramClient,
  config config: RequestQueueConfig,
) -> Result(TelegramClient, error.TelegaError)

Enable request queue with custom configuration for rate limiting

The request queue helps prevent hitting Telegram’s rate limits by:

Queuing requests when limits are reached
Automatically retrying failed requests with exponential backoff
Supporting different rate limits for different types of requests

Example

import telega/client

let config = client.RequestQueueConfig(
  rules: [
    // Default rule for most requests
    client.RequestQueueRule(
      id: "default",
      rate: 30,        // 30 requests
      limit: 1000,     // per 1 second
      priority: 5,
    ),
    // Slower rate for sending messages
    client.RequestQueueRule(
      id: "send_message",
      rate: 1,         // 1 request
      limit: 1000,     // per 1 second
      priority: 10,
    ),
    // Higher priority for important requests
    client.RequestQueueRule(
      id: "important",
      rate: 5,
      limit: 1000,
      priority: 1,     // Lower number = higher priority
    ),
  ],
  overall_rate: Some(30),    // Global limit across all rules
  overall_limit: Some(100),  // Max concurrent requests
  retry_delay: 1000,         // Retry after 1 second
  max_retries: 3,
)

let assert Ok(client) =
  client.new(token)
  |> client.set_request_queue(config)

// Use specific rule for rate-limited operations
client.fetch_with_rule(request, client, "send_message")

// Check queue status
let queue_length = client.get_queue_length(client)
let is_busy = client.is_queue_overheated(client)

set_tg_api_url

</>

pub fn set_tg_api_url(
  client client: TelegramClient,
  tg_api_url tg_api_url: String,
) -> TelegramClient

Set the Telegram Bot API URL.

shutdown

</>

pub fn shutdown(client client: TelegramClient) -> Nil

Shutdown the client and its request queue

Only recommended if request queue is enabled.