API

API HTTP در TelegramOS: با کلید API احراز هویت کنید و اکانت‌ها، اینباکس، بات‌ها، آنالیتیکس و ورک‌فلوها را به‌صورت برنامه‌نویسی‌شده مدیریت کنید.

هر کاری که داشبورد انجام می‌دهد، از طریق همین API HTTP انجام می‌شود. تک‌تک مسیرها، بدنه‌ها و کدهای وضعیتی که در ادامه می‌بینید پیش از انتشار این صفحه روی یک فضای کاری واقعی آزمایش شده‌اند.

آدرس پایه

https://telegramos.net

درخواست‌ها و پاسخ‌ها JSON هستند (Content-Type: application/json). خروجی‌های Export یک فایل برمی‌گردانند (.xlsx / .csv) و دانلود رسانه‌ها بایت خام برمی‌گرداند.

احراز هویت

یک کلید در Settings → API keys بسازید و آن را در هدر X-API-Key بفرستید:

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

کلید فقط یک بار، در لحظه‌ی ساخت، نمایش داده می‌شود. به‌صورت هش SHA-256 ذخیره می‌شود، بنابراین هیچ‌کس — حتی خود ما — نمی‌تواند آن را بازیابی کند. اگر گمش کردید، یک کلید جدید بسازید.

تغییر رمز عبور، بازنشانی آن، غیرفعال‌کردن 2FA یا خروج از همه‌ی دستگاه‌ها تمام کلیدهایی را که پیش از آن لحظه صادر شده‌اند برای همیشه باطل می‌کند.

نشست (session) مرورگر به‌جای کلید از کوکی استفاده می‌کند. این دو مسیر هرگز با هم قاطی نمی‌شوند: درخواستی که X-API-Key دارد صرفاً با همان کلید احراز هویت می‌شود، و مدیریت کلیدها (/api-keys) عمداً کلید را نمی‌پذیرد — یک کلید نمی‌تواند کلید دیگری بسازد یا باطل کند (403).

دسترسی‌ها

دسترسی‌هایی که هنگام ساخت کلید تیک می‌زنید روی تک‌تک درخواست‌ها اعمال می‌شوند.

فعل‌ها — همیشه یکی از این‌ها لازم است:

حوزه‌ها — اختیاری. کلیدی که هیچ حوزه‌ای را تیک نزده باشد به همه‌ی حوزه‌ها می‌رسد؛ کلیدی که یک یا چند حوزه را تیک زده باشد فقط به همان‌ها محدود است:

read به‌تنهایی یک کلید فقط‌خواندنی روی کل پلتفرم است. read + write + inbox می‌تواند فقط در اینباکس هر کاری بکند — روی /api/accounts پاسخ 403 می‌گیرد.

شناسه‌ی درخواست

هر پاسخ یک X-Request-ID دارد. اگر خودتان بفرستید همان را استفاده می‌کنیم؛ اگر چیزی نفرستید، یکی تولید می‌کنیم:

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

هر درخواست در سمت ما با همان شناسه، مسیر، وضعیت، مدت‌زمان، پیشوند کلید (هرگز خود کلید) و فضای کاری لاگ می‌شود:

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>

شناسه را در سمت خودتان هم لاگ کنید. تا وقتی پلتفرم در بتاست، این سریع‌ترین راه برای پیداکردن دقیقاً همان فراخوانی شماست — آن را در تیکت پشتیبانی ذکر کنید تا بتوانیم کل مسیر درخواست را بدون حدس‌زدن بیرون بکشیم.

خطاها

خطاها فیلد detail دارند:

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

شیء متعلق به فضای کاری دیگر 404 است، هرگز 403 — API هیچ‌وقت وجود یک شناسه را تأیید نمی‌کند.

قراردادها

