API

Authenticate with an API key and drive accounts, inbox, bots, analytics and workflows over HTTP

Everything the dashboard does, it does over this HTTP API. Every path, body and status code below was exercised against a live workspace before this page was published.

Base URL

https://telegramos.net

Requests and responses are JSON (Content-Type: application/json). Exports return a file (.xlsx / .csv) and media downloads return bytes.

Authenticating

Create a key under Settings → API keys, then send it as the X-API-Key header:

curl -H "X-API-Key: tgp_your_key_here" \
     https://telegramos.net/api/accounts

The key is shown once, at creation. It is stored as a SHA-256 hash, so nobody — including us — can recover it. Lose it and you create a new one.

Changing your password, resetting it, disabling 2FA or logging out everywhere revokes every key issued before that moment, permanently.

A browser session uses a cookie instead. The two paths never mix: an X-API-Key request is authenticated purely by that key, and key management (/api-keys) deliberately refuses keys — a key cannot mint or revoke another key (403).

Permissions

The permissions you tick at creation are enforced on every request.

Verbs — one is always required:

Areas — optional. A key that ticks no area reaches every area; a key that ticks one or more is confined to those:

read alone is a read-only key over the whole platform. read + write + inbox can do anything in the inbox only — it gets 403 on /api/accounts.

Request ids

Every response carries an X-Request-ID. Send your own and we use it; send nothing and we generate one:

curl -i -H "X-API-Key: $KEY" -H "X-Request-ID: my-job-42" \
     https://telegramos.net/api/accounts
...
x-request-id: my-job-42

Each request is logged on our side with that id, the path, the status, the duration, the key prefix (never the key) and the workspace:

api.request service=account-service request_id=my-job-42 method=GET
path=/api/accounts status=200 duration_ms=144 auth=key:tgp_t24zIO user=<workspace>

Log the id on your side. While the platform is in beta it is the fastest way for us to find your exact call — quote it in a support ticket and we can pull the whole request path without guessing.

Errors

Errors carry detail:

{"detail": "This API key is scoped to inbox — not 'accounts'."}

Another workspace's object is 404, never 403 — the API never confirms that an id exists.

Conventions

• Ids are UUIDs. A non-UUID path segment is 400 or 404, never a 500.
• Sending is queued, not synchronous. Endpoints that make an account act return 202 with a task_id. The account then sends under the anti-ban pacing rules (see Limits & quotas). Poll the resource to see the result.
• Everything is workspace-scoped. You never pass a workspace id; the key carries it.
• List endpoints take limit/offset or page/page_size depending on the resource; both are optional.

Accounts

Area: accounts.

The session vault lives under the same account: POST /api/accounts/{id}/vault/enable, /disable, /lock, /unlock, /rotate, with GET /api/accounts/{id}/vault for the current state.

Note `/group-invites` is the strictest endpoint in the product, because adding people is the fastest way to lose an account. It refuses with `409` unless the account has finished warm-up, holds a clean @SpamBot verdict less than 36 hours old, and is not reply-only.

Note `/sessions` is for rented accounts. On an account you own it answers `404 no live allocation for this account on your workspace` — that is the correct answer, not a fault.

Proxies

Warm-up

Scraping

POST /api/scraping/jobs
{
  "name": "leads",
  "group_links": ["https://t.me/somepublicgroup"],
  "limit_per_group": 300,
  "max_accounts": 5,
  "patterns": [],
  "keyword_filter": []
}

patterns empty means phone numbers. A paid deep run is billed per message scanned and returns 402 if the wallet can't cover the worst case.

Niche finder

POST /api/niche/jobs
{
  "name": "crypto traders",
  "keywords": ["trading", "signals"],
  "active_within_days": 30,
  "msg_scan_limit": 3000,
  "max_accounts": 5,
  "extract_members": false
}

extract_members dumps raw member lists; it is off by default because it is the ban-risky read.

Lead packages and watches

