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

ارسال پیامک

این endpoint یک پیامک الگویی را برای یک یا چند گیرنده ثبت می‌کند. در هر درخواست حداکثر ۱۰۰ گیرنده پذیرفته می‌شود؛ برای تعداد بیشتر از ارسال گروهی استفاده کنید. ارسال با زمان‌بندی نیز با همین endpoint و پارامتر Schedule انجام می‌شود.

مشخصات​

موردمقدار
متد و مسیرPOST /api/Message/SendMessage
احراز هویتکلید API یا Bearer
هدر اختیاریX-Client-App، اگر کلاینت شما آن را الزامی کرده باشد
نوع بدنهapplication/json

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

نامنوعالزامیتوضیح
Scheduleرشتهخیرتاریخ و ساعت شمسی ارسال، مانند 1405/08/30 10:30. مقدار باید URL-encode شود

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

فیلدنوعالزامیتوضیح
codeعدد صحیح (long)بلهکد عددی الگو؛ از الگوها دریافت می‌شود
lineNumberرشتهخیرشماره‌ی خط ارسال؛ نوع خط باید با نوع الگو یکی باشد (خطوط ارسال). اگر خالی باشد، سامانه از میان خطوط هم‌نوع الگو، خط مناسب را خودکار انتخاب می‌کند
recipientsآرایهبلهفهرست گیرندگان؛ حداکثر ۱۰۰ مورد
recipients[].phoneNumberرشتهبلهشماره‌ی موبایل ایرانی، مانند 09120000000
recipients[].parametersآرایهبسته به الگومقدار پارامترهای الگو برای همین گیرنده
recipients[].parameters[].keyرشتهبلهکلید پارامتر مطابق الگو
recipients[].parameters[].valueرشتهبلهمقدار پارامتر

پارامترهای ثابت (مانند نام برند) و پارامترهای داینامیک (Dy_) را ارسال نکنید؛ سامانه خودش آن‌ها را پر می‌کند. قواعد کامل پارامترها در الگوها و پارامترها آمده است.

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

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

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

{
"status": 0,
"message": "عملیات با موفقیت انجام شد.",
"data": {
"result": {
"messages": [
{
"registerCode": 10000001,
"phoneNumber": "989120000000",
"parts": 1
}
]
},
"platform": "Sms"
}
}
فیلد پاسخنوعتوضیح
statusعددنتیجه‌ی عملیات؛ 0 یعنی موفق. سایر مقادیر در کدهای وضعیت آمده است
messageرشتهتوضیح فارسی نتیجه
dataobjectداده های مربوط به درخواست
توجه

خطاهای منظقی مانند کمبود موجودی یا پارامتر نامعتبر، ممکن است با کد HTTP 200 و status غیر از صفر برگردند. همیشه فیلد status بدنه را بررسی کنید و فقط به کد HTTP تکیه نکنید.

ارسال زمان‌بندی‌شده​

پارامتر Schedule را با تاریخ و ساعت شمسی بفرستید. محدودیتی برای فاصله‌ی زمانی وجود ندارد، اما اگر زمان گذشته باشد پیام بلافاصله ارسال می‌شود. مقدار باید URL-encode شود؛ در نمونه‌ی زیر 1405/08/30 10:30 به 1405%2F08%2F30%2010%3A30 تبدیل شده است.

curl -X POST "https://api.payavasms.com/api/Message/SendMessage?Schedule=1405%2F08%2F30%2010%3A30" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"code": 123456789012,
"lineNumber": "YOUR_LINE_NUMBER",
"recipients": [
{
"phoneNumber": "09120000000",
"parameters": [
{
"key": "name",
"value": "علی"
},
{
"key": "code",
"value": "5821"
}
]
}
]
}'

ارسال بدون تعیین خط​

اگر lineNumber را حذف کنید، سامانه خطی مناسب را انتخاب می‌کند:

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

خطاهای رایج​

statusمعنااقدام پیشنهادی
1موجودی کافی نیستحساب را شارژ کنید
2000الگو پیدا نشدکد الگو را بررسی کنید
2004الگو غیرفعال استالگوی فعال انتخاب کنید
3000خط در سامانه موجود نیست (یا برای انتخاب خودکار، خط هم‌نوع الگو یافت نشد)شماره‌ی خط را بررسی کنید
3002نوع خط با نوع الگو مطابقت نداردخطی هم‌نوع الگو انتخاب کنید یا lineNumber را حذف کنید
3500ارسال به برخی شماره‌ها ممکن نیستشماره‌های نامعتبر یا غیرمجاز را حذف کنید
4001حساب مسدود استبا پشتیبانی تماس بگیرید
4500 / 4501کلید برنامه الزامی یا نامطابق استهدر X-Client-App را اصلاح کنید
5001کلید پارامتر نامعتبر استکلیدها را با الگو مطابقت دهید
5002طول پارامتر بیش از حد مجاز استمقدار را کوتاه کنید
5003پارامتر اجباری مقدار نداردمقدار را بفرستید

فهرست کامل در کدهای وضعیت و خطاها قرار دارد. هنگام خطای پارامتر، data فهرستی از خطاها با اندیس گیرنده (index)، کلید (key)، کد (status) و دلیل (reason) است.