• شناسه‌ها UUID هستند. یک بخش مسیر که UUID نباشد 400 یا 404 می‌گیرد، هرگز 500.
• ارسال صف می‌شود، همزمان نیست. endpointهایی که اکانت را وادار به انجام کاری می‌کنند 202 به همراه یک task_id برمی‌گردانند. سپس اکانت طبق قوانین زمان‌بندی ضدبن ارسال می‌کند (به محدودیت‌ها و سهمیه‌ها نگاه کنید). برای دیدن نتیجه، خود منبع را poll کنید.
• همه‌چیز در محدوده‌ی فضای کاری است. هیچ‌وقت شناسه‌ی فضای کاری را نمی‌فرستید؛ کلید آن را با خود دارد.
• endpointهای لیست بسته به منبع، limit/offset یا page/page_size می‌گیرند؛ هر دو اختیاری‌اند.

اکانت‌ها

حوزه: accounts.

هر ردیف اکانت، به‌محض اینکه worker متصل شد، هویت تلگرامی خود اکانت را هم دارد: tg_user_id (شناسه‌ی عددی تلگرام)، tg_username، tg_first_name، tg_last_name. tg_user_id همان مقداری است که وقتی رشته‌ی گفتگوی شخص دیگری به این اکانت اشاره می‌کند، به‌عنوان peer_id ظاهر می‌شود.

گاوصندوق نشست زیر همان اکانت قرار دارد: POST /api/accounts/{id}/vault/enable، /disable، /lock، /unlock، /rotate، و GET /api/accounts/{id}/vault برای وضعیت فعلی.

یادداشت /group-invites سخت‌گیرترین endpoint محصول است، چون افزودن افراد سریع‌ترین راه از دست دادن اکانت است. مگر اینکه اکانت گرم‌کردن را تمام کرده باشد، یک رأی پاک از ⁦@SpamBot⁩ با عمر کمتر از 36 ساعت داشته باشد و در حالت فقط‌پاسخ نباشد، با 409 رد می‌کند.

یادداشت /sessions مخصوص اکانت‌های اجاره‌ای است. روی اکانتی که مال خودتان است پاسخ 404 no live allocation for this account on your workspace می‌دهد — این پاسخ درست است، نه یک خطا.

پروکسی‌ها

گرم‌کردن

محدودیت‌های ضدبن

تک‌تک throttleهای این API — بودجه‌ی پیام سرد و پاسخ، شیب گرم‌کردن، کندشدن پس از PeerFlood، سقف روزانه‌ی کمپین، فاصله‌گذاری در یک گروه و تأخیرهای انسان‌نما — محافظت خود پلتفرم است، نه تلگرام. در پلن پولی می‌توانید آن را برای هر اکانت با POST /api/accounts/{id}/safety تغییر دهید یا خاموش کنید، یا برای همه‌ی اکانت‌ها یک‌جا با POST /api/accounts/bulk/safety:

{
  "mode": "custom",
  "cold_hourly": 30, "cold_daily": 200,
  "reply_hourly": 120, "reply_daily": 600,
  "per_minute": 6, "min_gap_seconds": 3,
  "campaign_daily": 200, "group_spacing_minutes": 30,
  "content_filter": true, "spam_circuit": true,
  "warmup_ramp": false, "human_delay": true,
  "trial_cap": true, "spambot_throttle": true,
  "join_hourly": 40, "join_daily": 60,
  "forward_hourly": 20, "forward_daily": 200,
  "invite_hourly": 4, "invite_daily": 20,
  "report_hourly": 5, "report_daily": 20,
  "massdm_daily": 30, "massdm_delay_min": 45, "massdm_delay_max": 120,
  "massdm_warmup_ramp": true, "massdm_flood_hold": true, "massdm_circuit": true
}