Mass DM

POST /api/mass-dm/jobs
{
  "recipients": [{"tg_user_id": 123456789, "username": "someone"}],
  "message_text": "hi {first_name}",
  "account_ids": ["<account-uuid>"],
  "per_account_daily_cap": 20,
  "followups": []
}

Supply either recipients or niche_job_id, not both. Suppression takes a list:

POST /api/mass-dm/suppression
{"tg_user_ids": [777000777], "reason": "opted out"}

Inbox

Area: inbox.

Filters on the list: account_id, status, tags, unread_only, source (campaign / mass_dm), campaign_id, job_id, page, page_size.

reply-stats requires source=campaign&campaign_id=... or source=mass_dm&job_id=...; without them it answers 422/400 naming what's missing.

Following a thread

Inbound messages are only recorded for accounts whose message listener is on. An account with power_sender_only: true in GET /api/accounts sends but never receives, so its threads stay empty however often you poll — turn the listener on for it first.

GET /api/conversations/{id}/messages pages backwards by default (before, before_msg_id, limit up to 200) — that is what a UI wants when you scroll up.

A monitor wants the opposite. Pass after_msg_id with the telegram_msg_id of the newest message you already hold and you get only what arrived since, oldest first:

GET /api/conversations/{id}/messages?after_msg_id=19626585&limit=200

telegram_msg_id rises monotonically inside a chat, so the cursor never repeats a message and never skips one. Keep the highest id you have seen, poll with it, and there is nothing to de-duplicate. after_msg_id overrides before/before_msg_id if you send both.

Each message carries direction: in for messages the account received, out for messages sent through this platform. Messages typed by hand in a Telegram client on the same account are not recorded — Telegram delivers them as your own outgoing updates and the listener ignores them.

For push instead of polling, see Webhooks and Real-time events below.

Sending

Reply into an existing thread:

POST /api/conversations/{id}/messages
{"content": "Thanks — one moment.", "media_key": null}

Start a thread with someone not in the inbox yet:

POST /api/conversations
{
  "account_id": "<account-uuid>",
  "recipient_type": "username",
  "recipient": "someone",
  "content": "hello"
}

recipient_type is username, phone or user_id. Both endpoints answer 202:

{"task_id": "...", "conversation_id": null, "queued": true,
 "note": "Message queued. It will appear in the inbox once Telegram acknowledges the send."}

The message appears in GET /api/conversations/{id}/messages once Telegram acknowledges it — typically seconds, longer if the account is at its hourly pacing cap.

Anti-ban guards answer before anything is queued, so handle them:

• A spam-limited account cold-starting a chat: Telegram has limited this account, so it can't start new conversations right now — it can still reply to people who messaged it.
• A warming account cannot initiate, only reply.
• The content filter rejects the text with 422 and a bracketed code — [REPEATED_CHARS], [EXCESSIVE_CAPS], [TOO_MANY_LINKS], [BLOCKED_LINK], [SPAM_PATTERN]. Fix the text and resend; retrying the same body always fails.
• The rolling send budget answers 429 with [HOURLY_MESSAGE_LIMIT] or [DAILY_MESSAGE_LIMIT]. Each account may send 10 messages per hour and 40 per day; the hourly window rolls continuously, so back off rather than rewriting the message. An account whose health score has dropped gets a proportionally smaller budget.

Only a 202 means the send is on its way. If it still fails later — the recipient blocked the account, the account dropped offline — the reason arrives as an inbox.message_failed webhook carrying the same task_id.

Groups, replies, rules, notifications

POST /api/groups
{"identifier": "https://t.me/somepublicgroup", "type": "group", "via_account_id": "<uuid>"}

POST /api/saved-replies
{"title": "greeting", "content": "Hi {first_name}", "variables": ["first_name"]}

