Tutorials

Eleven short walkthroughs take you from the first dashboard sign-in to your own Telegram command. Each step works against your own server (HOOKA_URL, for example http://localhost:8080 from the README quickstart).

Step	Tutorial
1	Sign in to the dashboard
2	Find your Telegram chat ID
3	Create a topic and route it to Telegram
4	Mint a scoped API token
5	Publish your first message
6	Publish from the CLI
7	Accept webhooks without an API key
8	Collect answers with a form
9	Schedule a reminder
10	Build your own app
11	See it all on the Flow map

1. Sign in to the dashboard

The dashboard is Hooka's control plane: topics, routes, tokens, forms, reminders and apps in one place.

1. Open the dashboard and enter your passphrase.
2. Flow is home. It draws every message moving Messages → Topics → Routes.
3. Topics, Tokens, Forms, Reminders and Store each get a page; Dashboard shows counts, pending reminders, audit events and API health.

2. Find your Telegram chat ID

Hooka delivers through its Telegram bot. Every Telegram route needs a chat ID, and the bot tells you yours.

1. Open a chat with the Hooka bot, or add the bot to a group.
2. Send /chatid. The bot replies with the chat ID, the chat type and any topics already bound to the chat.
3. In a forum group the reply also includes the thread ID, so a route can target one thread.

3. Create a topic and route it to Telegram

A topic is a named channel. A route is where its messages go: a Telegram chat or a webhook.

1. Topics → New topic.
2. Name it after what it carries (letters, digits, _ and -), for example deploys.
3. Provider Telegram chat, paste the chat ID, keep parse mode HTML, then Save.
4. Add more routes later with Add route. One message fans out to every route.

curl -sS -X POST "$HOOKA_URL/topics/deploys/routes" \
  -H "Authorization: Bearer $HOOKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"telegram","chat_id":"<chat id>","parse_mode":"HTML"}'

4. Mint a scoped API token

Give each script its own token, limited to the topics it needs and only the permissions it uses.

1. Tokens → New token and name it for the caller, for example ci-deploys.
2. Set the topic pattern: an exact name, a prefix wildcard like deploys*, or * for all topics.
3. Keep Publish on; turn on Read only if the caller consumes messages or the SSE stream.
4. Create, then copy the value. It is shown once; Hooka stores only a hash. Revoke it from the list at any time.

5. Publish your first message

One HTTP call. Hooka stores the message, then delivers it to every route on the topic.

1. Export HOOKA_URL and the token as HOOKA_API_KEY.
2. POST to /publish/{topic}. The response has the stored message_id and each route's outcome.
3. Send an Idempotency-Key. Retrying with the same key returns the same message (idempotency_hit: true) and nothing is sent twice.

export HOOKA_URL="https://hooka.example.com"
export HOOKA_API_KEY="hk_…"

curl -sS -X POST "$HOOKA_URL/publish/deploys" \
  -H "Authorization: Bearer $HOOKA_API_KEY" \
  -H "Idempotency-Key: deploy-api-v1.42" \
  -d '{"title":"Deploy finished","text":"<b>api v1.42</b> is live","priority":4,"tags":["deploy","prod"]}'

6. Publish from the CLI

The hooka CLI wraps the API: publish, routes, tokens, reminders and streams. hooka update keeps it current.

1. The CLI reads the same HOOKA_URL and HOOKA_API_KEY.
2. hooka publish <topic> --text … adds --title, --priority and --tags as flags.
3. Telegram Bot API fields pass through, for example inline buttons with --reply-markup-json.

hooka publish deploys --title "CI" --text "Build #1289 passed on main" --tags ci,green

hooka publish deploys --title "Release v1.43?" --text "Staging checks are green." \
  --reply-markup-json '{"inline_keyboard":[[{"text":"Open release","url":"https://example.com"}]]}'

7. Accept webhooks without an API key

/webhook mints an anonymous, publish-only URL bound to a chat. Paste it into GitHub, Stripe, Zapier or anything that can POST.

1. In the chat, send /webhook. The bot replies with an /in/… capability URL.
2. POST JSON with title and text, or plain text; the first line becomes the title.
3. The URL can only post into that chat. /webhook rotate re-issues it and /webhook revoke disables it.

curl -sS -X POST "$HOOK_URL" -H 'Content-Type: application/json' \
  -d '{"title":"New signup","text":"[email protected] joined the beta"}'

curl -sS -X POST "$HOOK_URL" --data-binary $'Nightly backup\nFinished in 4m12s'

8. Collect answers with a form

Build a form in the dashboard and share its public link. Every response is stored and exports as CSV.

1. Forms → New form. Add a title, a description and questions: short answer, paragraph, single or multiple choice.
2. Create form. It opens for responses immediately.
3. Share the public link. Respondents need no account.
4. Responses appear on the form page, newest first, with Export CSV.

9. Schedule a reminder

Publish later: once after a delay, at a set time, every interval, or on a cron schedule.

1. Reminders → New reminder and pick the topic.
2. In takes a duration (30s, 5m, 1h30m); At an RFC 3339 time; Every an interval; Cron a 5-field schedule.
3. Add the title and text, then Schedule. Reminders are checked every 30 seconds and publish through the topic's routes.

10. Build your own app

An app owns a Telegram command. Hooka routes the command to your program and delivers its replies; your code runs anywhere.

1. As the Telegram admin, send /app install dice Dice in the chat that should get replies.
2. Register a command: /app command dice roll --default Roll a die.
3. Run a loop that reads app-dice-in over SSE and publishes replies to app-dice-out, with a token scoped to app-dice-*.
4. Anyone in the installed chat can now run /dice 20.

for line in urlopen(Request(f"{URL}/topics/app-dice-in/stream?include_payload=true", headers=AUTH)):
    if not line.startswith(b"data:"):
        continue
    cmd = json.loads(line[5:]).get("payload") or {}
    if cmd.get("kind") == "app.command":
        publish(cmd["out_topic"], {"chat_id": cmd["chat_id"], "text": f"rolled {randint(1, 6)}"})

11. See it all on the Flow map

Every message, topic and route in one picture, with delivery history and an audit trail behind it.

1. Flow draws Messages → Topics → Routes. Hover a topic to trace its path.
2. Open a topic's Messages tab to see what was published and delivered.
3. Dashboard sums up topics, routes, 24-hour volume and API health.

Optional: tutorial videos

These tutorials are text-only by default, and so is the dashboard's /docs/tutorials page. The repository does not ship videos. To show your own next to each step, host them under one base URL as tutorials/<step>.mp4 with a tutorials/<step>.jpg poster, where <step> is 01-sign-in, 02-chat-id, … 11-flow, and set HOOKA_MEDIA_URL to that base when you build the dashboard (the docs pages are prerendered). One way to host them is hookad's own media redirect: configure MEDIA_S3_* (see the API reference), upload the files under public/tutorials/, and set HOOKA_MEDIA_URL=https://hooka.example.com/media; hookad then serves /media/tutorials/<step>.mp4 through a short-lived signed redirect.