ارسال پیامک
ارسال یک متن به یک یا چند گیرنده، یا به گروه‌های دفترچه تلفن.
POST
scope: sms.send/sms/sendمتن را به شماره‌های گیرنده ارسال می‌کند. شماره‌ها به‌صورت خودکار نرمال‌سازی و تکراری‌ها حذف می‌شوند؛ اگر حتی یک شماره نامعتبر باشد کل درخواست رد می‌شود و هزینه‌ای کسر نمی‌شود. هزینه پیش از ارسال رزرو و پس از ارسال قطعی می‌شود؛ پیام‌های ناموفق به‌طور خودکار بازگردانده می‌شوند. برای تست بدون هزینه از کلید آزمایشی و lineId: "sandbox" استفاده کنید.
پارامترها
| نام | محل | نوع | توضیح |
|---|---|---|---|
| lineId * | بدنه | string | شناسه خط فرستنده (از GET /sms/lines). برای کلید آزمایشی مقدار sandbox. |
| to | بدنه | string | string[] | شماره(های) گیرنده؛ فرمت‌های 09121234567، +989121234567 و ارقام فارسی پذیرفته می‌شود. حداکثر ۱۰٬۰۰۰ شماره. |
| groupIds | بدنه | string[] | شناسه گروه‌های دفترچه تلفن؛ مخاطبین لغو عضویت‌شده حذف می‌شوند. حداقل یکی از to یا groupIds الزامی است. |
| text * | بدنه | string | متن پیام (حداکثر ۱۰۰۰ نویسه). فارسی: ۷۰ نویسه در پیام تک‌بخشی و ۶۷ نویسه در هر بخش پیام چندبخشی. |
| scheduledAt | بدنه | string (ISO 8601) | زمان ارسال در آینده (حداقل ۱ دقیقه و حداکثر ۶۰ روز بعد). هزینه همان لحظه رزرو می‌شود و پیام در زمان مقرر ارسال می‌گردد؛ تا پیش از آن با POST /sms/batches/{batchId}/cancel قابل لغو است. فهرست: GET /sms/scheduled. |
| gradual | بدنه | { chunkSize, intervalMinutes } | ارسال تدریجی: در هر intervalMinutes دقیقه (۱ تا ۱۴۴۰)، chunkSize پیام (۱ تا ۱۰٬۰۰۰) آزاد می‌شود. هزینهٔ کل از ابتدا رزرو می‌شود؛ توقف/ادامه/لغو: POST /sms/batches/{batchId}/pause|resume|cancel (لغو، فقط باقی‌مانده را بازمی‌گرداند). با scheduledAt قابل ترکیب است. |
| Idempotency-Key | هدر | string | کلید یکتا (حداکثر ۱۰۰ نویسه). ارسال دوباره با همان کلید، پیام تکراری نمی‌سازد و نتیجه قبلی را برمی‌گرداند. |
خطاهای خاص این endpoint
| 400 | invalid_recipients | یک یا چند شماره نامعتبر است (فهرست در details). |
| 402 | insufficient_balance | اعتبار کافی نیست. |
| 403 | احراز هویت حساب تکمیل نشده، یا کلید فاقد دسترسی sms.send است. | |
| 404 | خط وجود ندارد یا در دسترس شما نیست. | |
| 422 | no_price | برای این سرویس تعرفه‌ای تعریف نشده است. |
اجرای زنده (محیط تست)
با یک کلید آزمایشی (در پنل ← وب‌سرویس ← «کلید آزمایشی») این درخواست را همین‌جا اجرا کنید. پیام واقعی ارسال نمی‌شود و هزینه‌ای کسر نمی‌شود.