اعلان‌های امروز
—
از ساعت ۰۰:۰۰ به وقت UTC
YOUR NOTIFICATION CONTROL ROOM
نبض اعلان‌ها، در یک نگاه.
از رویدادهای سرویس‌ها تا تحویل به مشترکان، همه‌چیز اینجاست.
تحویل موفق
—
در بازهٔ نگهداری گزارش‌ها
مشترکان فعال
—
در حال دریافت اطلاعات
در انتظار تحویل
—
تعداد ارسال‌های باقی‌مانده
در صف
جریان تحویل اعلان‌ها
تعداد تحویل به مشترکان در هر روز
تحویل موفقناموفق
در حال دریافت نمودار
کیفیت تحویل
در بازهٔ نگهداری گزارش‌ها
—از نتایج قطعی تحویل
ناموفق—
نتیجهٔ نامشخص—
ردشده / لغوشده—
آخرین اعلان‌ها
آخرین رویدادهایی که وارد مسیر ارسال شده‌اند
در حال دریافت اعلان‌ها
EVENT LOG
مسیر هر اعلان، روشن است.
رویدادها را پیدا کنید و نتیجهٔ ارسال به هر مشترک را ببینید.
«نامشخص» یعنی پاسخ قطعی از تلگرام دریافت نشده است. برای جلوگیری از پیام تکراری، این ارسال به‌صورت خودکار تکرار نمی‌شود.
YOUR AUDIENCE
یک بات، یک تیم باخبر.
پروفایل، عضویت و دسترسی هر مشترک به اپلیکیشن‌های بات انتخاب‌شده.
کاربران با ارسال /start به بات عضو می‌شوند. ارسال /stop یا مسدود کردن بات، عضویت را غیرفعال می‌کند. کاربران با /apps در تلگرام اپلیکیشن‌های دلخواه را انتخاب می‌کنند؛ پیش‌فرض دریافت همه است. پس از رفع مسدودیت مدیریتی، کاربر باید دوباره /start بفرستد.باز
کردن بات
مشترکان بات
در حال دریافت اطلاعات
ریست کامل پروژه
همهٔ فضاها، بات‌ها، کلیدهای اپلیکیشن، مشترکان، صف‌ها، گزارش‌ها و تنظیمات پاک می‌شوند. کلید ورود حفظ می‌شود.
عملیات سراسری و غیرقابل بازگشت است.
PREFERENCES & SECURITY
به سبک سرویس‌های شما.
رفتار ارسال، دسترسی سرویس‌ها و تجربهٔ مشترکان را تنظیم کنید.
اتصال به تلگرام
توکن، وب‌هوک و تنظیمات این صفحه متعلق به بات انتخاب‌شده در بالای داشبورد است.
برای دریافت کلید ارسال، از بخش یک اپلیکیشن بسازید.
وب‌هوک عضویت کاربران
برای ثبت عضویت، وب‌هوک بات باید به این Worker متصل باشد.
منوی فرمان‌های بات
کاربران با زدن
/
در گفت‌وگوی خصوصی، همهٔ فرمان‌ها را از پیشنهادهای تلگرام انتخاب می‌کنند.
/startشروع و منوی اصلی/appsانتخاب اپلیکیشن‌ها/allدریافت همهٔ اعلان‌های مجاز/preferencesتنظیمات دریافت/timezoneمنطقهٔ زمانی/quietساعت‌های سکوت/stopتوقف اعلان‌ها
TENANT API GUIDE
اتصال سرویس‌ها به این فضا.
فضا را از بالای صفحه انتخاب کنید؛ آدرس‌ها و راهنما برای همان Tenant آماده می‌شوند.
SELECTED TENANT
یک فضا انتخاب کنید
هر فضا بات، اپلیکیشن‌ها و مخاطبان خودش را دارد.
- شناسهٔ Tenant در URL
—- وضعیت فضا
- —
کلید ارسال را از اپلیکیشن‌های همین فضا دریافت کنید.
اگر بات اپلیکیشن غیرفعال باشد، درخواست ارسال با HTTP 409 · BOT_DISABLED رد می‌شود. کلید اپلیکیشن، بات مقصد را تعیین می‌کند؛ نیازی به ارسال توکن بات یا شناسهٔ بات در درخواست نیست.
۱. ارسال اعلان
نمونهٔ آماده برای ترمینال یا CI/CD
POST
—ابتدا مقدار
YOUR_APPLICATION_API_KEY
را با کلید یکی از اپلیکیشن‌های همین فضا جایگزین کنید.
EVENT_ID
باید شناسهٔ یکتای رویداد شما باشد.
پیش از اولین درخواست
- ۱
بات مورد نظر را در همین Tenant متصل کنید
در «بات‌های تلگرام»، یک یا چند بات اضافه کنید. بات مورد نظر را انتخاب و وب‌هوک همان بات را ثبت کنید.
- ۲
اپلیکیشن و کلید ارسال بسازید
در «اپلیکیشن‌ها» سرویس خود را بسازید و کلیدش را در متغیر محرمانهٔ سرویس یا CI/CD ذخیره کنید. کلید فقط هنگام ساخت یا تعویض نمایش داده می‌شود.
- ۳
مخاطبان، بات را Start کنند
کاربر با /start عضو همان بات مقصد می‌شود. پیش‌فرض، دریافت همهٔ اپلیکیشن‌هاست؛ با /apps انتخاب می‌کند و با /all به دریافت همه برمی‌گردد.
مسیر URL فضا را مشخص می‌کند؛ کلید، اپلیکیشن فرستنده را. کلید یک Tenant برای Tenant دیگر معتبر نیست. از کلید اپلیکیشن استفاده کنید؛ کلید ورود داشبورد برای ارسال اعتبار ندارد.
هدرهای درخواست
کلید را در هدر بفرستید؛ نام اپلیکیشن از آن شناسایی می‌شود.
| هدر | مقدار | کاربرد |
|---|---|---|
X-API-Keyضروری |
APPLICATION_API_KEY |
کلید اپلیکیشن فعال متعلق به Tenant انتخاب‌شده. به‌جای این هدر می‌توانید Authorization: Bearer <APPLICATION_API_KEY> بفرستید؛ یکی کافی است. |
Content-Typeضروری برای ارسال |
application/json |
بدنهٔ ارسال اعلان باید JSON باشد. |
Idempotency-Key |
شناسهٔ یکتای رویداد | اختیاری؛ ۱ تا ۱۲۸ کاراکتر از حروف انگلیسی، عدد و _ . : - . برای تکرار همان درخواست، کلید و بدنه را ثابت نگه دارید؛ برای رویداد جدید کلید جدید بسازید. |
از هشدار تا رفع مشکل
یک شناسهٔ ثابت برای یک مشکل؛ یک پیام قابل پیگیری در تلگرام.
تجمیع را در «قوانین ارسال» فعال کنید. این دو بدنه را با همان کلید اپلیکیشن، به مسیر ارسال همین Tenant بفرستید. مقدار fingerprint در تکرارها و پیام رفع مشکل ثابت می‌ماند؛ برای هر رویداد تازه، Idempotency-Key تازه بسازید.
۱. ثبت یا تکرار مشکل
{
"event": "service.unavailable",
"text": "The API is unavailable.",
"level": "critical",
"environment": "production",
"fingerprint": "api:production:unavailable",
"incidentStatus": "firing"
}
۲. بستن همان رخداد
{
"event": "service.recovered",
"text": "The API has recovered.",
"level": "success",
"environment": "production",
"fingerprint": "api:production:unavailable",
"incidentStatus": "resolved"
}
تکرارها در بازهٔ تنظیم‌شده، شمارندهٔ همان رخداد را بالا می‌برند؛ resolved رخداد باز متناظر را می‌بندد. اتصال‌های Grafana و Alertmanager وضعیت رفع مشکل را خودکار نگاشت می‌کنند.
۲. پیگیری تحویل
با همان کلید اپلیکیشن ارسال‌کننده
GET
—مقدار
NOTIFICATION_ID
را از فیلد
notification.id
پاسخ ارسال بردارید. هر اپلیکیشن فقط گزارش اعلان‌های خودش را می‌بیند.
پاسخ را چطور بخوانیم؟
بخشی از یک پاسخ نمونه با مخاطبان واجد شرایط
{
"notification": {
"id": "...",
"status": "queued",
"total": 12,
"sent": 0
},
"duplicate": false
}
- 202 یعنی اعلان ثبت شده و تحویل در پس‌زمینه انجام می‌شود. وضعیت و شمارنده‌های ارسال را از API پیگیری یا «تاریخچهٔ اعلان‌ها» ببینید.
- 200 همراه duplicate: true یعنی این درخواست قبلاً ثبت شده؛ اعلان جدیدی ساخته نشده است.
- status: empty و total: 0 یعنی مخاطب واجد شرایط وجود ندارد. عضویت در بات، انتخاب اپلیکیشن و مسدود نبودن کاربر را بررسی کنید.
- مشترکان Tenantهای دیگر و کاربران مسدودشده، این اعلان را دریافت نمی‌کنند.
اعلان در تلگرام چگونه نمایش داده می‌شود؟
عنوان و متن فارسی، اطلاعات فنی در بلوک‌های منظم با قلم ثابت.
- عنوان درشت همراه نشان سطح هشدار و متن اصلی، بخش خوانای پیام را می‌سازند. تصویر اختیاری هم داخل همین پیام اعلان قرار می‌گیرد.
- بلوک CONTEXT نام اپلیکیشن، نوع رویداد، محیط اجرا و سطح هشدار را با قلم ثابت نمایش می‌دهد. کشور مبدأ و پرچم آن، مطابق تنظیمات فضا به همین بخش اضافه می‌شوند.
- بلوک TIME شامل تاریخ عددی شمسی و میلادی در دو خط جدا، یک ساعت مشترک و منطقهٔ زمانی Asia/Tehran است. تاریخ‌ها و ساعت با ارقام انگلیسی نمایش داده می‌شوند.
- اطلاعات تکمیلی و برچسب‌ها، در صورت وجود، در بلوک‌های METADATA و TAGS نمایش داده می‌شوند. بخش‌های گزارش همیشه باز هستند؛ برچسب‌های کوتاه انگلیسی هم‌راستا و مقادیر طولانی یا فارسی زیر کلیدشان، به‌صورت کامل قرار می‌گیرند.
- فیلد url یک دکمهٔ اصلی برای مشاهدهٔ جزئیات می‌سازد. دکمه‌های کپی رویداد و کپی شناسه، مقدار کامل نوع رویداد و شناسهٔ اعلان را برای پیگیری با API یا تاریخچه کپی می‌کنند.
محتوای HTML، در همان گزارش همیشگی
برای متن اعلان، parseMode: "HTML" بفرستید؛ بخش‌های فنی و دکمه‌ها حفظ می‌شوند.
نمونهٔ بالای این صفحه را روی «HTML قالب‌بندی‌شده» بگذارید تا درخواست آماده با آدرس همین Tenant ساخته شود. HTML فقط برای بدنهٔ پیام تفسیر می‌شود؛ عنوان و داده‌های دیگر متن ساده می‌مانند.
قالب‌های مجاز: b / strong · i / em · u / ins · s /
strike / del · code · mark · sub / sup · tg-spoiler · a و بلوک‌های p
· br · h1–h6 · pre · ul / ol / li · blockquote · footer · hr · details / summary.
برای اسپویلر، span class="tg-spoiler" هم مجاز است. فهرست مرتب start،
نقل‌قول expandable و بخش بازشونده open می‌پذیرند. در
pre می‌توانید code class="language-X" بگذارید.
تگ‌ها باید درست بسته شوند؛ حداکثر ۱۲ لایه و ۲۰۰ بلوک یا آیتم فهرست مجاز است. اسکریپت، CSS، جدول و ویژگی‌های دیگر پشتیبانی نمی‌شوند. لینک‌های HTTP(S) ، mailto: ، tel: و tg://user?id=… مجازند؛ اطلاعات ورود داخل لینک پذیرفته نمی‌شود.
برای عکس و دکمهٔ جزئیات از فیلدهای image و url استفاده کنید.
تاریخچهٔ داشبورد متن خوانا و منبع HTML را جداگانه نمایش می‌دهد. در خلاصه‌های دوره‌ای، فقط
چکیدهٔ متن ساده تا ۳۰۰ کاراکتر نمایش داده می‌شود. مستندات قالب‌بندی تلگرام ↗
بدنهٔ درخواست
فقط event و text ضروری‌اند؛ نام و شناسهٔ اپلیکیشن را در بدنه نفرستید.
| فیلد | نوع | توضیح |
|---|---|---|
eventضروری |
string | نوع رویداد مانند deployment.completed ؛ حداکثر ۸۰ کاراکتر. |
textضروری |
string | بدنهٔ اعلان؛ پیش‌فرض متن ساده با سقف ۳۰۰۰ کاراکتر. در حالت HTML، سقف منبع ۱۲۰۰۰ و متن پس از تبدیل ۳۰۰۰ کاراکتر است. |
parseMode |
HTML |
اختیاری؛ فقط فیلد text را با تگ‌های مجاز قالب‌بندی می‌کند. برای متن ساده، این فیلد را حذف کنید. Markdown پشتیبانی نمی‌شود. |
level |
enum | info · success · warning · error · critical ؛ پیش‌فرض info . |
timestamp |
ISO 8601 | زمان رویداد همراه منطقهٔ زمانی؛ در صورت حذف، زمان ثبت درخواست. در بلوک TIME ، تاریخ عددی شمسی و میلادی با ارقام انگلیسی و یک ساعت مشترک بر مبنای تهران نمایش داده می‌شوند. |
title / environment |
string | عنوان تا ۱۶۰ و محیط اجرا تا ۸۰ کاراکتر؛ مانند production . |
image |
string | آدرس عمومی HTTPS تصویر یا file_id تلگرام متعلق به همین بات. تصویر را در JSON بفرستید؛ داخل همان پیام اعلان نمایش داده می‌شود. |
url |
HTTPS URL | لینک دکمهٔ اصلیِ مشاهدهٔ جزئیات؛ حداکثر ۲۰۴۸ کاراکتر. |
metadata / tags |
object / string[] | تا ۲۰ جفت کلید–مقدار ساده و ۱۰ برچسب؛ کلید و برچسب تا ۴۰، مقدار تا ۵۰۰ کاراکتر. اطلاعات تکمیلی و برچسب‌ها در بلوک‌های جداگانهٔ METADATA و TAGS ، با قلم ثابت و مقادیر کامل نمایش داده می‌شوند. |
fingerprint |
string | شناسهٔ ثابت مشکل، حداکثر ۱۶۰ کاراکتر. در تکرارها و رخداد رفع مشکل همان مقدار را بفرستید؛ گروه‌بندی برای هر اپلیکیشن مستقل است. |
incidentStatus |
enum | firing برای رخداد فعال و resolved برای رفع مشکل. بدون این فیلد، پیام به‌عنوان رخداد فعال بررسی می‌شود. |
silent |
boolean | ارسال بی‌صدا در تلگرام. |
مجموع متن قالب‌بندی‌شدهٔ پیام باید حداکثر ۴۰۰۰ کاراکتر باشد. برای ارسال
تصویر و لینک، فیلدهای اختیاری
image
و
url
را به همین نمونه اضافه کنید.
محدودیت‌ها و رفع خطا
سقف‌های همین Tenant، مشترک میان اپلیکیشن‌های آن است.
| HTTP | معنی | اقدام بعدی |
|---|---|---|
400 / 413 |
بدنه یا اندازهٔ نامعتبر | نام و مقدار فیلدها و سقف اندازهٔ پیام را بررسی کنید. INVALID_HTML یعنی تگ، ویژگی یا ساختار HTML مجاز نیست؛ درخواست پیش از ورود به صف رد می‌شود. |
401 |
کلید ارسال نامعتبر | کلید اپلیکیشن فعالِ همین Tenant و هدر احراز هویت را بررسی کنید. |
403 |
دسترسی مجاز نیست | فعال بودن Tenant و قوانین IP و کشور آن را بررسی کنید. |
404 |
فضا یا اعلان پیدا نشد | شناسهٔ Tenant و اعلان را بررسی کنید. پیگیری اعلان به کلید همان اپلیکیشن نیاز دارد. |
409 |
رویداد تکراری با بدنهٔ متفاوت | در تلاش مجدد، همان بدنه و Idempotency-Key را بفرستید؛ رویداد جدید به کلید جدید نیاز دارد. |
429 |
سهمیه یا ظرفیت صف پر شده | اگر Retry-After وجود دارد، رعایت کنید؛ در غیر این صورت سهمیهٔ روزانه و ظرفیت صف را بررسی کنید. پیگیری وضعیت هم از سهمیهٔ درخواست استفاده می‌کند. |
503 |
سرویس آماده نیست | اتصال بات همین Tenant و تنظیمات سرویس را بررسی کنید. |
قوانین IP و کشور در «تنظیمات» همین فضا اعمال می‌شوند. تشخیص درخواست
تکراری برای هر اپلیکیشن مستقل است و تا زمان نگهداری رکورد اعلان اعتبار دارد. برای استفاده از این
کلیدها، درخواست را از سرور یا CI/CD خود بفرستید.
ONE APPLICATION. ONE API KEY.
کلید هر سرویس، مستقل.
اپلیکیشن‌های فضای انتخاب‌شده را مدیریت کنید؛ هرکدام کلید و هویت ارسال خودش را دارد.
نام اپلیکیشن در پیام از کلید آن شناسایی می‌شود. کلید اپلیکیشن تنها اجازهٔ ارسال دارد و برای ورود به مدیریت معتبر نیست.
اپلیکیشن‌های این بات
در حال دریافت اطلاعات
ONE SPACE. MANY CONNECTIONS.
هر بات، یک مسیر مستقل.
بات‌های تیم را کنار هم مدیریت کنید؛ هرکدام با اپلیکیشن‌ها، مخاطبان و گزارش‌های خودش.
۰۱اتصال مستقلتوکن و وب‌هوک مخصوص هر بات
۰۲مخاطبان جداگانهانتخابها و دسترسیها در همان بات
۰۳توقف با یک کلیدتوقف ارسال همهٔ اپلیکیشن‌های بات
ISOLATED NOTIFICATION SPACES
هر سرویس، فضای خودش.
بات‌ها، اپلیکیشن‌ها، مشترکان، گزارش‌ها و سهمیهٔ هر فضا مستقل هستند.
کلید مدیریت برای کنترل همهٔ فضاهاست. هر اپلیکیشن در هر فضا کلید ارسال مستقل دارد؛ برای سرویس‌ها از همان کلید استفاده کنید.
فضاهای اعلان
در حال دریافت فضاها
غیرفعال کردن فضا، دریافت و ارسال اعلان‌های آن را متوقف می‌کند. داده‌های قبلی باقی می‌مانند و پس از فعال‌سازی دوباره قابل استفادهاند.
LESS NOISE. MORE CONTEXT.
یک رخداد، یک مسیر رسیدگی.
تکرارها را یکجا ببینید، مسئول رسیدگی را بشناسید و تا رفع مشکل همراه هشدار بمانید.
THE RIGHT SIGNAL. THE RIGHT MOMENT.
هر پیام، به‌وقت خودش.
هشدارهای تکراری را جمع کنید، مسئول بعدی را مشخص کنید و برای پیام‌های کم‌اهمیت، زمان مناسبی بسازید.
پیش‌فرض بات
اپلیکیشن‌ها می‌توانند قوانین اختصاصی داشته باشند.
DASHBOARD ACCESS LOG
تلاش‌های ورود، قابل پیگیری.
ورودهای ناموفق به داشبورد، از همهٔ مبدأها و مستقل از فضای انتخاب‌شده.
کلید واردشده در این گزارش ذخیره نمی‌شود. اطلاعات مرورگر توسط درخواستکننده ارسال شده و هویت تأییدشدهٔ فرد نیست.
تلاش‌های ناموفق
در حال دریافت گزارش