POST /api/auto-reply-rules
{
  "account_id": "<account-uuid>",
  "match_type": "contains",
  "match_value": "price",
  "reply_text": "Our pricing is on the site.",
  "is_active": true,
  "delay_min": 2,
  "delay_max": 8
}

match_type is one of any, exact, contains, regex.

Bots

Area: bots.

Campaigns

POST /api/campaigns
{
  "name": "launch",
  "message_a": {"text": "..."},
  "message_b": {"link": "https://t.me/channel/123"},
  "interval_minutes": 30,
  "delay_min_seconds": 15,
  "delay_max_seconds": 90,
  "assignments": [{"account_id": "<uuid>", "group_chat_ids": [-1001234567890]}]
}

Creating does not start it — call /start.

Channel syncs and the bot database

POST /api/botdb/collections
{"name": "leads", "schema": {"fields": [{"key": "email", "type": "text"}]}}

POST /api/botdb/collections/{id}/records
{"data": {"email": "a@b.com"}}

Field definitions use key (not name), and a record whose data has an undeclared key is rejected with unknown field(s): ....

Analytics

Area: analytics.

With the workspace analytics switch off these return empty series rather than an error. AI endpoints draw on the AI quota: check /api/analytics/ai/quota first, and expect 429 once it's spent.

Workflows

Area: tasks.

POST /api/workflows
{"name": "nightly", "definition": {"nodes": [], "edges": []}}

Support

No area — any key reaches these.

Identity

Editing the profile (PATCH /auth/me), like key management, needs a browser session — a key answers 403.

Webhooks

A webhook is the durable way to receive events: we write the event to our database first, then POST it to your URL and keep retrying until you take it. A socket that was disconnected during your deploy loses the event; a webhook does not.

Manage them under Settings → API keys → Webhooks, or over the API (area inbox):

POST /api/webhooks
{"url": "https://your-server.example/telegramos",
 "events": ["inbox.new_message"],
 "description": "prod monitor"}

An empty events list means every type. Ten endpoints per workspace; the URL must be a public http(s) address (private and loopback addresses are refused).

Events

Closing the loop on a send. A send answers 202 with a task_id and nothing else — the account still has to get it past Telegram's pacing. Subscribe to both inbox.new_message and inbox.message_failed and you learn which happened: the success arrives as a message with direction: "out", the failure as inbox.message_failed carrying the same task_id, an error_code (blocked_by_user, privacy_restricted, account_offline, cannot_write, account_banned, …) and a sentence you can show a user.

The request we send

POST /your-path
Content-Type: application/json
X-TGP-Event: inbox.new_message
X-TGP-Delivery: 82a91c75-7446-4ebe-8f79-3013cceaa1d7
X-TGP-Timestamp: 1787308800
X-TGP-Signature: v1=<hex>

{"id": "<delivery id>", "type": "inbox.new_message",
 "created_at": "2026-08-20T10:27:04+00:00",
 "data": {"user_id": "...", "conversation_id": "...",
          "message": {"id": "...", "direction": "in", "content": "...", "sent_at": "..."},
          "conversation": {"id": "...", "title": "...", "peer_id": 123}}}

Verifying the signature. HMAC-SHA256 over {timestamp}.{raw body} with your secret, compared to the hex after v1=. Use the raw bytes — re-serializing the JSON changes them.

import hmac, hashlib

