پرش به مطلب اصلی

ارسال گروهی

وقتی تعداد گیرندگان از ۱۰۰ بیشتر است، آن‌ها را در چند درخواست پیاپی زیر یک شناسه‌ی گروه (batchId) ثبت می‌کنید. تا زمانی که ارسال نهایی اعلام نشود، پیامی ارسال نمی‌شود. در درخواست آخر با IsFinal=true همه‌ی گیرندگان یک‌جا ارسال می‌شوند. هزینه‌ی کل پیش از ارسال نهایی محاسبه می‌شود و اگر اعتبار کافی نباشد، خطای کمبود موجودی همراه با مبلغ کسری برمی‌گردد.

مشخصات​

موردمقدار
متد و مسیرPOST /api/Message/SendBatch
احراز هویتکلید API یا Bearer
نوع بدنهapplication/json

پارامترهای query​

نامنوعالزامیتوضیح
IsFinalبولیخیرtrue برای ارسال نهایی گروه. پیش‌فرض false
Scheduleرشتهخیرتاریخ و ساعت شمسی ارسال، مانند 1405/08/30 10:30. در ارسال نهایی اعمال می‌شود

بدنه‌ی درخواست​

فیلدنوعالزامیتوضیح
batchIdعدد صحیح (long)بلهشناسه‌ی دلخواه شما برای این گروه. در همه‌ی درخواست‌های یک گروه یکسان است
codeعدد صحیح (long)بلهکد الگو؛ باید در همه‌ی درخواست‌های گروه یکی باشد
lineNumberرشتهخیرشماره‌ی خط ارسال
recipientsآرایهبلهگیرندگان همین درخواست؛ حداکثر ۱۰۰ مورد. در درخواست نهایی می‌تواند خالی باشد

ساختار هر گیرنده مانند ارسال پیامک است.

گام ۱: ثبت گیرندگان​

هر درخواست حداکثر ۱۰۰ گیرنده را ثبت می‌کند. این درخواست را با batchId یکسان، به‌تعداد لازم تکرار کنید:

curl -X POST "https://api.payavasms.com/api/Message/SendBatch?IsFinal=false" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"batchId": 1001,
"code": 123456789012,
"lineNumber": "YOUR_LINE_NUMBER",
"recipients": [
{
"phoneNumber": "09120000000",
"parameters": [
{
"key": "name",
"value": "علی"
},
{
"key": "code",
"value": "5821"
}
]
}
]
}'

گام ۲: ارسال نهایی​

پس از ثبت همه‌ی گیرندگان، با IsFinal=true ارسال را نهایی کنید. اگر گیرنده‌ی دیگری هم باقی مانده، می‌توانید در همین درخواست بفرستید؛ در غیر این صورت recipients را خالی بگذارید:

curl -X POST "https://api.payavasms.com/api/Message/SendBatch?IsFinal=true" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"batchId": 1001,
"code": 123456789012,
"lineNumber": "YOUR_LINE_NUMBER",
"recipients": []
}'

نمونه‌ی پاسخ​

{
"status": 0,
"message": "عملیات با موفقیت انجام شد.",
"data": {
"result": {
"messages": [
{
"registerCode": 10000001,
"phoneNumber": "989120000000",
"parts": 1
}
]
},
"platform": "Sms"
}
}

ساختار پاسخ مانند ارسال پیامک است.

خطاهای مخصوص ارسال گروهی​

statusمعنا
8000مقادیر درخواست جدید (مثلاً کد الگو) با درخواست‌های قبلی همان گروه مطابقت ندارد
8001موجودی کافی نیست و مبلغ کسری در پیام آمده است
8002خطا در بررسی موجودی
8010شناسه‌ی گروه در سامانه موجود نیست (مثلاً ارسال نهایی بدون ثبت قبلی)

سایر خطاها مانند ارسال پیامک است.