mode یکی از default (قوانین پلتفرم)، custom (اعدادی که خودتان می‌فرستید؛ هر چه را جا بگذارید مقدار پلتفرمی‌اش را نگه می‌دارد؛ 0 روی per_minute، min_gap_seconds، campaign_daily یا group_spacing_minutes یعنی بدون محدودیت) یا off (هیچ throttle پلتفرمی‌ای اصلاً وجود ندارد) است. جفت‌های join_*، forward_*، invite_* و report_* بودجه‌ی هر نوع اقدام هستند؛ فیلدهای massdm_* رفتار dispatcher پیام انبوه را کنترل می‌کنند (massdm_daily سقف هر اکانت را که یک job می‌تواند درخواست کند بالا می‌برد، massdm_circuit تعیین می‌کند که وقتی اکانت‌های یک job با flood یا بلاک برمی‌گردند، job متوقف شود یا نه؛ تا وقتی حتی یکی از اکانت‌های job آن را روشن نگه داشته باشد، job محافظت‌شده می‌ماند). پروفایل فعلی به‌عنوان safety روی شیء اکانت برمی‌گردد و از ارسال بعدی اثر می‌کند — بدون نیاز به اتصال مجدد. FloodWait و محدودیت‌های اسپم خود تلگرام هر چه هم تنظیم کنید همچنان اعمال می‌شوند، و ریسک بن یک اکانت شل‌شده پای خودتان است. پلن Free پاسخ 402 می‌دهد. قانون «هر نفر، یک اکانت» از این پروفایل جداست و حتی در حالت off روشن می‌ماند؛ آن را برای هر اکانت با /api/accounts/{id}/contact-policy تغییر دهید.

اسکرپینگ

اسکرپینگ یک استخراج یک‌باره است، نه یک مانیتور: یک اکانت یک بار تاریخچه‌ی پیام‌های هدف را می‌گردد و شماره‌های تلفن (یا الگوهایی که به آن می‌دهید) را بیرون می‌کشد. کانال‌های broadcast هم به‌عنوان هدف کار می‌کنند، اما پست‌هایشان از طرف خود کانال است، بنابراین اجرای روی کانال به‌ندرت شماره‌ای برمی‌گرداند. برای دنبال‌کردن چیزی که یک کانال منتشر می‌کند، به‌جای آن از مانیتورکردن یک کانال استفاده کنید. دوره‌ی آزمایشی رایگان نتایج را می‌شمارد، نه پیام‌های اسکن‌شده، بنابراین اجرایی که چیزی پیدا نکند هزینه‌ای ندارد.

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

patterns خالی یعنی شماره‌ی تلفن؛ انواع پیش‌فرض دیگر email، username، url و price هستند، و الگوی custom regex خودتان را می‌گیرد. group_links هم گروه‌های عمومی را می‌پذیرد و هم کانال‌های عمومی.

اجرای عمیق پولی به‌ازای هر پیام اسکن‌شده محاسبه می‌شود و اگر کیف پول بدترین حالت را پوشش ندهد 402 برمی‌گرداند. دوره‌ی آزمایشی رایگان طور دیگری شمرده می‌شود: 50 نتیجه است، بنابراین اجرایی که چیزی پیدا نکند هزینه‌ای برای شما ندارد. از آن طرف هم محدود است — اجراهای رایگان بعد از خواندن مجموعاً 2,000 پیام متوقف می‌شوند، هر چه هم برگردانده باشند. GET /api/scraping/usage هر دو شمارنده را گزارش می‌کند (used / limit و scanned / scan_limit).

نیچ‌یاب

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 لیست خام اعضا را بیرون می‌ریزد؛ به‌طور پیش‌فرض خاموش است چون همین خواندن است که ریسک بن دارد.

پکیج‌های لید و watchها

پیام انبوه

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": []
}

یا recipients را بدهید یا niche_job_id را، نه هر دو. suppression یک لیست می‌گیرد:

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

اینباکس

حوزه: inbox.

فیلترهای لیست: account_id، peer_type (user / bot / group / channel)، status، tags، unread_only، source (campaign / mass_dm)، campaign_id، job_id، page، page_size.

