zalobot-sdk 0.1.0__tar.gz

zalobot_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes are listed here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and versions follow [Semantic Versioning](https://semver.org/). Before 1.0 a minor version may change the API.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-08
+
+### Added
+
+- `Bot` (blocking) and `AsyncBot` (asyncio) with every Zalo Bot API method: `get_me`, `get_updates`,
+  `set_webhook`, `test_webhook`, `delete_webhook`, `get_webhook_info`, `send_message`, `send_photo`,
+  `send_sticker`, `send_voice` and `send_chat_action`, plus `send_long_message`.
+- A typed dataclass for every answer, keeping the raw JSON in `.raw`.
+- An exception for each documented error code, plus `NetworkError`. The bot token is removed from errors,
+  `repr()` and httpx log lines.
+- Checks against the documented limits before sending, and an opt-in `RetryPolicy` for quota and network errors.
+- `Text`, a builder for `text_styles` with UTF-16 offsets, and `split_text`.
+- `Dispatcher` and `Router` with command and message handlers, filters `F` (combinable with `&`, `|`, `~`),
+  fallback and error hooks, and duplicate-message protection.
+- Long polling (`run_polling`, `start_polling`, `run`) with backoff, a clean stop, and a refusal to start while a
+  webhook is set.
+- Webhook helpers that work with any framework: `verify_secret`, `parse_update`, `WebhookHandler` and
+  `AsyncWebhookHandler`.
+- `zalobot.testing.FakeZalo`, an in-memory Bot API for tests. It answers like the real API where the real API
+  differs from the docs.
+- `InvalidChat` (410) and `BotInfo.display_name`, both seen from the real API but not in the docs.

zalobot_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tâm Ngô
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zalobot_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: zalobot-sdk
+Version: 0.1.0
+Summary: Typed Python client and bot framework for the Zalo Bot Platform (sync and async).
+Keywords: zalo,zalobot,bot,chatbot,vietnam,asyncio,webhook
+Author: Tâm Ngô
+Author-email: Tâm Ngô <ngothtam.me@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Natural Language :: Vietnamese
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: httpx>=0.27,<1
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/nttams/zalobot
+Project-URL: Source, https://github.com/nttams/zalobot
+Project-URL: Issues, https://github.com/nttams/zalobot/issues
+Project-URL: Changelog, https://github.com/nttams/zalobot/blob/main/CHANGELOG.md
+Project-URL: Zalo Bot API, https://bot.zaloplatforms.com/docs/
+Description-Content-Type: text/markdown
+
+# zalobot
+
+A typed Python library for the [Zalo Bot Platform](https://bot.zaloplatforms.com/docs/) with blocking and asyncio
+clients, handlers, long polling and webhooks.
+
+- **The whole Bot API**: all 11 methods, including `sendVoice`, `testWebhook` and the webhook check `setWebhook`
+  now returns.
+- **Typed**: every answer is a dataclass, and the package ships `py.typed` (it passes `mypy --strict`).
+- **Blocking or asyncio**: `Bot` and `AsyncBot` have the same methods.
+- **Rich text that lines up**: `Text` builds Zalo's `text_styles`. Their offsets are counted in UTF-16 units, so
+  Vietnamese accents and emoji land in the right place.
+- **Handlers like you know them**: `@dp.command("start")` and `@dp.message(F.photo)`, plus filters, an error hook
+  and duplicate-message protection.
+- **Safe by default**: the bot token never shows up in errors, `repr()` or httpx's request logs. Webhook secrets are
+  compared in constant time.
+- **Testable offline**: `zalobot.testing.FakeZalo` is an in-memory Bot API you can point a bot at in your own
+  tests.
+
+## Install
+
+```bash
+uv add zalobot-sdk        # or: pip install zalobot-sdk
+```
+
+The package is `zalobot-sdk` on PyPI, and you import it as `zalobot`. Python 3.11 or newer. The only dependency is [httpx](https://www.python-httpx.org/).
+
+## Quickstart
+
+Create a bot in the Zalo app: open the official account **Zalo Bot Manager**, tap **Tạo bot**, and give it a name
+starting with "Bot". Zalo then sends you the token in a message.
+
+```python
+import os
+
+from zalobot import Bot, Dispatcher, F
+
+dp = Dispatcher()
+
+
+@dp.message(F.text)
+def echo(ctx):
+    ctx.reply_text(ctx.text)
+
+
+dp.run_polling(Bot(os.environ["ZALO_BOT_TOKEN"]))
+```
+
+Message your bot in Zalo, and it answers with the same text.
+
+## Commands, filters, replies
+
+```python
+from zalobot import Context, Dispatcher, F
+
+dp = Dispatcher()
+
+@dp.command("add")                       # "/add 50k coffee" (any case)
+def add(ctx: Context) -> None:
+    ctx.reply_text(f"Added: {ctx.args}")  # "50k coffee"
+
+@dp.message(F.photo & F.private)
+def photo(ctx: Context) -> None:
+    ctx.reply_text(f"Got your photo: {ctx.message.photo_url}")
+
+@dp.fallback
+def other(ctx: Context) -> None:
+    ctx.reply_sticker("bfe458bf64fa8da4d4eb")
+
+@dp.error
+def on_error(ctx: Context, exc: Exception) -> None:
+    ctx.reply_text("Sorry, something went wrong.")
+```
+
+Filters: `F.text`, `F.photo`, `F.sticker`, `F.voice`, `F.unsupported`, `F.private`, `F.group`,
+`F.command(...)`, `F.regex(...)`, `F.from_user(...)` and `F.chat(...)`. Combine them with `&`, `|` and `~`. The first
+matching handler wins. A `Router` groups handlers, and `dp.include(router)` adds the group to the dispatcher.
+
+Replies: `ctx.reply_text`, `ctx.reply_long` (splits text over 2,000 characters at line breaks), `ctx.reply_photo`,
+`ctx.reply_sticker`, `ctx.reply_voice` and `ctx.typing()`.
+
+## asyncio
+
+```python
+from zalobot import AsyncBot, AsyncContext, Dispatcher, F
+
+dp = Dispatcher()
+
+@dp.message(F.text)
+async def echo(ctx: AsyncContext) -> None:
+    await ctx.typing()
+    await ctx.reply_text(ctx.text)
+
+dp.run(AsyncBot(token))             # or: await dp.start_polling(bot)
+```
+
+With an `AsyncBot`, plain `def` handlers still work: they run in a worker thread, and their replies go through
+the same bot.
+
+## Polling or webhook
+
+Zalo delivers messages in one of two ways, and you can't use both at once:
+
+| | Long polling | Webhook |
+|---|---|---|
+| How | `dp.run_polling(bot)` | Zalo POSTs to your HTTPS URL |
+| Good for | development, small bots, no public server | production (Zalo's advice) |
+| Setup | nothing | `bot.set_webhook(url, secret)` once |
+
+While a webhook is set, Zalo turns `getUpdates` off. `run_polling` checks for this and tells you to call
+`bot.delete_webhook()`.
+
+Webhook with FastAPI (see `examples/webhook_flask.py` for Flask):
+
+```python
+from fastapi import FastAPI, Request, Response
+from zalobot import AsyncBot, AsyncWebhookHandler
+
+handler = AsyncWebhookHandler(dp, AsyncBot(token), secret="a-long-random-secret")
+app = FastAPI()
+
+@app.post("/zalo/webhook")
+async def webhook(request: Request) -> Response:
+    status, body = await handler.handle(request.headers, await request.body())
+    return Response(body, status_code=status, media_type="application/json")
+```
+
+The handler checks the `X-Bot-Api-Secret-Token` header (403 if it's wrong) and the body (400 if it isn't an
+update), then runs your handlers. `bot.set_webhook()` and `bot.test_webhook()` return Zalo's check of your URL, such
+as `outcome="webhook.http.403"` with a hint about what to fix.
+
+## Rich text
+
+```python
+from zalobot import Color, Size, Text
+
+msg = (Text().size(Size.LARGE, "Đơn hàng #1024").plain("\n")
+       .bullets(["Cà phê sữa đá: 29,000đ", "Bánh mì: 25,000đ"])
+       .bold("Tổng: ").plain("54,000đ ").color(Color.GREEN, "✅ đã thanh toán"))
+bot.send_message(chat_id, msg)
+```
+
+You can also let Zalo parse the markup: `bot.send_message(chat_id, "**bold** {red}red{/red}", parse_mode="markdown")`
+or `parse_mode="html"`.
+
+## Errors and retries
+
+Each documented error code has its own exception, all subclasses of `zalobot.ZaloError`:
+
+| Code | Exception |
+|---|---|
+| 400 | `BadRequest` |
+| 401 | `Unauthorized` (token expired or wrong) |
+| 403 | `Forbidden` |
+| 404 | `NotFound` |
+| 408 | `TimedOut` |
+| 410 | `InvalidChat` (no such chat for this bot; not in Zalo's table) |
+| 429 | `QuotaExceeded` |
+| network failure | `NetworkError` |
+
+The real API answers errors with HTTP 200 and the code in the body; zalobot reads the body either way.
+
+Retries are off by default. Turn them on with `Bot(token, retry=RetryPolicy(attempts=3))`: quota errors and
+network errors are retried with doubling waits, while 401 never is. A send (`send_message`, `send_photo` ...) is
+retried after a network error only if the request never left (connection refused or timed out): after a read
+timeout Zalo may already have delivered it, and a retry would send it twice. Inputs that break the documented limits raise
+`ValueError` before any request is sent: text over 2,000 characters (counted like Zalo's server, where most emoji
+take 2), a secret shorter than 8, or a voice file that isn't `.aac`.
+
+## Testing your bot
+
+```python
+from zalobot.testing import FakeZalo
+
+def test_echo():
+    fake = FakeZalo()
+    fake.push_text("hello")                      # a user writes to the bot
+    with fake.bot() as bot:
+        for update in bot.get_updates():
+            dp.feed(bot, update)
+    assert fake.sent[0].text == "hello"          # what the bot sent back
+```
+
+`FakeZalo` answers with the shapes from the official docs. It can fail on demand (`fake.fail(429)`), and it can
+deliver queued updates to a webhook handler (`fake.deliver_webhook(handler)`).
+
+## Links
+
+- Source and issues: https://github.com/nttams/zalobot
+- Zalo Bot Platform docs: https://bot.zaloplatforms.com/docs/
+- Changelog: [CHANGELOG.md](https://github.com/nttams/zalobot/blob/main/CHANGELOG.md)
+- Contributing: [CONTRIBUTING.md](https://github.com/nttams/zalobot/blob/main/CONTRIBUTING.md)
+
+zalobot is an independent project, not made or endorsed by Zalo or VNG. MIT licensed.

zalobot_sdk-0.1.0/README.md

@@ -0,0 +1,193 @@
+# zalobot
+
+A typed Python library for the [Zalo Bot Platform](https://bot.zaloplatforms.com/docs/) with blocking and asyncio
+clients, handlers, long polling and webhooks.
+
+- **The whole Bot API**: all 11 methods, including `sendVoice`, `testWebhook` and the webhook check `setWebhook`
+  now returns.
+- **Typed**: every answer is a dataclass, and the package ships `py.typed` (it passes `mypy --strict`).
+- **Blocking or asyncio**: `Bot` and `AsyncBot` have the same methods.
+- **Rich text that lines up**: `Text` builds Zalo's `text_styles`. Their offsets are counted in UTF-16 units, so
+  Vietnamese accents and emoji land in the right place.
+- **Handlers like you know them**: `@dp.command("start")` and `@dp.message(F.photo)`, plus filters, an error hook
+  and duplicate-message protection.
+- **Safe by default**: the bot token never shows up in errors, `repr()` or httpx's request logs. Webhook secrets are
+  compared in constant time.
+- **Testable offline**: `zalobot.testing.FakeZalo` is an in-memory Bot API you can point a bot at in your own
+  tests.
+
+## Install
+
+```bash
+uv add zalobot-sdk        # or: pip install zalobot-sdk
+```
+
+The package is `zalobot-sdk` on PyPI, and you import it as `zalobot`. Python 3.11 or newer. The only dependency is [httpx](https://www.python-httpx.org/).
+
+## Quickstart
+
+Create a bot in the Zalo app: open the official account **Zalo Bot Manager**, tap **Tạo bot**, and give it a name
+starting with "Bot". Zalo then sends you the token in a message.
+
+```python
+import os
+
+from zalobot import Bot, Dispatcher, F
+
+dp = Dispatcher()
+
+
+@dp.message(F.text)
+def echo(ctx):
+    ctx.reply_text(ctx.text)
+
+
+dp.run_polling(Bot(os.environ["ZALO_BOT_TOKEN"]))
+```
+
+Message your bot in Zalo, and it answers with the same text.
+
+## Commands, filters, replies
+
+```python
+from zalobot import Context, Dispatcher, F
+
+dp = Dispatcher()
+
+@dp.command("add")                       # "/add 50k coffee" (any case)
+def add(ctx: Context) -> None:
+    ctx.reply_text(f"Added: {ctx.args}")  # "50k coffee"
+
+@dp.message(F.photo & F.private)
+def photo(ctx: Context) -> None:
+    ctx.reply_text(f"Got your photo: {ctx.message.photo_url}")
+
+@dp.fallback
+def other(ctx: Context) -> None:
+    ctx.reply_sticker("bfe458bf64fa8da4d4eb")
+
+@dp.error
+def on_error(ctx: Context, exc: Exception) -> None:
+    ctx.reply_text("Sorry, something went wrong.")
+```
+
+Filters: `F.text`, `F.photo`, `F.sticker`, `F.voice`, `F.unsupported`, `F.private`, `F.group`,
+`F.command(...)`, `F.regex(...)`, `F.from_user(...)` and `F.chat(...)`. Combine them with `&`, `|` and `~`. The first
+matching handler wins. A `Router` groups handlers, and `dp.include(router)` adds the group to the dispatcher.
+
+Replies: `ctx.reply_text`, `ctx.reply_long` (splits text over 2,000 characters at line breaks), `ctx.reply_photo`,
+`ctx.reply_sticker`, `ctx.reply_voice` and `ctx.typing()`.
+
+## asyncio
+
+```python
+from zalobot import AsyncBot, AsyncContext, Dispatcher, F
+
+dp = Dispatcher()
+
+@dp.message(F.text)
+async def echo(ctx: AsyncContext) -> None:
+    await ctx.typing()
+    await ctx.reply_text(ctx.text)
+
+dp.run(AsyncBot(token))             # or: await dp.start_polling(bot)
+```
+
+With an `AsyncBot`, plain `def` handlers still work: they run in a worker thread, and their replies go through
+the same bot.
+
+## Polling or webhook
+
+Zalo delivers messages in one of two ways, and you can't use both at once:
+
+| | Long polling | Webhook |
+|---|---|---|
+| How | `dp.run_polling(bot)` | Zalo POSTs to your HTTPS URL |
+| Good for | development, small bots, no public server | production (Zalo's advice) |
+| Setup | nothing | `bot.set_webhook(url, secret)` once |
+
+While a webhook is set, Zalo turns `getUpdates` off. `run_polling` checks for this and tells you to call
+`bot.delete_webhook()`.
+
+Webhook with FastAPI (see `examples/webhook_flask.py` for Flask):
+
+```python
+from fastapi import FastAPI, Request, Response
+from zalobot import AsyncBot, AsyncWebhookHandler
+
+handler = AsyncWebhookHandler(dp, AsyncBot(token), secret="a-long-random-secret")
+app = FastAPI()
+
+@app.post("/zalo/webhook")
+async def webhook(request: Request) -> Response:
+    status, body = await handler.handle(request.headers, await request.body())
+    return Response(body, status_code=status, media_type="application/json")
+```
+
+The handler checks the `X-Bot-Api-Secret-Token` header (403 if it's wrong) and the body (400 if it isn't an
+update), then runs your handlers. `bot.set_webhook()` and `bot.test_webhook()` return Zalo's check of your URL, such
+as `outcome="webhook.http.403"` with a hint about what to fix.
+
+## Rich text
+
+```python
+from zalobot import Color, Size, Text
+
+msg = (Text().size(Size.LARGE, "Đơn hàng #1024").plain("\n")
+       .bullets(["Cà phê sữa đá: 29,000đ", "Bánh mì: 25,000đ"])
+       .bold("Tổng: ").plain("54,000đ ").color(Color.GREEN, "✅ đã thanh toán"))
+bot.send_message(chat_id, msg)
+```
+
+You can also let Zalo parse the markup: `bot.send_message(chat_id, "**bold** {red}red{/red}", parse_mode="markdown")`
+or `parse_mode="html"`.
+
+## Errors and retries
+
+Each documented error code has its own exception, all subclasses of `zalobot.ZaloError`:
+
+| Code | Exception |
+|---|---|
+| 400 | `BadRequest` |
+| 401 | `Unauthorized` (token expired or wrong) |
+| 403 | `Forbidden` |
+| 404 | `NotFound` |
+| 408 | `TimedOut` |
+| 410 | `InvalidChat` (no such chat for this bot; not in Zalo's table) |
+| 429 | `QuotaExceeded` |
+| network failure | `NetworkError` |
+
+The real API answers errors with HTTP 200 and the code in the body; zalobot reads the body either way.
+
+Retries are off by default. Turn them on with `Bot(token, retry=RetryPolicy(attempts=3))`: quota errors and
+network errors are retried with doubling waits, while 401 never is. A send (`send_message`, `send_photo` ...) is
+retried after a network error only if the request never left (connection refused or timed out): after a read
+timeout Zalo may already have delivered it, and a retry would send it twice. Inputs that break the documented limits raise
+`ValueError` before any request is sent: text over 2,000 characters (counted like Zalo's server, where most emoji
+take 2), a secret shorter than 8, or a voice file that isn't `.aac`.
+
+## Testing your bot
+
+```python
+from zalobot.testing import FakeZalo
+
+def test_echo():
+    fake = FakeZalo()
+    fake.push_text("hello")                      # a user writes to the bot
+    with fake.bot() as bot:
+        for update in bot.get_updates():
+            dp.feed(bot, update)
+    assert fake.sent[0].text == "hello"          # what the bot sent back
+```
+
+`FakeZalo` answers with the shapes from the official docs. It can fail on demand (`fake.fail(429)`), and it can
+deliver queued updates to a webhook handler (`fake.deliver_webhook(handler)`).
+
+## Links
+
+- Source and issues: https://github.com/nttams/zalobot
+- Zalo Bot Platform docs: https://bot.zaloplatforms.com/docs/
+- Changelog: [CHANGELOG.md](https://github.com/nttams/zalobot/blob/main/CHANGELOG.md)
+- Contributing: [CONTRIBUTING.md](https://github.com/nttams/zalobot/blob/main/CONTRIBUTING.md)
+
+zalobot is an independent project, not made or endorsed by Zalo or VNG. MIT licensed.

zalobot_sdk-0.1.0/docs/api.md

@@ -0,0 +1,35 @@
+# API reference
+
+## Clients
+
+::: zalobot.client.Bot
+
+::: zalobot.client.AsyncBot
+
+::: zalobot._core.RetryPolicy
+
+## Types
+
+::: zalobot.types
+
+## Handlers and polling
+
+::: zalobot.dispatcher
+
+::: zalobot.filters
+
+## Webhooks
+
+::: zalobot.webhook
+
+## Rich text
+
+::: zalobot.text
+
+## Errors
+
+::: zalobot.errors
+
+## Testing
+
+::: zalobot.testing

zalobot_sdk-0.1.0/docs/changelog.md

@@ -0,0 +1,3 @@
+# Changelog
+
+--8<-- "CHANGELOG.md:3"

zalobot_sdk-0.1.0/docs/errors.md

@@ -0,0 +1,48 @@
+# Errors and retries
+
+Every failed call raises a subclass of `zalobot.ZaloError`, with `.code` (Zalo's `error_code`), `.description`
+and `.method`:
+
+| Code | Exception | Usually |
+|---|---|---|
+| 400 | `BadRequest` | invalid fields, wrong method |
+| 401 | `Unauthorized` | the token expired or is wrong (retrying won't help) |
+| 403 | `Forbidden` | Zalo's table says "internal server error" |
+| 404 | `NotFound` | unknown method (Zalo's table says 400; the real API answers 404) |
+| 408 | `TimedOut` | the request took too long (`get_updates` turns it into `[]`) |
+| 410 | `InvalidChat` | no chat with that id for this bot (the real API's code; not in Zalo's table) |
+| 429 | `QuotaExceeded` | over the API quota: slow down |
+| none | `NetworkError` | DNS, TLS, connection or timeout before Zalo answered |
+
+## Checks before sending
+
+These raise `ValueError` without making a request:
+
+- `text` and `caption` must be 1 to 2,000 characters, counted in UTF-16 units as Zalo's Java server counts them
+  (most emoji take 2).
+- `secret_token` must be 8 to 256 characters.
+- The webhook URL must use `https://`.
+- `photo` and `voice_url` must be `http(s)` URLs, and `voice_url` must end in `.aac`.
+
+## Retries
+
+Retries are off by default. Turn them on per bot:
+
+```python
+from zalobot import Bot, RetryPolicy
+
+bot = Bot(token, retry=RetryPolicy(attempts=4, base_delay=1, max_delay=30))
+```
+
+`QuotaExceeded` and `NetworkError` are retried, waiting 1 s, then 2 s, then 4 s. Other errors are raised at once.
+Set `retry_network=False` to retry quota errors only.
+
+Sends are the exception: after a network error, `send_message`, `send_photo`, `send_sticker` and `send_voice` are
+retried only when the request never left (`NetworkError.request_sent` is False: connection refused, connect or pool
+timeout). After a read timeout or a dropped connection, Zalo may already have delivered the message, and a retry
+would send it twice. Reads (`get_me`, `get_webhook_info` ...) are always safe to retry.
+
+## The token stays secret
+
+The token is part of every request URL. zalobot removes it from error messages and `repr(bot)`, and filters it out
+of httpx's request log lines (which log URLs at INFO level). `bot.token` still gives it to you when you need it.

zalobot_sdk-0.1.0/docs/getting-started.md

@@ -0,0 +1,64 @@
+# Getting started
+
+## 1. Make a bot
+
+In the Zalo app, open the official account **Zalo Bot Manager** and tap **Tạo bot**. Name the bot (the name must
+start with "Bot") and confirm. Zalo then sends you the bot **token** in a message. Keep it secret: anyone with the
+token controls the bot.
+
+## 2. Install
+
+```bash
+uv add zalobot-sdk        # or: pip install zalobot-sdk
+```
+
+The package is `zalobot-sdk` on PyPI; in code it is `import zalobot`.
+
+## 3. Check the token
+
+```python
+from zalobot import Bot
+
+with Bot("YOUR_TOKEN") as bot:
+    me = bot.get_me()
+    print(me.id, me.account_name)
+```
+
+A wrong or expired token raises `zalobot.Unauthorized`.
+
+## 4. Answer messages
+
+```python
+from zalobot import Bot, Context, Dispatcher, F
+
+dp = Dispatcher()
+
+@dp.command("start")
+def start(ctx: Context) -> None:
+    ctx.reply_text(f"Xin chào {ctx.message.from_user.display_name}!")
+
+@dp.message(F.text)
+def echo(ctx: Context) -> None:
+    ctx.reply_text(ctx.text or "")
+
+dp.run_polling(Bot("YOUR_TOKEN"))
+```
+
+Message your bot in Zalo. A bot can only answer people who wrote to it: there is no API for starting a
+conversation.
+
+## 5. Or with asyncio
+
+```python
+from zalobot import AsyncBot, AsyncContext, Dispatcher, F
+
+dp = Dispatcher()
+
+@dp.message(F.text)
+async def echo(ctx: AsyncContext) -> None:
+    await ctx.reply_text(ctx.text or "")
+
+dp.run(AsyncBot("YOUR_TOKEN"))
+```
+
+Next: [handlers and filters](handlers.md), then [polling or webhooks](polling-webhooks.md).