twins.la

telegram.twins.la

A digital twin of the Telegram Bot API.

What is this?

A high-fidelity digital twin of Telegram's Bot API. Code you write against this twin will work against the real api.telegram.org with only hostname and credential changes. No BotFather account needed to develop.

Supported scenarios

How to use it

Cloud: Point your Bot API client at https://telegram.twins.la instead of api.telegram.org. Bootstrap a tenant via POST /_twin/tenants, create a bot via POST /_twin/accounts, and use the returned token.

Local: Install with pip install twins-telegram-local and run a local instance on any port. Same API, same behavior, your machine.

For agents

Copy this into your agent's system prompt, tool configuration, or CLAUDE.md. Also available as plain text at /_twin/agent-instructions. 

# 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
GitHub twins.la Health Scenarios