reply-stats به source=campaign&campaign_id=... یا source=mass_dm&job_id=... نیاز دارد؛ بدون آن‌ها با 422/400 جواب می‌دهد و می‌گوید چه چیزی کم است.

مانیتورکردن یک کانال

کانال broadcast هم گفتگویی مثل بقیه است — peer_type آن channel است — اما پست‌هایش opt-in هستند. یک کانال پرکار می‌تواند روزانه صدها مگابایت از پروکسی یک اکانت رد کند، بنابراین شنونده پست‌های هر کانالی را که خودتان درخواست نکرده‌اید دور می‌ریزد. به همین دلیل کانالی که عضوش شده‌اید تا وقتی آن را اضافه نکنید هیچ چیزی نشان نمی‌دهد: پشتیبانی‌اش کم نیست، خاموش است.

روشن‌کردن یکی:

1. با یکی از اکانت‌های خودتان (در خود تلگرام) به کانال بپیوندید.
2. آن را به فهرست پایش اضافه کنید: POST /api/groups با بدنه‌ی {"identifier": "@thechannel", "type": "channel", "via_account_id": "<uuid>"}.
3. پست‌ها را بخوانید: GET /api/conversations?peer_type=channel و بعد GET /api/conversations/{id}/messages?after_msg_id=<last seen>.

identifier یک @username عمومی، یک لینک t.me/name یا یک شناسه‌ی عددی peer می‌گیرد. type می‌تواند group، supergroup یا channel باشد؛ هر چه بفرستید در اولین همگام‌سازی از روی تلگرام تصحیح می‌شود، همراه با members_count، posts_per_day و شناسه‌ی marked peer.

کانال‌های خصوصی @username ندارند، و لینک دعوت (t.me/+…) هم شناسه‌ی peer ندارد، بنابراین هیچ‌کدام نمی‌تواند یکی را مشخص کند. یک بار لیست چت‌های اکانت را همگام کنید و کانال با شناسه‌ی عددی‌اش ظاهر می‌شود، که بعد آن را به روش معمول اضافه می‌کنید:

POST /api/accounts/{account_id}/backfill-history?discover_only=true
   → registers the account's chats, pulls no messages, costs almost no proxy data

GET /api/conversations?peer_type=channel
   → the private channel is now listed, with its peer_id

POST /api/groups
{"identifier": "-1001234567890", "type": "channel", "via_account_id": "<uuid>"}

در داشبورد همین جریان همان انتخاب‌گر کانال در Groups → Track group است.

وقتی ردیابی شد، پست‌های جدید مثل هر پیام ورودی دیگری می‌رسند: روی رویداد وب‌سوکت inbox.new_message و روی وب‌هوکی که به آن مشترک شده باشد. کانالی که در تلگرام بی‌صدا کرده‌اید همچنان هر دو را می‌فرستد، با conversation.muted: true، بنابراین یک یکپارچه‌سازی هیچ پستی را از دست نمی‌دهد؛ فقط داشبورد ساکت می‌ماند.

peer_type چهار مقدار دارد: user، bot، group و channel. سوپرگروه‌ها group هستند — این تفاوت فقط برای /api/groups مهم است، که بعد از اولین همگام‌سازی‌اش supergroup را گزارش می‌کند.

وقتی کانالی مانیتور می‌شود، پست‌هایش مثل هر پیام دیگری می‌رسند: در GET /api/conversations/{id}/messages، روی رویداد وب‌سوکت inbox.new_message، و از طریق وب‌هوکی که به inbox.new_message مشترک شده است.

دو چیزی که این قابلیت *نیستند*: /api/channel-syncs پست‌های یک کانال را در کانال دیگری که در کنترل شماست آینه می‌کند (یک forwarder است، نه خواننده)، و /api/warmup/channels لیست کانال‌هایی است که اکانت جدید در حین گرم‌شدن عضوشان می‌شود. هیچ‌کدام محتوای کانال را برنمی‌گردانند. POST /api/groups/{id}/sync فقط شمار اعضا و پست‌ها را تازه می‌کند — پست‌ها را واکشی نمی‌کند.

