# Telegram Bot API Twin — telegram.twins.la

A high-fidelity digital twin of the Telegram Bot API. Code written
against this twin works against api.telegram.org with only hostname and
credential changes.

## Authentication

Bot API: token-in-URL
  Path: /bot<token>/<METHOD>
  The token is returned by POST /_twin/accounts.

Twin Plane: HTTP Basic Auth (tenant_id:tenant_secret)
  Bootstrap a tenant first:
    POST /_twin/tenants -> {tenant_id, tenant_secret}
  Then create a bot inside the tenant:
    POST /_twin/accounts (Basic auth) -> {bot_id, token, username, ...}

Twin Plane Admin: Bearer token
  Header: Authorization: Bearer <admin_token>
  Service-wide operations (list all bots, all logs, all feedback)
  require an admin token set by the deployment owner.

## Key Endpoints

Twin Plane (no auth):
  GET  /_twin/health        — status check
  GET  /_twin/scenarios     — supported scenarios
  GET  /_twin/settings      — twin settings
  GET  /_twin/references    — authoritative sources used to build this twin
  POST /_twin/tenants       — bootstrap a tenant (returns id + secret once)

Twin Plane (Basic tenant_id:tenant_secret):
  POST /_twin/accounts          — create a bot inside the tenant
  GET  /_twin/accounts          — list your bots
  GET  /_twin/logs              — your operation logs
  POST /_twin/simulate/inbound  — deliver a synthetic inbound message to a bot
  POST /_twin/feedback          — submit feedback
  GET  /_twin/feedback          — list your feedback

Bot API (token-in-URL):
  GET  /bot<token>/getMe              — return the bot's User object
  POST /bot<token>/sendMessage        — chat_id, text -> Message
  GET  /bot<token>/getUpdates         — return queued Updates
  POST /bot<token>/setWebhook         — url, secret_token, allowed_updates
  POST /bot<token>/deleteWebhook      — drop_pending_updates: bool
  GET  /bot<token>/getWebhookInfo     — current WebhookInfo

## Quick Start

1. Bootstrap a tenant (no auth):
   curl -X POST https://telegram.twins.la/_twin/tenants \
     -H "Content-Type: application/json" \
     -d '{"friendly_name": "My App"}'
   # -> { tenant_id, tenant_secret }

2. Create a bot inside the tenant:
   curl -X POST https://telegram.twins.la/_twin/accounts \
     -u "TENANT_ID:TENANT_SECRET" \
     -H "Content-Type: application/json" \
     -d '{"username": "my_bot", "first_name": "My Bot"}'
   # -> { bot_id, token, ... }

3. Send a message:
   curl -X POST "https://telegram.twins.la/bot<TOKEN>/sendMessage" \
     -H "Content-Type: application/json" \
     -d '{"chat_id": 123456, "text": "Hello from the twin"}'

4. Set a webhook and simulate inbound:
   curl -X POST "https://telegram.twins.la/bot<TOKEN>/setWebhook" \
     -d 'url=https://your.example.com/telegram&secret_token=hunter2'

   curl -X POST https://telegram.twins.la/_twin/simulate/inbound \
     -u "TENANT_ID:TENANT_SECRET" \
     -H "Content-Type: application/json" \
     -d '{"bot_id": <BOT_ID>, "from_user_id": 42, "text": "ping"}'

## Local Usage

pip install twins-telegram twins-telegram-local
python -m twins_telegram_local

Then use http://localhost:8080 instead of https://telegram.twins.la.

## Feedback

Submit feedback (Basic tenant auth):
  curl -X POST https://telegram.twins.la/_twin/feedback \
    -u "TENANT_ID:TENANT_SECRET" \
    -H "Content-Type: application/json" \
    -d '{
      "body": "Description of what you encountered",
      "category": "bug",
      "context": {"bot_id": 123, "method": "sendMessage"}
    }'

## Reference

GitHub:           https://github.com/twins-la/telegram
Project overview: https://twins.la
All twins:        https://github.com/twins-la/twins-la