راهنمای پیامک و تماس سفارشی

این چیست و کِی لازم است؟

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

• پرداخت ناموفق یا سفارش مهم ثبت شد → پیام بله به مدیر فروش.
• دیتابیس پر شد → تماس صوتی به مسئول فنی.
• بکاپ شبانه شکست خورد → پیامک.
• deploy تمام شد → پیام تلگرام به تیم.

اگر پیام باید طبق مراحل و زمان‌بندی سیاست بروید یا بازیابی داشته باشد، وب‌هوک خطا مناسب‌تر است (راهنما).

راه‌اندازی در ۴ قدم

1. مخاطب بسازید. «مخاطبین» ← افزودن مخاطب: نوع «پیامک»، «تماس صوتی»، «بله» یا «تلگرام». برای بله و تلگرام ابتدا باید با دکمه‌ی «اتصال به @ربات» متصل شود (وضعیت «متصل ✓»).
2. کلید بسازید. «کلیدهای فراخوانی» ← «ساخت کلید فراخوانی»: یک نام، مخاطب و متن پیام پیش‌فرض را بدهید. (ساخت کلید فقط برای مالک و ادمین حساب ممکن است.)
3. کلید را ذخیره کنید. کلید کامل (که با trg_ شروع می‌شود) فقط همین یک‌بار نمایش داده می‌شود. همان لحظه در جای امن (مثلاً متغیر محیطی یا secret manager) بگذارید.
4. امتحان کنید. «ارسال آزمایشی» را بزنید و در «آخرین ارسال‌ها» نتیجه را ببینید؛ بعد از سیستم خودتان صدا بزنید.

کدام کانال؟

• مهم و فوری و می‌خواهید حتماً توجه جلب شود: تماس صوتی.
• مهم و می‌خواهید روی هر گوشی برسد: پیامک.
• اطلاع‌رسانی عادی و حجم بالا: بله (یا تلگرام).

پیامک

پیامک در ایران فقط با «قالب» (template) تأییدشده‌ی اپراتور ارسال می‌شود. یعنی بخش ثابت پیام از قبل ثبت شده و متن کوتاه شما جای یک متغیر داخل آن می‌نشیند. برای همین:

• متن پیامک حداکثر ۱۰۰ نویسه است.
• فاصله‌ها و زیرخط به «-» تبدیل می‌شوند. «سرور اصلی قطع شد» به «سرور-اصلی-قطع-شد» می‌رسد. پس از ابتدا کوتاه و با خط‌تیره بنویسید: db-prod-پر-شد.
• لینک و متن طولانی ننویسید؛ اپراتور ممکن است پیام را رد کند.
• متن نهایی چیزی شبیه این است: «هشدار: سرویس سرور-اصلی-قطع-شد نیازمند بررسی است. استتلی». بخش ثابت، قالب تأییدشده‌ی اپراتور است و قابل تغییر نیست.

تماس صوتی

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

• کوتاه و ساده، با جمله‌ی کامل: «سرور اصلی قطع شد. لطفاً فوراً بررسی کنید.»
• عدد و واژه‌ی لاتین (مثل API) را ماشین گاهی بد تلفظ می‌کند؛ فارسی بنویسید («ای‌پی‌آی»).
• نشانه‌ها، لینک و ایموجی در تماس معنا ندارند.
• تماس هر کلید حداکثر ۳ بار در دقیقه است؛ تماس مجدد پشت سر هم برای یک مشکل بی‌فایده است.

بله و تلگرام

• مخاطب باید «متصل ✓» باشد؛ بدون اتصال، کلید ساخته نمی‌شود (پیام «این مخاطب هنوز متصل/تأیید نشده است»).
• اگر کاربر ربات را بلاک کرد یا چت را حذف کرد، ارسال با خطای «ربات اجازه‌ی ارسال به این چت را ندارد» یا «چت پیدا نشد» ثبت می‌شود (در «آخرین ارسال‌ها»).
• تا ۱۰۰۰ نویسه متن آزاد و فارسی، بدون هزینه.
• تلگرام در ایران فیلتر است؛ ارسال به آن فقط وقتی کار می‌کند که پروکسی روی سرور تنظیم شده باشد. اگر ارسال تلگرام ناموفق است، فعلاً از بله استفاده کنید.

فراخوانی کلید

آدرس همیشه به این شکل است و بدنه اختیاری است. اگر message بدهید، متن پیش‌فرض کلید را برای همین یک بار عوض می‌کند (با رعایت حداکثر طول هر کانال):

POST https://statly.ir/api-backend/trigger/<KEY>
Content-Type: application/json

{"message": "متن دلخواه (اختیاری)"}

# با متن پیش‌فرض کلید
curl -X POST https://statly.ir/api-backend/trigger/<KEY>