دنبال‌کردن یک رشته‌ی گفتگو

پیام‌های ورودی فقط برای اکانت‌هایی ثبت می‌شوند که شنونده‌ی پیامشان روشن است. اکانتی که در GET /api/accounts مقدار power_sender_only: true دارد می‌فرستد اما هرگز دریافت نمی‌کند، بنابراین هر چقدر هم poll کنید رشته‌هایش خالی می‌مانند — اول شنونده را برایش روشن کنید.

GET /api/conversations/{id}/messages به‌طور پیش‌فرض رو به عقب صفحه‌بندی می‌کند (before، before_msg_id، limit تا 200) — همان چیزی که یک UI وقتی به بالا اسکرول می‌کنید می‌خواهد.

یک مانیتور برعکسش را می‌خواهد. after_msg_id را با telegram_msg_id جدیدترین پیامی که از قبل دارید بفرستید و فقط آنچه از آن زمان رسیده را، از قدیمی‌ترین به جدیدترین، می‌گیرید:

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

telegram_msg_id داخل یک چت به‌صورت یکنوا افزایش می‌یابد، بنابراین این cursor هیچ پیامی را تکرار نمی‌کند و هیچ‌کدام را جا نمی‌اندازد. بالاترین شناسه‌ای که دیده‌اید را نگه دارید، با آن poll کنید، و دیگر چیزی برای حذف تکراری‌ها نمی‌ماند. اگر هر دو را بفرستید، after_msg_id بر before/before_msg_id غلبه می‌کند.

هر پیام یک direction دارد: in برای پیام‌هایی که اکانت دریافت کرده، out برای پیام‌هایی که از طریق این پلتفرم فرستاده شده‌اند. پیام‌هایی که با دست در یک کلاینت تلگرام روی همان اکانت تایپ شده‌اند ثبت نمی‌شوند — تلگرام آن‌ها را به‌عنوان آپدیت‌های خروجی خودتان می‌فرستد و شنونده آن‌ها را نادیده می‌گیرد.

برای push به‌جای polling، به وب‌هوک‌ها و رویدادهای بلادرنگ در ادامه نگاه کنید.

ارسال

پاسخ در یک رشته‌ی گفتگوی موجود:

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

شروع گفتگو با کسی که هنوز در اینباکس نیست:

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

recipient_type یکی از username، phone یا user_id است. هر دو endpoint پاسخ 202 می‌دهند:

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

پیام به‌محض اینکه تلگرام ارسال را تأیید کند در GET /api/conversations/{id}/messages ظاهر می‌شود — معمولاً چند ثانیه، و اگر اکانت به سقف زمان‌بندی ساعتی‌اش رسیده باشد بیشتر.

گاردهای ضدبن پیش از اینکه چیزی صف شود جواب می‌دهند، پس آن‌ها را مدیریت کنید:

