# Getting started — Telegram platform for your service

This document is for a **partner service** (recharge, shop, support, …) that wants Telegram without talking to BotFather webhooks itself.

You use **two places**:

1. **Telegram management panel** (admin UI of the Telegram service)
2. **Your own backend** (this sample, or an app an AI builds for you)

---

## Step 1 — Login

Ask your operator for:

- Telegram admin URL (example: `http://host:8080`)
- Login **username** and **password** (tenant account)
- Your **tenant id** (needed later for Open API)

Log in to the Telegram management panel.

---

## Step 2 — Create an App

In the panel: **Telegram → Apps → Add**.

Fill in:

- App name (example: `Recharge demo`)
- App key (short slug, cannot change later)
- **Reply style**
  - **Managed** — templates and event routes live in the panel. Your backend only returns variables for REMOTE routes (or nothing for LOCAL).
  - **Passthrough** — every chat event is POSTed to your backend; you return the full message JSON.
- Status: enabled

Save. Note the numeric **App id**.

You need **two Apps** if you want both Managed and Passthrough (one style per App). Open API works for both.

---

## Step 3 — Backend URL and secret key

Open the App → **Backend**:

- **Backend base URL** — public URL of *your* service (example: `http://host.docker.internal:8090`)
- **Inbound path** — for Passthrough, default `/telegram/inbound`
- **Secret key** — generate/save. Reveal it once and store it.  
  Same secret is used for:
  - HMAC on inbound calls (`X-Telegram-Signature`)
  - Open API MD5 `sign`

Download/copy the secret. You cannot build Open API or inbound HMAC without it.

In this sample, paste platform URL, tenant id, app ids, and secrets on **Connection** (`/connect`). They are stored in table `telegram_connection` and used immediately (no YAML restart).

---

## Step 4 — Attach a bot

Create a bot in BotFather, then either:

- **Panel:** Telegram → Bots → bind username + token to this App, **or**
- **Open API:** `POST /telegram/v1/bots` with Base64(`username|token`)

Telegram still sends updates to the **Telegram service** webhook (`/telegram/webhook` or `/tg/msg`), not to your app.

---

## Step 5 — Build your product in one of two ways

### A) Telegram management panel (Managed)

1. Add **templates** (text, buttons, `{{placeholders}}`).
2. Add **event routes** (`/start`, callbacks) — LOCAL (template only) or REMOTE (HMAC call to your path, then fill template).
3. Optional: import JSON from `managed-templates.json` / `managed-routes.json` (one object at a time), or push them via Open API.

Your backend implements REMOTE paths such as `/api/managed/start` and returns `{ "vars": { ... } }`.

### B) Open API (programmatic)

From your server, `POST https://{telegram-host}/telegram/v1/...` with JSON:

```json
{
  "tenantId": "...",
  "appId": 1,
  "timestamp": 1737000000000,
  "sign": "<md5(secretKey + tenantId + appId + timestamp)>",
  "data": "<Base64 payload>"
}
```

Use this to create/list bots, groups, channels, templates, event routes, and outbound send.

Passthrough Apps still need your inbound HTTP API; do not use templates/routes for chat replies on Passthrough.

---

## What to give an AI

Download the files on the Guidelines page and paste them into the AI with the prompt in `ai-prompt-telegram-app.md`.