ارسال گروهی پیامک با یک متن مشترک

یک متن واحد را با یک سرشماره مشخص، به فهرستی از گیرندگان ارسال می‌کند. حداکثر ۱۰٬۰۰۰ گیرنده در هر فراخوانی مجاز است؛ شماره‌ها به قالب 09xxxxxxxxx نرمال‌سازی می‌شوند، شماره‌های نامعتبر و تکراری از ارسال کنار گذاشته می‌شوند ولی در پاسخ با وضعیت ۰ (دریافت کننده نامعتبر) و ۱۵ (شماره تکراری) برگردانده می‌شوند و اگر هیچ شماره معتبری باقی نماند خطای ۴۱۱ برمی‌گردد. سرشماره باید متعلق به حساب شما و دارای مجوز can_send_api_campaign باشد، و پیش از ارسال، اعتبار حساب برای کل هزینه بررسی می‌شود. برای خطوط پیامکی، عبارت انصراف «لغو۱۱» به‌صورت خودکار به انتهای متن افزوده (یا در صورت وجود، یکسان‌سازی) می‌شود؛ این کار برای خطوط پیام‌رسان‌ها (مانند بله و روبیکا) انجام نمی‌شود.

احراز هویت

نوع احراز هویتتوکن BearerbearerAuth

کلید API را در هدر Authorization با پیشوند Bearer بفرستید:

``` Authorization: Bearer YOURAPIKEY ```

این روش برای سرویس‌های نسخهٔ ۲، نسخهٔ ۳ و بارگذاری فایل به کار می‌رود. سرویس‌های نسخهٔ ۱ کلید را از مسیر URL می‌گیرند و هدری نمی‌خواهند.

هدر لازم

Authorization: Bearer YOUR_ACCESS_TOKEN

کلید خود را کجا پیدا کنم؟

اطلاعات ورود را از پنل کاربری خود بگیرید و توکن را فقط روی سرور و در یک متغیر محیطی نگه دارید؛ هرگز آن را در کد سمت کاربر قرار ندهید.

بدنهٔ درخواست

application/jsonالزامی

بدنه JSON درخواست ارسال گروهی. با `ctx.ShouldBindJSON` خوانده و اعتبارسنجی می‌شود؛ هر خطای پارس یا اعتبارسنجی به خطای ۴۰۰ منجر می‌شود.

نام	نوع	الزامی	توضیح
`message`*	string	الزامی	متن پیامک. برای خطوط پیامکی، عبارت «\nلغو۱۱» به‌صورت خودکار به انتهای متن اضافه می‌شود و اگر متن از قبل الگویی مانند «لغو ۱۱» یا `laghv11` داشته باشد با همین عبارت استاندارد جایگزین می‌گردد. مقدار برگشتی در پاسخ، متنِ نهاییِ پس از این تغییر است. محدودیت: حداقل ۱ کاراکتر؛ در کد سرویس هیچ سقف صریحی برای طول متن بررسی نمی‌شود (هزینه بر اساس تعداد صفحات محاسبه می‌شود) نمونه`سلام، سفارش شما ثبت شد.`
`sender`*	string	الزامی	سرشماره ارسال. اگر خط متعلق به حساب شما نباشد یا مجوز ارسال کمپین API نداشته باشد، خطای ۴۱۲ برمی‌گردد. محدودیت: باید دقیقاً برابر شماره یکی از خطوط حساب کاربر و دارای مجوز cansendapi_campaign باشد نمونه`3000505`
`receivers`*	array<string>	الزامی	فهرست شماره گیرندگان. قالب‌های `09xxxxxxxxx`، `9xxxxxxxxx`، `989xxxxxxxxx` و `+989xxxxxxxxx` پذیرفته و همگی به `09xxxxxxxxx` تبدیل می‌شوند. بیش از ۱۰٬۰۰۰ عضو خطای ۴۱۴ می‌دهد. محدودیت: حداقل ۱ و حداکثر ۱۰٬۰۰۰ عضو؛ هر شماره باید با الگوی ^((\+?98)\|0)?9[0-9]{9}$ مطابقت داشته باشد
`file_id`	string	اختیاری	شناسه فایل بازگشتی از `POST /upload-file/bale` (یک UUID). فایل باید متعلق به همان حساب باشد و ارائه‌دهنده فایل با ارائه‌دهنده سرشماره یکی باشد، وگرنه خطای ۴۰۰ برمی‌گردد. فقط برای ارائه‌دهنده‌های بله و روبیکا در ارسال استفاده می‌شود. محدودیت: حداکثر ۱۰۰ کاراکتر نمونه`3f2b7c1e-9a4d-4f1c-8b77-2c0f9e6a5d31`می‌تواند null باشد