• اکانتی که محدودیت اسپم دارد و می‌خواهد یک چت را از صفر شروع کند: Telegram has limited this account, so it can't start new conversations right now — it can still reply to people who messaged it.
• اکانت در حال گرم‌شدن نمی‌تواند گفتگو را شروع کند، فقط می‌تواند پاسخ بدهد.
• فیلتر محتوا متن را با 422 و یک کد داخل براکت رد می‌کند — [REPEATED_CHARS]، [EXCESSIVE_CAPS]، [TOO_MANY_LINKS]، [BLOCKED_LINK]، [SPAM_PATTERN]. متن را درست کنید و دوباره بفرستید؛ تلاش مجدد با همان بدنه همیشه شکست می‌خورد.
• بودجه‌ی ارسال لغزان با 429 و [HOURLY_MESSAGE_LIMIT] یا [DAILY_MESSAGE_LIMIT] جواب می‌دهد. پیام سرد به 10 پیام در ساعت و 40 در روز برای هر اکانت محدود است. وقتی طرف مقابل جواب داد، هر پیام بعدی در آن رشته به‌عنوان پاسخ شمرده می‌شود و به‌جایش 60 در ساعت و 300 در روز می‌گیرد — چه از طریق POST /api/conversations/{id}/messages بفرستید و چه همچنان POST /api/conversations را با همان گیرنده فراخوانی کنید. پنجره‌ی ساعتی پیوسته می‌لغزد، پس به‌جای بازنویسی پیام عقب بنشینید. اکانتی که امتیاز سلامتش افت کرده بودجه‌ی متناسباً کوچک‌تری می‌گیرد. پلن‌های پولی می‌توانند این بودجه‌ها را برای هر اکانت تغییر دهند یا حذف کنند — به محدودیت‌های ضدبن نگاه کنید؛ پروفایل custom کدهای [MINUTE_MESSAGE_LIMIT] و [MESSAGE_GAP_LIMIT] را هم به کدهای ممکن 429 اضافه می‌کند.

فقط 202 یعنی ارسال در راه است. اگر بعداً باز هم شکست بخورد — گیرنده اکانت را بلاک کرده، اکانت آفلاین شده — دلیلش به‌صورت وب‌هوک inbox.message_failed با همان task_id می‌رسد.

گروه‌ها، پاسخ‌ها، قوانین، اعلان‌ها

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 یکی از any، exact، contains، regex است.

بات‌ها

حوزه: bots.

کمپین‌ها

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]}]
}

ساختن، آن را شروع نمی‌کند — /start را فراخوانی کنید.

همگام‌سازی کانال‌ها و دیتابیس بات

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

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

تعریف فیلدها از key استفاده می‌کند (نه name)، و رکوردی که در data کلیدی اعلام‌نشده داشته باشد با unknown field(s): ... رد می‌شود.

آنالیتیکس

حوزه: analytics.

وقتی سوییچ آنالیتیکس فضای کاری خاموش باشد، این‌ها به‌جای خطا سری‌های خالی برمی‌گردانند. endpointهای AI از سهمیه‌ی AI مصرف می‌کنند: اول /api/analytics/ai/quota را چک کنید، و وقتی تمام شد انتظار 429 داشته باشید.

ورک‌فلوها

حوزه: tasks.

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

پشتیبانی

بدون حوزه — هر کلیدی به این‌ها می‌رسد.

هویت

ویرایش پروفایل (PATCH /auth/me)، مثل مدیریت کلیدها، به نشست مرورگر نیاز دارد — کلید پاسخ 403 می‌گیرد.

وب‌هوک‌ها

وب‌هوک راه پایدار دریافت رویدادهاست: ما اول رویداد را در دیتابیس خودمان می‌نویسیم، بعد آن را به URL شما POST می‌کنیم و در صورت شکست دوباره تلاش می‌کنیم. سوکتی که در حین دیپلوی شما قطع شده رویداد را از دست می‌دهد؛ وب‌هوک نه.

آن‌ها را در Settings → API keys → Webhooks مدیریت کنید، یا از طریق API (حوزه‌ی inbox):

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

لیست events خالی یعنی همه‌ی انواع. حداکثر ده endpoint برای هر کاربر؛ URL باید یک آدرس عمومی http(s) باشد (آدرس‌های خصوصی و loopback رد می‌شوند).

رویدادها

بستن حلقه‌ی یک ارسال. یک ارسال با 202 و یک task_id جواب می‌دهد و دیگر هیچ — اکانت هنوز باید آن را از زمان‌بندی تلگرام رد کند. به هر دو رویداد inbox.new_message و inbox.message_failed مشترک شوید و می‌فهمید کدام اتفاق افتاده: موفقیت به‌صورت پیامی با direction: "out" می‌رسد، شکست به‌صورت inbox.message_failed با همان task_id، یک error_code (blocked_by_user، privacy_restricted، account_offline، cannot_write، account_banned، …) و یک جمله که می‌توانید به کاربر نشان دهید.

