TelegramEx.API (TelegramEx v1.2.1)

Copy Markdown View Source

HTTP wrapper around the Telegram Bot API.

This module provides low-level functions for making HTTP requests to the Telegram Bot API. It handles both JSON and multipart form data requests, and includes error handling and logging.

Most users should use the builder modules (TelegramEx.Builder.*) instead of calling these functions directly.

Examples

# Get updates (used internally by the polling server)
{:ok, updates} = API.get_updates(token, 0)

# Send a request via builder context
ctx
|> Map.put(:chat_id, chat_id)
|> Map.put(:method, "sendMessage")
|> Map.put(:payload, %{text: "Hello"})
|> Map.put(:format, :json)
|> API.request()

Error Handling

All functions return either {:ok, result} or {:error, reason}. Errors are logged automatically.

Summary

Types

request_context()
updates()

Functions

answer_callback_query(token, map)

Answers a callback query from an inline keyboard button.

get_updates(token, offset)

Fetches updates from Telegram using long polling.

request(ctx)

Sends a request to the Telegram Bot API.

Types

request_context()

@type request_context() :: %{
  :chat_id => integer(),
  :token => String.t(),
  :method => String.t(),
  :payload => map(),
  :format => :json | :multipart,
  optional(:message_thread_id) => integer()
}

updates()

@type updates() :: TelegramEx.Types.updates()

Functions

answer_callback_query(token, map)

@spec answer_callback_query(String.t(), TelegramEx.Types.CallbackQuery.t()) ::
  :ok | {:error, any()}

Answers a callback query from an inline keyboard button.

This function should be called after handling a callback query to acknowledge it and optionally show an alert or notification to the user.

Parameters

Returns

  • :ok - Callback query answered successfully
  • {:error, reason} - Failed to answer callback query

Examples

def handle_callback(%{data: "confirm"} = callback, ctx) do
  API.answer_callback_query(ctx.token, callback)
  # ... send response message
end

Note

You typically don't call this directly. Use Message.answer_callback_query/2 in the builder pipeline instead.

get_updates(token, offset)

@spec get_updates(String.t(), integer()) :: {:ok, updates()} | {:error, any()}

Fetches updates from Telegram using long polling.

This function is called internally by TelegramEx.Server to retrieve new messages and callbacks.

Parameters

  • token - Bot authentication token
  • offset - Update ID offset for pagination (0 for first request)

Returns

  • {:ok, updates} - List of update maps
  • {:error, reason} - Error atom or term

Examples

defp client do Application.get_env(:telegram_ex, :req_client) ||

Req.new()
|> ReqProxy.attach()
|> tap(&Application.put_env(:telegram_ex, :req_client, &1))

end

iex> API.get_updates("123456:ABC-DEF", 0)
{:ok, [%{"update_id" => 1, "message" => %{...}}]}

iex> API.get_updates("invalid_token", 0)
{:error, :bad_request}

request(ctx)

@spec request(request_context()) :: :ok | {:error, term()}

Sends a request to the Telegram Bot API.

This is the main function used by all builder modules to send messages, photos, documents, and other content to Telegram.

Parameters

  • ctx - A context map containing:
    • :chat_id - Target chat ID
    • :token - Bot authentication token
    • :method - Telegram API method name (e.g., "sendMessage", "sendPhoto")
    • :payload - Map of parameters for the API method
    • :format - Either :json or :multipart
    • :message_thread_id (optional) - Thread ID for forum chats

Returns

  • :ok - Request succeeded
  • {:error, reason} - Request failed

Examples

# Send a text message
ctx
|> Map.put(:chat_id, 123456)
|> Map.put(:token, "bot_token")
|> Map.put(:method, "sendMessage")
|> Map.put(:payload, %{text: "Hello"})
|> Map.put(:format, :json)
|> API.request()

# Send a photo (multipart)
ctx
|> Map.put(:chat_id, 123456)
|> Map.put(:token, "bot_token")
|> Map.put(:method, "sendPhoto")
|> Map.put(:payload, %{photo: file_content})
|> Map.put(:format, :multipart)
|> API.request()