# هشدارها و کانال‌های اعلان

> https://docs.errora.org/products/alerts

هشدار از دو چیز ساخته می‌شود: یک **کانال** (پیام کجا برود) و یک **قاعدهٔ هشدار** (کدام رویداد
پیام بفرستد). هر دو در **تنظیمات ← وب‌هوک‌ها** هستند.

## رویدادهایی که می‌توانید مشترکشان شوید

| رویداد | چه وقت فعال می‌شود |
| --- | --- |
| `issue.created` | نوع تازه‌ای از استثنا برای اولین بار دیده می‌شود |
| `event.received` | هر رویداد خطا می‌رسد (پرسروصداست — محدودش کنید) |
| `issue.regressed` | خطای حل‌شده دوباره برمی‌گردد |
| `autofix.started` | یک اجرای [رفع خودکار](/products/ai-autofix) شروع می‌شود |
| `autofix.mr_created` | رفع خودکار مرج‌ریکوئست باز کرد |
| `autofix.failed` | رفع خودکار شکست خورد |
| `monitor.failed` | یک [مانیتور کران](/products/crons) خراب است |
| `monitor.recovered` | مانیتور کران دوباره سالم شد |
| `uptime.down` | یک [مانیتور آپ‌تایم](/products/uptime) قطع شد |
| `uptime.up` | مانیتور آپ‌تایم دوباره وصل شد |
| `feedback.received` | [بازخورد کاربر](/products/user-feedback) تازه‌ای رسید |
| `wallet.balance_low` | موجودی [کیف پول](/billing/wallet) از آستانه‌ای که گذاشته‌اید پایین‌تر رفت |

## نوع کانال‌ها

| نوع | چه چیزی لازم دارد |
| --- | --- |
| `webhook` | یک آدرس. ارورا قالب رندرشده را در بدنه `POST` می‌کند. |
| `mattermost` | آدرس وب‌هوک ورودی |
| `telegram` | یک چت متصل (پایین‌تر) — **هیچ توکن رباتی لازم نیست** |
| `bale` | یک چت متصل (پایین‌تر) |
| `email` | یک نشانی ایمیل |
| `sms` | یک شمارهٔ موبایل |

### تلگرام و بله — اتصال چت

ارورا ربات‌های خودش را دارد، پس شما هیچ‌وقت توکن ربات نمی‌سازید و جایی نمی‌چسبانید:

1. **تنظیمات ← وب‌هوک‌ها ← اتصال چت تلگرام/بله.** ارورا یک پیوند کوتاه‌عمر می‌دهد.
2. پیوند را باز کنید و **Start** را بزنید. حالا آن چت به سازمان شما وصل است.
3. کانالی از همان نوع بسازید و چت متصل را انتخاب کنید.

چت‌ها به تفکیک سازمان وصل می‌شوند: هر کانال فقط می‌تواند به چتی پیام بدهد که از همان سازمان
متصل شده باشد.

## قالب‌ها

هر کانال یک قالب اختیاری با نشانه‌های `{{ placeholder }}` می‌گیرد. نشانه‌های ناشناخته به رشتهٔ
خالی تبدیل می‌شوند.

نشانه‌های در دسترس: `{{ event }}`، `{{ title }}`، `{{ body }}`، `{{ url }}`،
`{{ level }}`، `{{ issue_id }}`.

پیش‌فرض هر نوع کانال:

```text
webhook      {"event": "{{ event }}", "title": "{{ title }}", "body": "{{ body }}",
              "url": "{{ url }}", "level": "{{ level }}", "issue_id": "{{ issue_id }}"}
mattermost   **{{ title }}**\n{{ body }}\n[View in Errora]({{ url }})
telegram     {{ title }}\n{{ body }}\n{{ url }}
bale         {{ title }}\n{{ body }}\n{{ url }}
email        {{ body }}\n\n{{ url }}
sms          Errora: {{ title }}
```

دو چیز ویرایش قالب را بی‌خطر می‌کند:

- **پیش‌نمایش زنده** قالب شما را دقیقاً همان‌طور رندر می‌کند که یک اعلان واقعی رندر می‌شود.
- **ارسال آزمایشی** همین حالا یک اعلان نمونه می‌فرستد و پاسخ خود ارائه‌دهنده را نشان می‌دهد، پس
  آدرس وب‌هوک اشتباه یا چت قطع‌شده به‌جای سکوت، با صدای بلند شکست می‌خورد.

## قواعد هشدار

هر قاعده یک **نوع رویداد** را به یک **کانال** وصل می‌کند و در صورت نیاز به یک پروژه محدود
می‌شود. برای هر جفت (رویداد، کانال) که می‌خواهید یک قاعده بسازید.

```bash
# ۱. ساخت کانال
curl -X POST "$ERRORA/api/v1/organizations/$ORG_ID/channels" \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Ops webhook","type":"webhook","config":{"url":"https://ops.example.com/hooks/errora"}}'

# ۲. وصل‌کردن یک رویداد به آن
curl -X POST "$ERRORA/api/v1/organizations/$ORG_ID/alert-rules" \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"event_type":"issue.created","channel":"<channel_id>","project":"<project_id>","is_active":true}'
```

مدیریت کانال‌ها و قواعد به توانمندی **`webhook:manage`** نیاز دارد.

## هشدار کیف پول

هشدارهای موجودی به‌جای اینجا در صفحهٔ صورتحساب تنظیم می‌شوند: یک کانال و یک آستانه انتخاب
می‌کنید و با عبور موجودی از آن، `wallet.balance_low` فعال می‌شود. نگاه کنید به
[کیف پول](/billing/wallet).

## کم‌کردن نویز

- `issue.created` را به `event.received` ترجیح بدهید. دومی برای *هر* رویداد فعال می‌شود.
- قواعد را به پروژه محدود کنید؛ چتی که نویز staging هم می‌گیرد، توسط اعضایش بی‌صدا می‌شود.
- از **آستانه‌های** کران و آپ‌تایم استفاده کنید تا یک لغزش کسی را بیدار نکند.
- رویدادهای کم‌اهمیت را به وب‌هوک یا Mattermost بفرستید و پیامک را برای چیزی نگه دارید که
  باید کسی را از خواب بیدار کند.

## API

```text
GET/POST     /api/v1/organizations/{org_id}/channels
PATCH/DELETE /api/v1/organizations/{org_id}/channels/{id}
GET          /api/v1/organizations/{org_id}/channels/template-meta
POST         /api/v1/organizations/{org_id}/channels/preview
POST         /api/v1/organizations/{org_id}/channels/{id}/test
GET/POST     /api/v1/organizations/{org_id}/alert-rules
PATCH/DELETE /api/v1/organizations/{org_id}/alert-rules/{id}
POST         /api/v1/organizations/{org_id}/chat-links/start
```

## عیب‌یابی

| نشانه | علت / راه‌حل |
| --- | --- |
| ارسال آزمایشی شکست می‌خورد | متن خطا پاسخ خود ارائه‌دهنده است — بخوانیدش؛ معمولاً آدرس اشتباه، توکن باطل یا چت متصل‌نشده |
| چیزی نمی‌رسد ولی ارسال آزمایشی کار می‌کند | برای آن نوع رویداد قاعده‌ای نیست، قاعده غیرفعال است یا به پروژهٔ دیگری محدود شده |
| چت تلگرام/بله در فهرست نیست | پیوند منقضی شده یا **Start** زده نشده — پیوند تازه بگیرید |
| ایمیل نمی‌رسد | نشانی و پوشهٔ اسپم را بررسی کنید |
| پیامک نمی‌رسد | بررسی کنید شماره یک موبایل معتبر ایران باشد |
| پیام‌ها خیلی زیادند | مشترک `event.received` شده‌اید؛ به `issue.created` تغییر دهید |