def verify(secret: str, headers, raw_body: bytes) -> bool:
    ts = headers["X-TGP-Timestamp"]
    expected = "v1=" + hmac.new(
        secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(headers["X-TGP-Signature"], expected)

The timestamp is inside the signed material, so reject anything older than a few minutes and a captured delivery can't be replayed at you later.

Delivery rules

• Any 2xx counts as accepted. Answer fast and do the work afterwards — we give up on a request after 10 seconds and treat it as a failure.
• Failures retry after 10s, 1m, 5m, 30m, 2h, 6h, then the delivery is marked failed.
• Five consecutive events that exhaust every retry switch the endpoint off; the dashboard shows why. Turning it back on clears the counter.
• Redirects are not followed. Point us at the final URL.
• The delivery id is stable across retries — key your de-duplication on it.
• Delivered records are kept 7 days, failed ones 30.

Real-time events

The dashboard streams live updates over Socket.IO:

wss://telegramos.net/ws

Authenticate with a session JWT (auth.token), the session cookie, or an API key — pass it as auth.apiKey in the handshake or as an X-API-Key header. A key needs read, and if it is area-scoped at all it must include inbox.

import { io } from 'socket.io-client'

const socket = io('https://telegramos.net', {
  path: '/ws',
  transports: ['websocket'],
  auth: { apiKey: process.env.TGP_API_KEY },
})
socket.on('inbox.new_message', (e) => console.log(e.conversation_id, e.message.content))

Events arrive as named Socket.IO messages: system.connected on connect, then inbox.new_message, notification.new, account.status_change, account.power_changed and friends; subscribe to one account with subscribe:account.

Two things to know before you build on it:

• Browsers are restricted. The handshake checks Origin, and only our own domains are allowed. A server-side client sends no Origin and connects fine; a page on your own domain will be refused. Proxy through your backend.
• A socket delivers once. Anything published while you are disconnected is gone. Use webhooks for delivery you can't afford to miss, or reconcile on reconnect with after_msg_id.

What the API does not cover

• Teams, billing, wallet and the marketplace are session-only: /wallet, /payments/*, /subscriptions/*, /billing/*, /bundles/purchase, /account-resale/*, /referrals/* and /teams/* answer 401 to an API key however it is scoped. There is no key path to spend money, rent an account or change seats — do those in the dashboard. The two exceptions are the public catalogue reads GET /listings and GET /bundles/availability, which need no authentication at all.
• No SDK. Plain HTTP; use whatever client you have.
• No per-key rate limit. Requests are cheap, but the actions behind them are paced per account by the anti-ban limits in Limits & quotas, so a burst of sends queues rather than fires.

A worked example

Reply to the newest unread conversation and wait for the send to land:

KEY="tgp_your_key_here"
BASE="https://telegramos.net"

CONV=$(curl -s -H "X-API-Key: $KEY" \
  "$BASE/api/conversations?unread_only=true&page_size=1" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)[0]['id'])")

curl -s -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
     -H "X-Request-ID: reply-$CONV" \
     -d '{"content":"Thanks for reaching out — one moment."}' \
     "$BASE/api/conversations/$CONV/messages"
# -> 202 {"task_id": "...", "queued": true, ...}

curl -s -H "X-API-Key: $KEY" "$BASE/api/conversations/$CONV/messages" | tail -c 400

Monitoring a conversation

Three moving parts, in the order you set them up.

1. Backfill once, if you want the history. POST /api/accounts/{id}/backfill-history queues a one-shot import of existing chats (owned accounts, no media, up to 1000 messages per chat, broadcast channels skipped). Poll GET /api/accounts/{id}/backfill-history until state is done — the states are queued, running, done, cancelled, and idle means no job is recorded (either it never started or the status expired after 6 hours). Run it once per account; it is heavy on proxy data and everything after it arrives on its own.

2. Take the live stream. Register a webhook for inbox.new_message. Nothing else is needed for messages to keep flowing into the inbox — the account's worker is already listening.

3. Reconcile. After any outage on your side, walk each conversation forward with after_msg_id from the last id you stored. That closes the gap without re-reading the thread.

KEY="tgp_your_key_here"
BASE="https://telegramos.net"

curl -s -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
     -d '{"url":"https://your-server.example/telegramos","events":["inbox.new_message"]}' \
     "$BASE/api/webhooks"
# -> 201 {"id": "...", "secret": "whsec_...", ...}   <- store the secret

curl -s -H "X-API-Key: $KEY" \
     "$BASE/api/conversations/$CONV/messages?after_msg_id=$LAST_SEEN&limit=200"