SwiftTelegramBot

The library supports two ways to receive updates from Telegram via TGConnectionType:

Long Polling

Best for local development or simple bots where you don't have a public URL.

let connectionType: TGConnectionType = .longpolling()

Webhook

Required for production environments where Telegram pushes updates to your server. You must provide a valid webHookURL.

let connectionType: TGConnectionType = .webhook(webHookURL: URL(string: "https://your-domain.com/webhook-path")!)

// Long Polling
let connectionType: TGConnectionType = .longpolling()

// Webhook
let connectionType: TGConnectionType = .webhook(webHookURL: URL(string: "https://your-domain.com/webhook-path")!)

To get started quickly, clone the repository and run one of the provided examples (e.g., the Vapor implementation):

1. Clone the repo:

   git clone https://github.com/nerzh/swift-telegram-bot

2. Navigate to the Vapor example directory:

   cd swift-telegram-bot/Examples/Vapor-Telegram-Bot

3. Open the project in Xcode or build the binary.
4. Update the botId in configure.swift with your actual Telegram Bot Token.
5. Run the application and test commands like /ping or /show_buttons in your Telegram bot.

To use the Vapor-based Telegram bot example, you must provide your Telegram Bot API token. Locate the configure.swift file and assign your token to the tgApi constant.

After configuration, run the Vapor application and send the /ping command to your bot via Telegram to verify the connection.

let tgApi: String = "..."

To initialize the bot, you must provide your Telegram Bot API token and a Logger instance. The botId is the token provided by @BotFather.

import SwiftTelegramBot
import Logging

let tgApi: String = "XXXXXXXXXX:YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY"
var logger: Logger = .init(label: "swift_telegram_bot")
logger.logLevel = .error

To use the smoke test example, you must provide your Telegram Bot API token in the configure.swift file. Replace the placeholder string with your actual bot key.

Once configured, run the Hummingbird application and send the /ping command to your Telegram bot to verify the connection.

let tgApi: String = "..."

When using Webhooks with the Vapor framework, you need to create a controller that decodes the TGUpdate and passes it to the bot's processing method.

/// TelegramController.swift
final class TelegramController: RouteCollection {
    func boot(routes: Vapor.RoutesBuilder) throws {
        routes.post(TGWebHookRouteName, use: telegramWebHook)
    }

    func telegramWebHook(_ req: Request) async throws -> Bool {
        let update: TGUpdate = try req.content.decode(TGUpdate.self)
        Task { await bot.processing(updates: [update]) }
        return true
    }
}

To use the Hummingbird-URLSession-Telegram-Bot example, you must provide your Telegram Bot API token in the configure.swift file. Replace the placeholder string with your actual bot key.

After configuration, run the Hummingbird application and send the /ping command to your Telegram bot to verify the connection.

let tgApi: String = "YOUR_TELEGRAM_BOT_API_KEY"

The library uses a client to send network requests to the Telegram API. While TGClientDefault is provided, you can implement your own TGClientPrtcl to use different networking engines (like AsyncHTTPClient or URLSession) or to handle custom request logic.

public protocol TGClientPrtcl {
    @discardableResult
    func post<Params: Encodable, Response: Decodable>(_ url: URL, params: Params?, as mediaType: HTTPMediaType?) async throws -> Response
    
    @discardableResult
    func post<Response: Decodable>(_ url: URL) async throws -> Response
}

To run the bot, instantiate TGBot with your configuration, add a dispatcher (which contains your business logic), and call start().

let bot: TGBot = try await .init(connectionType: connectionType,
                                 tgClient: TGClientDefault(),
                                 tgURI: TGBot.standardTGURL,
                                 botId: botId,
                                 log: logger)

// Add your logic via a dispatcher
try await bot.add(dispatcher: TestDispatcher(bot: bot, logger: logger))

// Start the bot loop
try await bot.start()