درخواستی که ما می‌فرستیم

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": "...", "account_id": "...", "conversation_id": "...",
          "message": {"id": "...", "direction": "in", "sender_id": 123, "sender_username": "...",
                      "content": "...", "sent_at": "..."},
          "conversation": {"id": "...", "title": "...", "peer_id": 123,
                           "peer_username": "...", "peer_type": "channel", "muted": false}}}

conversation.id برای رشته‌ی گفتگوی یک اکانت با یک peer ثابت است، پیام از هر طرفی که برود: پیام خروجی یک اکانت و پاسخ به آن همان conversation.id را دارند، پس همین کلیدی است که باید روی آن مشترک شوید. peer_id همیشه شناسه‌ی تلگرام طرف مقابل است، هرگز شناسه‌ی خود اکانت نیست، و message.direction می‌گوید کی آن را نوشته: out اکانت است، in طرف مقابل. message.sender_id / message.sender_username آن را صریح می‌کنند: در in شناسه و نام کاربری تلگرام طرف مقابل، در out شناسه و نام کاربری خود اکانت (null برای عضو گروه یا کانال، که هویتش را حمل نمی‌کنیم). دو اکانت خودتان که با هم صحبت می‌کنند دو رشته‌ی گفتگو تولید می‌کنند (یکی برای هر اکانت)، هر کدام با شناسه‌ی خودش.

تأیید امضا. HMAC-SHA256 روی {timestamp}.{raw body} با secret شما، که با مقدار hex بعد از v1= مقایسه می‌شود. از بایت‌های خام استفاده کنید — سریال‌سازی دوباره‌ی JSON آن‌ها را تغییر می‌دهد.

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)

timestamp داخل محتوای امضاشده است، بنابراین هر چیزی را که بیش از چند دقیقه قدمت دارد رد کنید تا یک تحویل ضبط‌شده بعداً نتواند دوباره روی شما replay شود.

قواعد تحویل

• هر 2xx به‌معنای پذیرش است. سریع جواب بدهید و کار را بعدش انجام دهید — ما بعد از 10 ثانیه از یک درخواست دست می‌کشیم و آن را شکست حساب می‌کنیم.
• شکست‌ها بعد از 10 ثانیه، 1 دقیقه، 5 دقیقه، 30 دقیقه و 2 ساعت دوباره تلاش می‌شوند — در مجموع شش تلاش — و بعد تحویل failed علامت می‌خورد.
• پنج رویداد پشت‌سرهم که همه‌ی تلاش‌های مجدد را تمام کنند endpoint را خاموش می‌کنند؛ داشبورد دلیلش را نشان می‌دهد. روشن‌کردن دوباره شمارنده را صفر می‌کند.
• ریدایرکت‌ها دنبال نمی‌شوند. ما را به URL نهایی هدایت کنید.
• شناسه‌ی تحویل در تلاش‌های مجدد ثابت می‌ماند — حذف تکراری‌ها را روی آن کلید کنید.
• رکوردهای تحویل‌شده 7 روز نگه داشته می‌شوند، شکست‌خورده‌ها 30 روز.

رویدادهای بلادرنگ

داشبورد آپدیت‌های زنده را از طریق Socket.IO استریم می‌کند:

wss://telegramos.net/ws

با JWT نشست (auth.token)، کوکی نشست، یا یک کلید API احراز هویت کنید — آن را به‌صورت auth.apiKey در handshake یا به‌صورت هدر X-API-Key بفرستید. کلید به read نیاز دارد، و اگر اصلاً محدود به حوزه است باید 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))

رویدادها به‌صورت پیام‌های نام‌دار Socket.IO می‌رسند: system.connected هنگام اتصال، بعد inbox.new_message، notification.new، account.status_change، account.power_changed و امثال آن؛ برای اشتراک روی یک اکانت از subscribe:account استفاده کنید.