نمونهٔ درخواست

{
  "message": "سلام، سفارش شما ثبت شد.",
  "sender": "3000505",
  "receivers": [
    "09121234567",
    "09351234567",
    "+989121112233"
  ],
  "file_id": "3f2b7c1e-9a4d-4f1c-8b77-2c0f9e6a5d31"
}

پاسخ‌ها

ساختار پاسخ

نام	نوع	الزامی	توضیح
`return`	ApiStatus	اختیاری	وضعیت پاسخ. مقدار `status` با کد وضعیت HTTP پاسخ یکسان است.
`status`*	integer	الزامی	کد وضعیت — همان کد وضعیت HTTP پاسخ. نمونه`200`
`message`*	string	الزامی	پیام فارسی قابل نمایش به کاربر. نمونه`درخواست تایید شد.`
`entries`	array<MessageInfo>	اختیاری	اطلاعات یک پیامک ثبت‌شده (`dto.MessageInfo`).
`messageid`	integer· int64	اختیاری	شناسهٔ پیامک در نجوا. برای رکوردهای نامعتبر/تکراری صفر است. نمونه`18392011`قالب`int64`
`message`	string	اختیاری	متن نهایی پیامک پس از افزودن «لغو۱۱».
`status`	integer	اختیاری	وضعیت پیامک: ۰ دریافت کننده نامعتبر · ۱ در صف ارسال · ۲ زمان‌بندی شده · ۴ ارسال شده به مخابرات · ۶ خطا در ارسال · ۱۰ رسیده به گیرنده · ۱۱ مشکل در رسیدن پیام · ۱۳ لغو شده · ۱۴ بلاک شده · ۱۵ شماره تکراری · ۱۰۰ شناسه نامعتبر. مقادیر مجاز`012461011131415100`نمونه`1`
`statustext`	string	اختیاری	متن فارسی وضعیت. نمونه`در صف ارسال`
`sender`	string	اختیاری	سرشمارهٔ ارسال. نمونه`3000505`
`receptor`	string	اختیاری	شمارهٔ گیرنده، نرمال‌شده به قالب `09xxxxxxxxx`. نمونه`09121234567`
`date`	integer· int64	اختیاری	زمان ثبت درخواست (unix، ثانیه). نمونه`1757145600`قالب`int64`
`cost`	number· float	اختیاری	هزینه به ریال (مقدار داخلی تومان × ۱۰). نمونه`700`قالب`float`

نمونهٔ پاسخ

{
  "return": {
    "status": 200,
    "message": "درخواست تایید شد."
  },
  "entries": [
    {
      "messageid": 18392011,
      "message": "سلام، سفارش شما ثبت شد.\nلغو۱۱",
      "status": 1,
      "statustext": "در صف ارسال",
      "sender": "3000505",
      "receptor": "09121234567",
      "date": 1757145600,
      "cost": 700
    },
    {
      "messageid": 18392012,
      "message": "سلام، سفارش شما ثبت شد.\nلغو۱۱",
      "status": 1,
      "statustext": "در صف ارسال",
      "sender": "3000505",
      "receptor": "09351234567",
      "date": 1757145600,
      "cost": 700
    },
    {
      "messageid": 0,
      "message": "",
      "status": 0,
      "statustext": "دریافت کننده نامعتبر",
      "sender": "",
      "receptor": "0912123",
      "date": 0,
      "cost": 0
    }
  ]
}