# با متن دلخواه
curl -X POST https://statly.ir/api-backend/trigger/<KEY> \
  -H "Content-Type: application/json" \
  -d '{"message":"دیتابیس پر شد"}'

نشانی بالا برای سرویس میزبانی‌شده‌ی ماست. اگر سامانه را خودتان نصب کرده‌اید، آدرس پایه‌ی سرور خودتان را بگذارید؛ آدرس دقیق هر کلید هم در صفحه‌ی «کلیدهای فراخوانی» نوشته شده است.

پاسخ‌ها و خطاها

به‌خاطر اینکه ارسال در پس‌زمینه انجام می‌شود، پاسخ 202 یعنی «پذیرفته شد»، نه «تحویل داده شد». دلیل شکست‌های واقعی را فقط در «آخرین ارسال‌ها» می‌بینید؛ مثلاً: قالب پیامک تنظیم نشده، شماره نامعتبر، ربات بلاک شده یا ارسال موقتاً متوقف است.

محدودیت‌ها

امنیت کلید

• کلید مثل رمز عبور است: هر کسی آن را داشته باشد می‌تواند پیامک/تماس با هزینه‌ی شما بفرستد (البته فقط به همان یک مخاطب).
• فقط از سمت سرور صدا بزنید. هرگز کلید را داخل کد فرانت‌اند، اپ موبایل یا مخزن کد عمومی نگذارید.
• ما فقط hash کلید را نگه می‌داریم؛ اگر گمش کنید قابل بازیابی نیست — «چرخش کلید» بزنید و کلید جدید را در سیستم‌تان بگذارید. کلید قبلی همان لحظه از کار می‌افتد.
• مشکوک شدید؟ «غیرفعال‌کردن» را بزنید (قابل برگشت) یا کلید را حذف کنید.
• هر ساخت، چرخش، غیرفعال‌سازی و حذف در «تاریخچه» ثبت می‌شود.

نمونه‌های کاربردی

اسکریپت cron: اگر بکاپ شکست خورد، تماس بگیر

#!/bin/bash
# /opt/backup.sh
if ! /usr/local/bin/do-backup; then
  curl -fsS -m 10 -X POST "https://statly.ir/api-backend/trigger/$STATLY_CALL_KEY" \
    -H "Content-Type: application/json" \
    -d '{"message":"بکاپ شبانه شکست خورد. لطفاً بررسی کنید."}'
fi

GitHub Actions / CI: بعد از deploy پیام بله

- name: Notify on Bale
  if: always()
  run: |
    curl -fsS -m 10 -X POST "https://statly.ir/api-backend/trigger/${{ secrets.STATLY_BALE_KEY }}" \
      -H "Content-Type: application/json" \
      -d "{\"message\":\"deploy ${{ job.status }}: ${{ github.repository }}\"}"

ابزارهای دیگر (Grafana، Zabbix، Nagios و…)

هر ابزاری که بتواند یک درخواست POST بفرستد کافی است. فیلدهای اضافه‌ی بدنه نادیده گرفته می‌شوند و فقط message خوانده می‌شود؛ اگر ابزار شما بدنه‌ی دلخواه نمی‌تواند بسازد، کلید را با متن پیش‌فرض مناسب بسازید و بدون بدنه صدا بزنید.

پرسش‌های پرتکرار

پاسخ ۲۰۲ گرفتم ولی پیام نرسید.

«آخرین ارسال‌ها»ی کلید را ببینید. «ناموفق» با دلیلش نوشته می‌شود. دلایل رایج: ربات بلاک شده یا مخاطب متصل نیست؛ شماره اشتباه است؛ برای پیامک قالب تنظیم نشده؛ تلگرام بدون پروکسی.

می‌توانم از یک کلید برای چند نفر استفاده کنم؟

نه. هر کلید یک مخاطب دارد. برای چند نفر چند مخاطب و چند کلید بسازید (یا چند فراخوانی پشت هم از کد خود).

مخاطب را حذف کنم چه می‌شود؟

کلیدهای آن مخاطب هم همراهش حذف می‌شوند و فراخوانی‌شان ۴۰۴ می‌دهد.

فرق «ارسال آزمایشی» با فراخوانی واقعی چیست؟

هیچ؛ همان مسیر و همان محدودیت‌ها (و هزینه) را دارد. فقط از داخل پنل و با دکمه است. کلید باید «فعال» باشد.

اگر چند ارسال لازم داشتم چه‌طور؟

به سقف‌ها دقت کنید (جدول بالا). برای حجم زیاد اطلاع‌رسانی عادی، بله مناسب‌تر است؛ پیامک و تماس را برای مواردی نگه دارید که واقعاً باید توجه جلب شود.