دو چیز که پیش از ساختن روی آن باید بدانید:

• مرورگرها محدود هستند. handshake هدر Origin را چک می‌کند و فقط دامنه‌های خود ما مجازند. کلاینت سمت سرور Origin نمی‌فرستد و بی‌مشکل متصل می‌شود؛ صفحه‌ای روی دامنه‌ی خودتان رد می‌شود. از طریق بک‌اند خودتان پروکسی کنید.
• سوکت فقط یک بار تحویل می‌دهد. هر چیزی که در زمان قطع‌بودن شما منتشر شده باشد از دست رفته است. برای تحویلی که نمی‌توانید از دستش بدهید از وب‌هوک استفاده کنید، یا هنگام اتصال مجدد با after_msg_id وضعیت را همگام کنید.

چه چیزهایی را API پوشش نمی‌دهد

• تیم‌ها، صورت‌حساب، کیف پول و مارکت‌پلیس فقط با نشست کار می‌کنند: /wallet، /payments/*، /subscriptions/*، /billing/*، /bundles/purchase، /account-resale/*، /referrals/* و /teams/* به کلید API، با هر محدوده‌ای که داشته باشد، 401 می‌دهند. هیچ مسیر مبتنی بر کلیدی برای خرج‌کردن پول، اجاره‌ی اکانت یا تغییر seatها وجود ندارد — این‌ها را در داشبورد انجام دهید. دو استثنا خواندن‌های کاتالوگ عمومی GET /listings و GET /bundles/availability هستند که اصلاً به احراز هویت نیاز ندارند.
• SDK ندارد. HTTP ساده؛ از هر کلاینتی که دارید استفاده کنید.
• محدودیت نرخ به‌ازای کلید ندارد. درخواست‌ها ارزان‌اند، اما اقدامات پشت آن‌ها به‌ازای هر اکانت با محدودیت‌های ضدبن در محدودیت‌ها و سهمیه‌ها زمان‌بندی می‌شوند، بنابراین یک رگبار ارسال صف می‌شود، نه اینکه یک‌جا شلیک شود.

یک مثال عملی

پاسخ به جدیدترین گفتگوی خوانده‌نشده و انتظار برای رسیدن ارسال:

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

مانیتورکردن یک گفتگو

سه جزء متحرک، به ترتیبی که راهشان می‌اندازید.

1. اگر تاریخچه را می‌خواهید، یک بار backfill کنید. POST /api/accounts/{id}/backfill-history یک ایمپورت یک‌باره از چت‌های موجود را صف می‌کند (اکانت‌های خودتان، بدون رسانه، تا 1000 پیام در هر چت؛ کانال‌های broadcast فقط وقتی شامل می‌شوند که از طریق POST /api/groups ردیابی شده باشند). GET /api/accounts/{id}/backfill-history را poll کنید تا state به done برسد — وضعیت‌ها queued، running، done، cancelled هستند، و idle یعنی هیچ job‌ای ثبت نشده (یا هرگز شروع نشده یا وضعیتش بعد از 6 ساعت منقضی شده). برای هر اکانت یک بار اجرایش کنید؛ روی داده‌ی پروکسی سنگین است و هر چه بعد از آن باشد خودش می‌رسد.

2. استریم زنده را بگیرید. یک وب‌هوک برای inbox.new_message ثبت کنید. برای اینکه پیام‌ها همچنان به اینباکس بریزند چیز دیگری لازم نیست — worker اکانت از قبل در حال شنیدن است.

3. همگام کنید. بعد از هر قطعی در سمت شما، هر گفتگو را با after_msg_id از آخرین شناسه‌ای که ذخیره کرده‌اید رو به جلو بگردید. این کار شکاف را بدون بازخوانی کل رشته می‌بندد.

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"