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

یک متن واحد را با یک سرشماره مشخص، به فهرستی از گیرندگان ارسال می‌کند. حداکثر ۱۰٬۰۰۰ گیرنده در هر فراخوانی مجاز است؛ سرشماره باید متعلق به حساب شما و دارای مجوز 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	الزامی	سرشماره ارسال. محدودیت: باید دقیقاً برابر شماره یکی از خطوط حساب کاربر و دارای مجوز 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
    }
  ]
}