README.md — sigil-telegram

1# sigil-telegram

A [Sigil](https://codeberg.org/sigil/sigil) library for the Telegram Bot API. Provides a complete bot framework with long-polling, command/message handlers, inline keyboards, MarkdownV2 formatting, and file uploads.

5## Features

7- **Bot framework** -- command, message, and callback handlers with long-polling loop

8- **Message operations** -- send, edit, delete with MarkdownV2 support

9- **Media sending** -- photos and documents by URL, file_id, or local file upload

10- **Inline keyboards** -- button rows with callback data or URLs

11- **MarkdownV2 formatting** -- bold, italic, code, links, spoilers with auto-escaping

12- **Authorization** -- restrict by allowed chats and/or allowed users

13- **Error recovery** -- configurable error handler, automatic retry on poll failure

14- **Cooperative I/O** -- blocking (`tg-bot-run`) or non-blocking (`tg-bot-tick`)

16## Usage

18Add `sigil-telegram` as a dependency in your `package.sgl`:

20```scheme

21(from-git url: "codeberg:sigil/sigil-telegram" package: "sigil-telegram")

22```

24Then build a bot:

26```scheme

27(import (sigil telegram))

29(define bot (make-tg-bot token: (getenv "TELEGRAM_BOT_TOKEN")))

31(tg-on-command bot "/hello"

32 (lambda (update)

33 (tg-reply bot update "Hello!")))

35(tg-on-message bot

36 (lambda (update)

37 (tg-reply bot update

38 (tg-bold "Echo: ")

39 (tg-escape-markdown (tg-message-text (tg-update-message update))))))

41(tg-bot-run bot)

42```

44## Modules

46| Module | Description |

47|--------|-------------|

48| `(sigil telegram)` | Top-level re-exports |

49| `(sigil telegram types)` | Data types: tg-user, tg-chat, tg-message, tg-update |

50| `(sigil telegram client)` | Low-level API calls, message/media operations |

51| `(sigil telegram bot)` | Bot framework, handlers, long-polling loop |

52| `(sigil telegram format)` | MarkdownV2 formatting and inline keyboards |

54## Dependencies

56- sigil-stdlib

57- sigil-json

58- sigil-http

60## Building

62```bash

63sigil deps install

64sigil build

65sigil test

66```

68## License

70BSD-3-Clause