مستندات فنی و راهنمای پیاده‌سازی وب سرویس‌های نجوا

دریافت توکن اختصاصی کاربر

پس از فعال کردن سرویس پوش نوتیفیکیشن، به هر کاربری که وارد وب‌سایت شما می‌شود پس از دادن اجازه ارسال پوش نوتیفیکیشن، یک توکن از سمت نجوا تخصیص داده خواهد شد. معیار یکتا بودن کاربر و تخصیص توکن، دستگاه استفاده شده از سمت کاربر برای subscribe شدن در سرویس پوش نوتیفیکیشن می‌باشد.
با دارا بودن این توکن، قادر خواهیم بود عملیات مختلفی از جمله ارسال اختصاصی پوش‌ نوتیفیکیشن به یک یا چند کاربر خاص و … را انجام دهیم.

برای این هدف، نجوا در scope اختصاصی خود در window، دو فانکشن مجزا در اختیار شما قرار داده است:

1- window.NAJVA.najvaUserSubscribed(najva_user_token)
2- window.NAJVA.getUserToken()

فانکشن najvaUserSubscribed:

این فانکشن بلافاصله بعد از subscribe شدن کاربر، اجرا خواهد شد و توکن کاربر را به عنوان پارامتر ورودی در اختیار دارد که شما قادر خواهید بود آن را دریافت کرده و عملیات مورد نظر خود را با استفاده از این توکن انجام دهید.

برای استفاده از این فانکشن،‌ کافی است کد زیر را در قسمت Head وب‌سایت خود قرار دهید و عملیات مورد نظر خود را بعد در داخل این فانکشن انجام دهید:

// :در این بخش می‌توانید از توکن کاربر استفاده نمایید. به عنوان مثال
alert(najva_user_token);
}
</script>

همانگونه که مشاهده می‌شود در قطعه کد بالا، najva_user_token به عنوان توکن اختصاصی کاربر به فانکشن پاس داده شده و به عنوان نمونه استفاده، این توکن در یک alert جاوااسکریپت نمایش داده شده است.

فانکشن getUserToken:
این فانکشن در لحظه فراخوانی، به شما در صورت subscribe بودن کاربر، توکن اختصاصی کاربر و در غیر این‌صورت، مقدار null برمی‌گرداند. و شما با استفاده از مقدار خروجی این فانکشن در هر جا و هر زمان بعد از subscribe شدن کاربر، مقدار توکن اختصاصی کاربر را داشته باشید:

ارسال به توکن خاص

نمونه درخواست ورودی:

curl –location ‘https://push.najva.com/v1/send/token/’ \

–header ‘Content-Type: multipart/form-data’ \

–header ‘apiKey: {Api Key}’ \

–form ‘website_id=”45100″‘ \

–form ‘ttl=”24″‘ \

–form date=”2025-07-21T21:04:45+03:30″‘ \

–form ‘tokens[]=”21a4548a-574d-4425-9af2-6a0e70dae649″‘ \

–form ‘tokens[]=”9615c2ea-9d2d-4343-b880-4e79cb115384″‘ \

–form ‘message.title=”transactional sample”‘ \

–form ‘message.body=”this is the body of transactional sample”‘ \

–form ‘message.icon=@/path/to/your/icon.jpg’ \

–form ‘message.image=@/path/to/your/image.jpg’ \

–form ‘message.notification_click.click_url=”https://google.com”‘ \

–form ‘message.button_1.title=”Button One”‘ \

–form ‘message.button_1.click_url=”https://najva.com”‘

نمونه پاسخ خروجی:

{

“Message”: “Request approved.”,

“Entries”: {

“request_id”: “4faac313-f3b2-4f5e-b9b9-dabc7e3f5d4c”,

“tokens”: [

{

“token”: “21a4548a-574d-4425-9af2-6a0e70dae649”,

“status”: “InvalidToken”,

“cost”: 0

},

{

“token”: “9615c2ea-9d2d-4343-b880-4e79cb115384”,

“status”: “Scheduled”,

“cost”: 25

}

]

}

ارسال به همه کاربران

نمونه درخواست ورودی:

curl –location ‘https://push.najva.com/v1/send/bulk/’ \

–header ‘Content-Type: multipart/form-data’ \

–header ‘apiKey: {Api Key}’ \

–form ‘website_id=”45100″‘ \

–form ‘ttl=”24″‘ \

–form ‘datetime=”025-07-21T21:04:45+03:30″”‘ \

–form ‘message.title=”transactional sample”‘ \

–form ‘message.body=”this is the body of transactional sample”‘ \

–form ‘message.icon=@/path/to/your/icon.jpg’ \

–form ‘message.image=@/path/to/your/image.jpg’ \

–form ‘message.notification_click.click_url=”https://google.com”‘ \

–form ‘message.button_1.title=”Button One”‘ \

–form ‘message.button_1.click_url=”https://najva.com”‘

نمونه پاسخ خروجی:

{

“Message”: “Request approved.”,

“Entries”: {

“campaign_id”: 17834,

“execution_id”: 19937,

“execution_status”: “Scheduled”

}

پیاده‌سازی PWA در IOS

۱. الزامات اولیه

برای آنکه وب‌سایت شما قابلیت نصب به‌عنوان PWA را داشته باشد، شرایط زیر باید فراهم شود:

وب‌سایت باید تحت پروتکل HTTPS اجرا شود.
فایل manifest.json باید در دسترس مرورگر قرار گیرد.
MetaDataهای مناسب در سند HTML قرار داده شوند.

۲. ایجاد فایل manifest.json

فایل manifest.json باید در مسیر عمومی (public) قرار گیرد و حاوی اطلاعات پایه‌ای برنامه باشد:

public/manifest.json
{
“name”: “عنوان کامل برنامه”,
“short_name”: “عنوان کوتاه”,
“start_url”: “/”,
“display”: “standalone”,
“background_color”: “#ffffff”,
“theme_color”: “#4f4691”,
“orientation”: “portrait”,
“icons”: [
{
“src”: “/icons/icon-192.png”,
“sizes”: “192×192”,
“type”: “image/png”
},
{
“src”: “/icons/icon-512.png”,
“sizes”: “512×512”,
“type”: “image/png”
}
]
}

توجه: تصاویر آیکون باید در مسیر public/icons قرار داشته باشند و از ابعاد استاندارد استفاده شود.

۳. درج پیوند فایل مانیفست در HTML

در پروژه‌های Next.js، فایل pages/_document.tsx یا _document.js باید به‌گونه‌ای اصلاح شود که فایل manifest و سایر MetaDataهای مرتبط درج شوند:

import { Html, Head, Main, NextScript } from ‘next/document’;
export default function Document() {
return (
<Html lang=”fa”>
<Head>
<link rel=”manifest” href=”/manifest.json” />
<meta name=”theme-color” content=”#4f4691″ />
<link rel=”apple-touch-icon” href=”/icons/icon-192.png” />
</Head>
<body>
<Main />
<NextScript />
</body>
</Html>
);
}

۴. پیکربندی افزونه next-pwa

برای ساده‌سازی روند، استفاده از بسته next-pwa توصیه می‌شود. این بسته قابلیت‌های PWA را با حداقل پیکربندی به پروژه اضافه می‌کند.

مستندات ارسال و دریافت پیامک- نسخه ۱

این نسخه مخصوص ارسال‌های تراکنشی پیامک بوده و برای ارسال‌های از جنس تراکنشی، اتومیشنی و یا OTP قابل استفاده است.

ساختار URL این متد:

https://sms.najva.com/v1/{API-KEY}/sms/send.json

پارامتر‌های ورودی:

پارامتر	نوع	تایپ	توضیحات
receptor	اجباری	String	شماره گیرندگان پیام را مشخص می‌کند، می‌توانید چندین شماره را با ‘,’ از یکدیگر جدا کنید.
message	اجباری	String	متن پیام ارسالی، این متن حتما باید به فرمت URL Encode انکود شده باشد.
sender	اختیاری	String	شماره خط ارسال‌کننده پیام،‌ در صورت خالی بودن، خط پیش فرض انتخاب خواهد شد.
date	اختیاری	UnixTime	زمان ارسال پیام، در صورت خالی بودن پیام در لحظه ارسال خواهد شد.
localid	اختیاری	String	شناسه محلی در پایگاه داده شما

پارامتر‌های خروجی:

پارامتر	تایپ	توضیحات
messageid	Long	شناسه یکتای پیامک
message	String	متن پیامک ارسالی
status	Integer	وضعیت ارسال پیامک
statustext	String	متن توضیح وضعیت ارسال پیامک
sender	String	شماره فرستنده
receptor	String	شماره گیرنده
date	UnixTime	زمان ارسال پیامک
cost	Integer	هزینه پیامک

نکات:

برای استفاده از این روش، کاربر حتما باید خط اختصاصی داشته باشد.
برای اطلاع از وضعیت پیامک به جدول وضعیت پیامک‌ها در انتهای مستند مراجعه نمایید.
در مورد شناسه محلی LocaId به چند نکته توجه نمایید:
- در صورت مقدار دهی ،تعداد آن باید برابر تعداد گیرنده باشد و با کاراکتر ویرگول « , » آنها را از هم جدا کنید
- در صورت تکرار این شناسه محلی در ارسال‌های قبلی شما، ارسال تکراری انجام نمی‌شود و رکورد مربوط به این شناسه در خروجی قرار خواهد گرفت.

جدول خطاها:

کد خطا	توضیح
۴۰۰	پارارمتر‌های ورودی صحیح نیستند.
۴۱۴	تعداد دریافت کننده‌ها بیش از ۲۰۰ عدد است.
۴۱۶	آدرس IP مبدأ مطابقت ندارد.
۴۱۷	تاریخ ارسال اشتباه است.
۴۱۸	اعتبار حساب شما کافی نیست.

نمونه درخواست ورودی:

https://sms.najva.com/v1/{API-KEY}/sms/send.json?receptor=0912000000,0912000001&sender=10001234&message=%D8%B3%D8%B1%D9%88%DB%8C%D8%B3%20%D8%A7%D8%B1%D8%B3%D8%A7%D9%84%20%D9%BE%DB%8C%D8%A7%D9%85%DA%A9%20%D9%86%D8%AC%D9%88%D8%A7

نمونه پاسخ خروجی:

{
“return”: {
“status”: 200,
“message”: “تایید شد”
},
“entries”: [
{
“messageid”: 1,
“message”: “سرویس ارسال پیامک نجوا”,
“status”: 1,
“statustext”: “در صف ارسال”,
“sender”: “10004346”,
“receptor”: “09120000000”,
“date”: 1706619709,
“cost”: 100
},
{
“messageid”: 2,
“message”: “سرویس ارسال پیامک نجوا”,
“status”: 1,
“statustext”: “در صف ارسال”,
“sender”: “10004346”,
“receptor”: “09120000001”,
“date”: 1706619709,
“cost”: 100
}
]
}

ارسال با قالب از پیش‌تعریف‌شده پیامک

کاربرد این متد ارسال پیامک از طریق قالب از پیش تعریف شده و پرکردن پارامتر‌های تعریف شده در قالب مد نظر است. برای استفاده از این سرویس باید از طریق پنل،‌ قالب دلخواه خود را اضافه کنید. از کاربردهای این متد، ارسال کد اعتبارسنجی یا اطلاعات مهم و حساس می‌باشد.

مثلا قالب پیامک زیر را در نظر بگیرید:

کد اعتبار سنجی (مقدار اولین توکن): %token

رمز عبور (مقدار دومین توکن): %token2

سریال (مقدار سومین توکن): %token3

مقدار متغیر بعدی (مقدار چهارمین توکن): %token10

(مقدار پنجمین توکن): %token20

با معین کردن مقادیر توکن در پارامتر‌های درخواست، می‌توانید قالب بالا را مقادیر مشخص‌شده توسط خودتان پر کنید و متنی که از این قالب تولید می‌شود، ارسال خواهد شد.

ساختار URL این متد:

https://sms.najva.com/v1/{API-KEY}/verify/lookup.json

پارامتر‌های ورودی:

پارامتر	نوع	تایپ	توضیحات
receptor	اجباری	String	شماره گیرنده پیام را مشخص می‌کند.
template	اجباری	String	نام قالب پیامکی تعریف‌شده در پنل نجوا
sender	اجباری	String	شماره خط ارسال‌کننده پیام
token	اجباری	String	رشته‌ای که در جایگاه تعریف شده برای token در تمپلیت تعریف شده قرار می‌گیرد.
token2	اختیاری	String	رشته‌ای که در جایگاه تعریف شده برای token2 در تمپلیت تعریف شده قرار می‌گیرد.
token3	اختیاری	String	رشته‌ای که در جایگاه تعریف شده برای token3 در تمپلیت تعریف شده قرار می‌گیرد.
token10	اختیاری	String	رشته‌ای که در جایگاه تعریف شده برای token10 در تمپلیت تعریف شده قرار می‌گیرد.
token20	اختیاری	String	رشته‌ای که در جایگاه تعریف شده برای token20 در تمپلیت تعریف شده قرار می‌گیرد.

پارامتر‌های خروجی:

پارامتر	تایپ	توضیحات
messageid	Long	شناسه یکتای پیامک
message	String	متن پیامک ارسالی
status	Integer	وضعیت ارسال پیامک
statustext	String	متن توضیح وضعیت ارسال پیامک
sender	String	شماره فرستنده
receptor	String	شماره گیرنده
date	UnixTime	زمان ارسال پیامک
cost	Integer	هزینه پیامک

نکات:

برای اطلاع از وضعیت پیامک به جدول وضعیت پیامک‌ها در انتهای مستند مراجعه نمایید.
شماره فرستنده (پارامتر sender) می‌تواند شماره اشتراکی یا شماره اختصاصی کاربر باشد.
قالب ارسالی، بایست پیش از استفاده از این متد تایید شده باشد.
هر کدام از توکن‌ها مقادیر و محدودیت‌هایی برای مقادیر خود دارند که در ادامه می‌آید. به صورت کلی همه توکن‌ها می‌توانند تمامی کاراکتر‌های معمول مثل حروف انگلیسی، حروف فارسی، اعداد را داشته باشند اما روی طول آن‌ها و شامل بودن کاراکتر فضای خالی محدودیت دارند (دقت شود به صورت کلی روی حداکثر کاراکتر داخل متن پیامک محدودیت وجود دارد.)

پارامتر	حداکثر طول	حداکثر تعداد فضای خالی (space)
token	۱۰۰	۰
token2	۱۰۰	۰
token3	۱۰۰	۰
token10	–	۴
token20	–	۸

جدول خطاها:

کد خطا	توضیح
۴۰۰	پارارمتر‌های ورودی صحیح نیستند.
۴۱۴	تعداد دریافت کننده‌ها بیش از ۲۰۰ عدد است.
۴۱۷	تاریخ ارسال اشتباه است.
۴۱۸	اعتبار حساب شما کافی نیست.
۴۲۲	مقدار پارامتر ارسال شده معتبر نیست (طولانی بودن و کاراکتر غیرمجاز)
۴۲۴	تمپلیت مشخص‌شده تایید نشده است.

نمونه درخواست ورودی:

https://sms.najva.com/v1/{API-KEY}/verify/lookup.json?receptor=0912000000&sender=90000625&template=Test&token=tavalue&token2=tvalue2&token3=tvalue3&token10=tvalue10&token20=tvalue20

نمونه پاسخ خروجی:

{

“return”: {

“status”: 200,

“message”: “درخواست تایید شد.”

},

“entries”: [

{

“messageid”: 614,

“message”: “کد اعتبار سنجی (مقدار اولین توکن): tvalue \nرمز عبور (مقدار دومین توکن): tvalue2 \nسریال (مقدار سومین توکن): tvalue3 \nمقدار متغیر بعدی (مقدار دهمین توکن): tvalue10 \n(مقدار بیستمین توکن): tvalue20”,

“status”: 1,

“statustext”: “در صف ارسال”,

“sender”: “90000625”,

“receptor”: “09120000000”,

“date”: 1718016806,

“cost”: 3780

}

]

}

جدول وضعیت پیا‌‌‌م‌ها

کد وضعیت	توضیحات
1	در صف ارسال
2	زمانبندی شده
4	ارسال شده به مخابرات
6	خطا در ارسال پیام به سرشماره مشخص شده
10	پیامک تحویل گیرنده پیام شده است
11	در تحویل پیامک مشکلی رخ داده است، از دسترس بودن مخاطب و یا خاموش بودن گوشی آن از جمله دلایل این وضعیت است.
13	ارسال پیامک لغو شده است.
14	گیرنده دریافت این پیامک را بلاک کرده است. ممکن است سرشماره یا پیامک‌های تبلیغاتی توسط گیرنده بلاک شده باشد. هزینه‌ی این پیامک به حساب شما باز میگردد.
100	شناسه پیامک نامعتبر است.

دریافت وضعیت ارسال

پیامک‌ها بعد از ارسال از طریق وب سرویس، وضعیت در صف خواهند داشت، و سپس به مخابرات ارسال خواهند شد و وضعیت ارسال به مخابرات را خواهند گرفت. سپس به صورت پیوسته وضعیت آنها کنترل می‌شود تا به وضعیت نهایی در سیستم برسند.

از این متد برای کنترل وضعیت تحویل Delivery پیامک استفاده کنید. برای استفاده از این متد باید شناسه یکتای هر پیامک messageid را که پس از ارسال پیامک در خروجی دریافت کرده‌اید را به عنوان پارامتر ورودی ارسال کنید.
در هر بار اجرای این متد می‌توانید وضعیت حداکثر ۵۰۰ پیامک را دریافت کنید. شناسه یکتای پیامک‌ها را به وسیله ‘,’ از یکدیگر متمایز کنید.

ساختار URL این متد:

https://sms.najva.com/v1/{API-KEY}/sms/status.json

پارامتر‌های ورودی:

پارامتر	نوع	تایپ	توضیحات
messageid	اجباری	Long	شناسه‌ی یکتای پیامک‌های مورد نظر

پارامتر‌های خروجی:

پارامتر	تایپ	توضیحات
messageid	Long	شناسه یکتای پیامک
status	Integer	وضعیت ارسال پیامک
statustext	String	متن توضیح وضعیت ارسال پیامک

نکات:

برای مشاهده لیست کامل وضعیت پیامک‌ها به انتهای مستند مراجعه نمایید.
در صورتی که شناسه پیامک messageid معتبر نباشد، مقدار فیلد status = 100 خواهد بود.

جدول خطاها:

کد خطا	توضیح
۴۰۰	پارارمتر‌های ورودی صحیح نیستند.
۴۱۴	تعداد messageId‌ها بیش از ۵۰۰ عدد است.

نمونه درخواست ورودی:

https://sms.najva.com/v1/{API-KEY}/sms/status.json?messageid=1234,4321

نمونه پاسخ خروجی:

{
“return”: {
“status”: 200,
“message”: “تایید شد”
},
“entries”: [
{
“messageid”: 1234,
“status”: 10,
“statustext”: “رسیده به گیرنده”
},
{
“messageid”: 4321,
“status”: 4,
“statustext”: “رسیده به مخابرات”
}
]
}

دریافت وضعیت به وسیله localId

به وسیله‌ی این متد می‌توانید گزارش پیامک‌ها را بر اساس localid که در هنگام ارسال پیامک به سامانه مشخص نمودید، دریافت کنید. ساختار خروجی این متد مشابه متد دریافت وضعیت ارسال می‌باشد.

در هر بار اجرای این متد می‌توانید از وضعیت حداکثر ۵۰۰ پیامک با خبر شوید. کافیست شناسه محلی پیامک ها را از طریق کاراکتر ویرگول « , » از هم جدا کنید.

ساختار URL این متد:

https://sms.najva.com/v1/{API-KEY}/sms/statuslocalmessageid.json

پارامتر‌های ورودی:

پارامتر	نوع	تایپ	توضیحات
localid	اجباری	Long	شناسه‌ی محلی پیامک‌های مورد نظر

پارامتر‌های خروجی:

پارامتر	تایپ	توضیحات
messageid	Long	شناسه یکتای پیامک
localid	Long	شناسه محلی پیامک
status	Integer	وضعیت ارسال پیامک
statustext	String	متن توضیح وضعیت ارسال پیامک

نکات:

وضعیت پیامک ها به جدول وضعیت پیامک ها در انتهای مستند مراجعه نمایید.
فقط پیامک‌های ۴۸ ساعت گذشته localid قابل دریافت هستند.

جدول خطاها:

کد خطا	توضیح
۴۱۴	تعداد localid ها بیش از ۵۰۰ عدد است.

نمونه درخواست ورودی:

https://sms.najva.com/v1/{API-KEY}/sms/statuslocalmessageid.json?localid=4321

نمونه پاسخ خروجی:

{
“return”: {
“status”: 200,
“message”: “تایید شد”
},
“entries”: [
{
“messageid”: 1234,
“status”: 10,

“localid”: 4321
“statustext”: “رسیده به گیرنده”
}
]

}

انتخاب پیامک

در صورتی که می‌خواهید اطلاعات پیامک ارسالی را دریافت نمایید، می‌توانید با messageid و استفاده از این متد اطلاعات رکورد را دریافت کنید.

در هر بار اجرای این متد می‌توانید وضعیت حداکثر ۵۰۰ پیامک را دریافت کنید. شناسه یکتای پیامک‌ها را به وسیله ‘,’ از یکدیگر متمایز کنید.

ساختار URL این متد:

https://sms.najva.com/v1/{API-KEY}/sms/select.json

پارامتر‌های ورودی:

پارامتر	نوع	تایپ	توضیحات
messageid	اجباری	Long	شناسه‌ی یکتای پیامک‌های مورد نظر

پارامتر‌های خروجی:

پارامتر	تایپ	توضیحات
messageid	Long	شناسه یکتای پیامک
message	String	متن پیامک ارسالی
status	Integer	وضعیت ارسال پیامک
statustext	String	متن توضیح وضعیت ارسال پیامک
sender	String	شماره فرستنده
receptor	String	شماره گیرنده
date	UnixTime	زمان ارسال پیامک
cost	Integer	هزینه پیامک

نکات:

در صورتی که شناسه پیامک messageid معتبر نباشد، مقدار فیلد status = 100 خواهد بود.

جدول خطاها:

کد خطا	توضیح
400	پارارمتر‌های ورودی صحیح نیستند.
407	دسترسی به اطلاعات مورد نظر برای شما امکان پذیر نیست
414	تعداد دریافت کننده‌ها بیش از ۲۰۰ عدد است.

نمونه درخواست ورودی:

https://sms.najva.com/v1/{API-KEY}/sms/select.json?messageid=1234,4321

نمونه پاسخ خروجی:

{
“return”: {
“status”: 200,
“message”: “تایید شد”
},
“entries”: [
{
“messageid”: 1234,
“message”: “سرویس ارسال پیامک نجوا”,
“status”: 1,
“statustext”: “در صف ارسال”,
“sender”: “10004346”,
“receptor”: “09120000000”,
“date”: 1706619709,
“cost”: 100
},
{
“messageid”: 4321,
“message”: “سرویس ارسال پیامک نجوا”,
“status”: 1,
“statustext”: “در صف ارسال”,
“sender”: “10004346”,
“receptor”: “09120000001”,
“date”: 1706619709,
“cost”: 100
}
]
}

لیست ارسال‌های پیامک

برای دریافت لیست پیامک‌های ارسال شده در یک بازه‌ی زمانی خاص از این متد استفاده کنید.

ساختار URL این متد:

https://sms.najva.com/v1/{API-KEY}/sms/selectoutbox.json

پارامتر‌های ورودی:

پارامتر	نوع	تایپ	توضیحات
startdate	اجباری	Long	تاریخ شروع بازه‌ی مورد نظر به فرمت UnixTime
enddate	اختیاری	Long	تاریخ پایان بازه‌ی مورد نظر به فرمت UnixTime، مقدار پیش‌فرض زمان حال است.
sender	اختیاری	String	خط اختصاصی ارسال کننده پیامک

پارامتر‌های خروجی:

پارامتر	تایپ	توضیحات
messageid	Long	شناسه یکتای پیامک
message	String	متن پیامک ارسالی
status	Integer	وضعیت ارسال پیامک
statustext	String	متن توضیح وضعیت ارسال پیامک
sender	String	شماره فرستنده
receptor	String	شماره گیرنده
date	UnixTime	زمان ارسال پیامک
cost	Integer	هزینه پیامک

نکات:

حداکثر طول بازه‌ی درخواست می‌تواند یک روز باشد.
تاریخ شروع حداکثر می‌تواند تا ۶۰ روز پیش باشد.
حداکثر قابلیت دریافت ۵۰۰ پیامک در این api وجود دارد.
تاریخ پایان حتما باید بعد از تاریخ شروع باشد.
برای دریافت پیام‌های یک خط خاص از sender استفاده کنید.

جدول خطاها:

کد خطا	توضیح
400	پارارمتر‌های ورودی صحیح نیستند.
407	دسترسی به اطلاعات مورد نظر برای شما امکان پذیر نیست
417	بازه‌ی زمانی داده شده معتبر نیست.

نمونه درخواست ورودی:

https://sms.najva.com/v1/{API-KEY}/sms/selectoutbox.json??startdate=1706619700&enddate=1706620000

نمونه پاسخ خروجی:

{
“return”: {
“status”: 200,
“message”: “تایید شد”
},
“entries”: [
{
“messageid”: 1,
“message”: “سرویس ارسال پیامک نجوا”,
“status”: 1,
“statustext”: “در صف ارسال”,
“sender”: “10004346”,
“receptor”: “09120000000”,
“date”: 1706619709,
“cost”: 100
},
{
“messageid”: 2,
“message”: “سرویس ارسال پیامک نجوا”,
“status”: 1,
“statustext”: “در صف ارسال”,
“sender”: “10004346”,
“receptor”: “09120000001”,
“date”: 1706619709,
“cost”: 100
}
]
}

آخرین ارسال‌های پیامک

برای دریافت لیست آخرین پیامک‌های ارسال شده از این متد استفاده کنید.

ساختار URL این متد:

https://sms.najva.com/v1/{API-KEY}/sms/latestoutbox.json

پارامتر‌های ورودی:

پارامتر	نوع	تایپ	توضیحات
pagesize	اختیاری	Long	تعداد رکورد‌های مورد نیاز (حداکثر ۵۰۰ رکورد)، مقدار پیش‌فرض این پارامتر ۵۰۰ است.
sender	اختیاری	String	خط اختصاصی ارسال کننده پیامک

پارامتر‌های خروجی:

پارامتر	تایپ	توضیحات
messageid	Long	شناسه یکتای پیامک
message	String	متن پیامک ارسالی
status	Integer	وضعیت ارسال پیامک
statustext	String	متن توضیح وضعیت ارسال پیامک
sender	String	شماره فرستنده
receptor	String	شماره گیرنده
date	UnixTime	زمان ارسال پیامک
cost	Integer	هزینه پیامک

نکات:

برای دریافت پیام‌های یک خط خاص از sender استفاده کنید.

جدول خطاها:

کد خطا	توضیح
400	پارارمتر‌های ورودی صحیح نیستند.
407	دسترسی به اطلاعات مورد نظر برای شما امکان پذیر نیست
417	بازه‌ی زمانی داده شده معتبر نیست.

نمونه درخواست ورودی:

https://sms.najva.com/v1/{API-KEY}/sms/latestoutbox.json?pagesize=2

نمونه پاسخ خروجی:

{
“return”: {
“status”: 200,
“message”: “تایید شد”
},
“entries”: [
{
“messageid”: 1,
“message”: “سرویس ارسال پیامک نجوا”,
“status”: 1,
“statustext”: “در صف ارسال”,
“sender”: “10004346”,
“receptor”: “09120000000”,
“date”: 1706619709,
“cost”: 100
},
{
“messageid”: 2,
“message”: “سرویس ارسال پیامک نجوا”,
“status”: 1,
“statustext”: “در صف ارسال”,
“sender”: “10004346”,
“receptor”: “09120000001”,
“date”: 1706619709,
“cost”: 100
}
]
}

تعداد ارسال‌های پیامک

برای دریافت تعداد پیامک‌های ارسال شده در یک بازه‌ی زمانی خاص از این متد استفاده کنید.

ساختار URL این متد:

https://sms.najva.com/v1/{API-KEY}/sms/countoutbox.json

پارامتر‌های ورودی:

پارامتر	نوع	تایپ	توضیحات
startdate	اجباری	Long	تاریخ شروع بازه‌ی مورد نظر به فرمت UnixTime
enddate	اختیاری	Long	تاریخ پایان بازه‌ی مورد نظر به فرمت UnixTime، مقدار پیش‌فرض زمان حال است.
status	اختیاری	Integer	در صورتی که میخواهید فقط پیام‌هایی با وضعیت مشخص را دریافت نمایید از این پارامتر استفاده کنید.

پارامتر‌های خروجی:

پارامتر	تایپ	توضیحات
startdate	Long	تاریخ شروع بازه‌ی درخواست
enddate	Long	تاریخ پایان بازه‌ی درخواست
sumpart	Long	مجموع تعداد صفحات ارسالی
sumcount	Long	مجموع تعداد پیام‌های ارسالی
cost	Long	هزینه‌ی پیامک‌های ارسالی (ریال)

نکات:

حداکثر طول بازه‌ی درخواست می‌تواند یک روز باشد.
تاریخ شروع حداکثر می‌تواند تا ۶۰ روز پیش باشد.
تاریخ پایان حتما باید بعد از تاریخ شروع باشد.
برای دریافت پیام‌های یک خط خاص از sender استفاده کنید.

جدول خطاها:

کد خطا	توضیح
400	پارارمتر‌های ورودی صحیح نیستند.
417	بازه‌ی زمانی داده شده معتبر نیست.

نمونه درخواست ورودی:

https://sms.najva.com/v1/{API-KEY}/sms/countoutbox.json??startdate=1706619700&enddate=1706620000

نمونه پاسخ خروجی:

{
“return”: {
“status”: 200,
“message”: “تایید شد”
},
“entries”: [
{
“startdate”: 1706619700,
“enddate”: 1706620000,
“sumpart”: 10,
“sumcount”: 4,
“cost”: 12000,
}
]
}

انصراف از ارسال پیامک

با استفاده از این متود می‌توانید ارسال‌های زمانبندی شده را لغو کنید و ارسال آنها را متوقف کنید.

در هر بار اجرای این متد می‌توانید وضعیت حداکثر ۵۰۰ پیامک را دریافت کنید. شناسه یکتای پیامک‌ها را به وسیله ‘,’ از یکدیگر متمایز کنید.

ساختار URL این متد:

https://sms.najva.com/v1/{API-KEY}/sms/cancel.json

پارامتر‌های ورودی:

پارامتر	نوع	تایپ	توضیحات
messageid	اجباری	Long	شناسه‌ی یکتای پیامک‌های مورد نظر

پارامتر‌های خروجی:

پارامتر	تایپ	توضیحات
messageid	Long	شناسه یکتای پیامک
status	Integer	وضعیت ارسال پیامک
statustext	String	متن توضیح وضعیت ارسال پیامک

نکات:

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

جدول خطاها:

کد خطا	توضیح
400	پارارمتر‌های ورودی صحیح نیستند.
412	درخواست لغو شد. تعداد پیامک‌های بیش از ۲۰۰ بوده است.

نمونه درخواست ورودی:

https://sms.najva.com/v1/{API-KEY}/sms/cancel.json?messageid=4321

نمونه پاسخ خروجی:

{
“return”: {
“status”: 200,
“message”: “تایید شد”
},
“entries”: [
{
“messageid”: 4321,
“status”: 13,
“statustext”: “لغو شده”
}
]
}

دریافت پیامک‌های دریافتی

به کمک این متد می‌توانید پیامک‌های دریافتی خط اختصاصی خود را دریافت نمایید.

ساختار URL این متد:

https://sms.najva.com/v1/{API-KEY}/sms/receive.json

پارامتر‌های ورودی:

پارامتر	نوع	تایپ	توضیحات
linenumber	اجباری	String	خط اختصاصی مورد نظر شما
isread	اجباری	Integer	خوانده شده: ۱، خوانده نشده: ۰

پارامتر‌های خروجی:

پارامتر	تایپ	توضیحات
messageid	Long	شناسه پیام دریافتی
message	String	متن پیامک
sender	String	شماره ارسال کننده پیامک
receptor	String	شماره دریافت کننده پیامک
date	UnixTime	تاریخ دریافت پیامک

نکات:

هر بار فراخوانی این متد ۱۰۰ پیامک برگردانده می‌شود.

نمونه درخواست ورودی:

https://sms.najva.com/v1/{API-KEY}/sms/receive.json?linenumber=90000123

نمونه پاسخ خروجی:

{
“return”: {
“status”: 200,
“message”: “تایید شد”
},
“entries”: [
{
“messageid”: 4321,
“message”: “پیام دریافتی نمونه”,
“sender”: “09123456789”,

“receptor”: “90000123”,

“date”: 1706619700

}
]
}

تعداد پیامک‌های دریافت شده

از این متد برای دریافت تعداد پیامک های دریافت شده به کلیه خطوط اختصاصی یا یک خط خاص در بازه زمانی استفاده کنید.

ساختار URL این متد:

https://sms.najva.com/v1/{API-KEY}/sms/countinbox.json

پارامتر‌های ورودی:

پارامتر	نوع	تایپ	توضیحات
startdate	اجباری	Long	تاریخ شروع بازه‌ی مورد نظر به فرمت UnixTime
enddate	اختیاری	Long	تاریخ پایان بازه‌ی مورد نظر به فرمت UnixTime، مقدار پیش‌فرض زمان حال است.
linenumber	اختیاری	Integer	خط اختصاصی مورد نظر شما
isread	اجباری	Integer	خوانده شده: ۱، خوانده نشده: ۰

پارامتر‌های خروجی:

پارامتر	تایپ	توضیحات
startdate	Long	تاریخ شروع بازه‌ی درخواست
enddate	Long	تاریخ پایان بازه‌ی درخواست
sumcount	Long	مجموع تعداد پیام‌های دریافتی

نکات:

حداکثر طول بازه‌ی درخواست می‌تواند یک روز باشد.
تاریخ شروع حداکثر می‌تواند تا ۶۰ روز پیش باشد.
تاریخ پایان حتما باید بعد از تاریخ شروع باشد.

جدول خطاها:

کد خطا	توضیح
400	پارارمتر‌های ورودی صحیح نیستند.
417	بازه‌ی زمانی داده شده معتبر نیست.

نمونه درخواست ورودی:

https://sms.najva.com/v1/{API-KEY}/sms/countinbox.json?linenumber=90000123

نمونه پاسخ خروجی:

{
“return”: {
“status”: 200,
“message”: “تایید شد”
},
“entries”: [
{
“startdate”: 1706619700,
“enddate”: 1706620000,
“sumcount”: 10

}
]
}

وب‌هوک

برای دریافت گزارش‌ها از طریق callback بایست در بخش تنظیمات پیامک پنل نجوا آدرس endpoint و متد ارسال درخواست وب‌هوک از میان متد‌های GET و POST، تعیین شود.

پس از آن، به ازای هر تغییر در وضعیت پیامک ارسالی، درخواستی برای endpoint معرفی شده توسط شما ارسال می‌شود. در حال حاضر، درخواست وب‌هوک تنها یک بار ارسال می‌شود (در صورتی که status مناسب توسط endpoint بازگردانده نشود، دوباره درخواست وب‌هوک ارسال نمی‌شود)

در درخواستی که از طرف نجوا به endpoint شما ارسال می‌شود، دو پارامتر زیر وجود دارند(در body درخواست):

messageid: که آیدی پیام ارسالی را مشخص می‌کند
status: که وضعیت پیام ارسالی را نشان می‌دهد. (طبق جدول پیوست شده)

نمونه‌ پیام ارسالی:

{
“messageid”: 1234,
“status”: 10,
}

مستندات ارسال و دریافت پیامک- نسخه ۲

این نسخه مخصوص ارسال‌های تعداد بالای پیامک از طریق API بوده و برای ارسال‌های از جنس کمپینی قابل استفاده است.

احراز هویت در تمام endpoint ها

برای احراز هویت در تمامی endpoint‌ها، با استفاده از توکن دریافت شده در صفحه‌ی تنظیمات (API TOKEN)، این توکن را در قالب هدر (header) زیر در تمامی درخواست‌ها ارسال نمایید.

محتوا	نام هدر
Bearer <API_TOKEN>	Authorization

ارسال پیامک دسته‌ای

کاربرد این متد ارسال پیامک یکسان به یک دسته از مخاطبان است. برای ارسال تکی نیز از همین متد استفاده کنید. در این متد می‌توانید حداکثر به ۱۰۰۰۰ نفر در یک درخواست پیامک ارسال کنید.

ساختار URL این متد:

باید از متد POST برای ارسال به این endpoint استفاده کنید.

https://sms.najva.com/v2/sms/send

پارامتر‌های ورودی:

پارامتر	نوع	تایپ	توضیحات
receptor	اجباری	String	شماره گیرندگان پیام را مشخص می‌کند. به صورت لیستی از شماره‌ها می‌باشد.
message	اجباری	String	متن پیام ارسالی، این متن حتما باید به فرمت URL Encode انکود شده باشد.
sender	اجباری	String	شماره خط ارسال‌کننده پیام

پارامتر‌های خروجی:

پارامتر	تایپ	توضیحات
messageid	Long	شناسه یکتای پیامک
message	String	متن پیامک ارسالی
status	Integer	وضعیت ارسال پیامک
statustext	String	متن توضیح وضعیت ارسال پیامک
sender	String	شماره فرستنده
receptor	String	شماره گیرنده
date	UnixTime	زمان ارسال پیامک
cost	Integer	هزینه پیامک

نکات:

برای اطلاع از وضعیت پیامک به جدول وضعیت پیام‌ها در انتهای مستند مراجعه نمایید.
محدودیت تعداد دریافت کننده‌ها ۱۰۰۰۰ نفر است.

جدول خطاها:

کد خطا	توضیح
۴۰۰	پارارمتر‌های ورودی صحیح نیستند.
۴۱۴	تعداد دریافت کننده‌ها بیش از 10000 عدد است.
۴۱۸	اعتبار حساب شما کافی نیست.

نمونه درخواست ورودی:

درخواست باید به فرمت زیر در body ارسال شود.

{
“message”: “این پیامک از زیرساخت ارسال پیامک نجوا ارسال شده است.”,
“sender”: “90000123”,
“receivers”: [
“09120000000”,
“09120000001”,
“09120000002”
]
}

نمونه پاسخ خروجی:

{
“return”: {
“status”: 200,
“message”: “تایید شد”
},
“entries”: [
{
“messageid”: 1,
“message”: “این پیامک از زیرساخت ارسال پیامک نجوا ارسال شده است.“,
“status”: 1,
“statustext”: “در صف ارسال”,
“sender”: “90000123“,
“receptor”: “09120000000“,
“date”: 1706619709,
“cost”: 1000
},
{
“messageid”: 2,
“message”: “این پیامک از زیرساخت ارسال پیامک نجوا ارسال شده است.“,
“status”: 1,
“statustext”: “در صف ارسال”,
“sender”: “90000123“,
“receptor”: “09120000001“,
“date”: 1706619709,
“cost”: 1000
},
{
“messageid”: 3,
“message”: “این پیامک از زیرساخت ارسال پیامک نجوا ارسال شده است.“,
“status”: 1,
“statustext”: “در صف ارسال”,
“sender”: “90000123“,
“receptor”: “09120000002“,
“date”: 1706619709,
“cost”: 1000
} ]
}

ارسال پیامک نظیر به نظیر

کاربرد این متد ارسال پیامک دسته‌ای به صورت نظر به نظر (متن ارسالی برای هر مخاطب متفاوت باشد) است. در این متد می‌توانید حداکثر به ۱۰۰۰۰ نفر در یک درخواست پیامک ارسال کنید.

ساختار URL این متد:

باید از متد POST برای ارسال به این endpoint استفاده کنید.

https://sms.najva.com/v2/sms/send-p2p

پارامتر‌های ورودی:

پارامتر	نوع	تایپ	توضیحات
receptor	اجباری	String	شماره گیرندگان پیام را مشخص می‌کند. به صورت لیستی از شماره‌ها می‌باشد.
message	اجباری	String	متن پیام ارسالی، این متن حتما باید به فرمت URL Encode انکود شده باشد.
sender	اختیاری	String	شماره خط ارسال‌کننده پیام،‌ در صورت خالی بودن، خط پیش فرض انتخاب خواهد شد.

پارامتر‌های خروجی:

پارامتر	تایپ	توضیحات
messageid	Long	شناسه یکتای پیامک
message	String	متن پیامک ارسالی
status	Integer	وضعیت ارسال پیامک
statustext	String	متن توضیح وضعیت ارسال پیامک
sender	String	شماره فرستنده
receptor	String	شماره گیرنده
date	UnixTime	زمان ارسال پیامک
cost	Integer	هزینه پیامک

نکات:

برای اطلاع از وضعیت پیامک به جدول وضعیت پیامک‌ها در انتهای مستند مراجعه نمایید.
محدودیت تعداد دریافت کننده‌ها ۱۰۰۰۰ نفر است.

جدول خطاها:

کد خطا	توضیح
۴۰۰	پارارمتر‌های ورودی صحیح نیستند.
۴۱۴	تعداد دریافت کننده‌ها بیش از ۱۰۰۰۰ عدد است.
۴۱۸	اعتبار حساب شما کافی نیست.

نمونه درخواست ورودی:

{
“sender”: “90000123”,
“messages”: [
{
“message”: “پیامک 1”,
“receiver”: “09120000000”
},
{
“message”: “پیامک 2”,
“receiver”: “09120000001”
},
{
“message”: “پیامک 3”,
“receiver”: “09120000002”
}
]
}

نمونه پاسخ خروجی:

{
“return”: {
“status”: 200,
“message”: “تایید شد”
},
“entries”: [
{
“messageid”: 1,
“message”: “پیامک 1“,
“status”: 1,
“statustext”: “در صف ارسال”,
“sender”: “90000123“,
“receptor”: “09120000000“,
“date”: 1706619709,
“cost”: 1000
},
{
“messageid”: 2,
“message”: “پیامک 2“,
“status”: 1,
“statustext”: “در صف ارسال”,
“sender”: “90000123“,
“receptor”: “09120000001“,
“date”: 1706619709,
“cost”: 1000
},
{
“messageid”: 3,
“message”: “پیامک 3“,
“status”: 1,
“statustext”: “در صف ارسال”,
“sender”: “90000123“,
“receptor”: “09120000002“,
“date”: 1706619709,
“cost”: 1000
} ]
}

دریافت وضعیت ارسال

پیامک‌ها بعد از ارسال از طریق وب سرویس، وضعیت در صف خواهند داشت، و سپس به مخابرات ارسال خواهند شد و وضعیت ارسال به مخابرات را خواهند گرفت. سپس به صورت پیوسته وضعیت آنها کنترل می‌شود تا به وضعیت نهایی در سیستم برسند.

از این متد برای کنترل وضعیت تحویل Delivery پیامک استفاده کنید. برای استفاده از این متد باید شناسه یکتای هر پیامک messageid را که پس از ارسال پیامک در خروجی دریافت کرده‌اید را به عنوان پارامتر ورودی ارسال کنید.
در هر بار اجرای این متد می‌توانید وضعیت حداکثر 1000 پیامک را دریافت کنید.

ساختار URL این متد:

باید از متد POST برای ارسال به این endpoint استفاده کنید.

https://sms.najva.com/v2/sms/status

پارامتر‌های ورودی:

پارامتر	نوع	تایپ	توضیحات
messageids	اجباری	List[Long]	لیست messageid هایی که وضعیت آنها را می‌خواهید.

پارامتر‌های خروجی:

پارامتر	تایپ	توضیحات
messageid	Long	شناسه یکتای پیامک
status	Integer	وضعیت ارسال پیامک
statustext	String	متن توضیح وضعیت ارسال پیامک

نکات:

برای مشاهده لیست کامل وضعیت پیام‌ها به انتهای مستند مراجعه نمایید.
در صورتی که شناسه پیامک messageid معتبر نباشد، مقدار فیلد status = 100 خواهد بود.

جدول خطاها:

کد خطا	توضیح
۴۰۰	پارارمتر‌های ورودی صحیح نیستند.
۴۱۴	تعداد messageId‌ها بیش از 1000 عدد است.

نمونه درخواست ورودی:

{
“messageids”: [
1,
2,
3
]
}

نمونه پاسخ خروجی:

{
“return”: {
“status”: 200,
“message”: “تایید شد”
},
“entries”: [
{
“messageid”: 1,
“status”: 10,
“statustext”: “رسیده به گیرنده”
},
{
“messageid”: 2,
“status”: 4,
“statustext”: “رسیده به مخابرات”
},
{
“messageid”: 3,
“status”: 100,
“statustext”: “شناسه پیامک نامعتبر است”
}
]
}

دریافت لیست پیامک‌های ارسالی اخیر

این endpoint در دست توسعه است و هنوز در دسترس نیست.

در صورتی که می‌خواهید اطلاعات پیامک ارسالی آخر خود را دریافت نمایید، از این متد استفاده نمایید.

در هر بار اجرای این متد می‌توانید وضعیت حداکثر ۲۰۰ پیامک را دریافت کنید.

ساختار URL این متد:

باید از متد GET برای درخواست به این endpoint استفاده کنید.

https://sms.najva.com/v2/sms/outbox

پارامتر‌های ورودی:

پارامتر	نوع	تایپ	توضیحات
page	اجباری	Integer	شماره‌ی صفحه‌ی مورد نظر (شروع از 0)
pageSize	اجباری	Integer	تعداد پیامک‌ها در پاسخ

پارامتر‌های خروجی:

پارامتر	تایپ	توضیحات
messageid	Long	شناسه یکتای پیامک
message	String	متن پیامک ارسالی
status	Integer	وضعیت ارسال پیامک
statustext	String	متن توضیح وضعیت ارسال پیامک
sender	String	شماره فرستنده
receptor	String	شماره گیرنده
date	UnixTime	زمان ارسال پیامک
cost	Integer	هزینه پیامک

جدول خطاها:

کد خطا	توضیح
400	پارارمتر‌های ورودی صحیح نیستند.

نمونه درخواست ورودی:

https://sms.najva.com/v2/{API-KEY}/sms/outbox

نمونه پاسخ خروجی:

{
“return”: {
“status”: 200,
“message”: “تایید شد”
},
“entries”: [
“totalMessages”: 1000,
“page”: 0
{
“messageid”: 1234,
“message”: “سرویس ارسال پیامک نجوا”,
“status”: 1,
“statustext”: “در صف ارسال”,
“sender”: “10004346”,
“receptor”: “09120000000”,
“date”: 1706619709,
“cost”: 100
},
{
“messageid”: 4321,
“message”: “سرویس ارسال پیامک نجوا”,
“status”: 1,
“statustext”: “در صف ارسال”,
“sender”: “10004346”,
“receptor”: “09120000001”,
“date”: 1706619709,
“cost”: 100
}
]
}

وب‌هوک

برای دریافت گزارش‌ها از طریق callback بایست در بخش تنظیمات پیامک پنل نجوا آدرس endpoint و متد ارسال درخواست وب‌هوک از میان متد‌های GET و POST، تعیین شود.

پس از آن، به ازای هر تغییر در وضعیت پیامک ارسالی، درخواستی برای endpoint معرفی شده توسط شما ارسال می‌شود. در حال حاضر، درخواست وب‌هوک تنها یک بار ارسال می‌شود (در صورتی که status مناسب توسط endpoint بازگردانده نشود، دوباره درخواست وب‌هوک ارسال نمی‌شود)

در درخواستی که از طرف نجوا به endpoint شما ارسال می‌شود، دو پارامتر زیر وجود دارند(در body درخواست):

messageid: که آیدی پیام ارسالی را مشخص می‌کند
status: که وضعیت پیام ارسالی را نشان می‌دهد. (طبق جدول پیوست شده)

نمونه‌ پیام ارسالی:

{
“messageid”: 1234,
“status”: 10,
}

جدول وضعیت پیا‌‌‌م‌ها

کد وضعیت	توضیحات
1	در صف ارسال
2	زمانبندی شده
4	ارسال شده به مخابرات
6	خطا در ارسال پیام به سرشماره مشخص شده
10	پیامک تحویل گیرنده پیام شده است
11	در تحویل پیامک مشکلی رخ داده است، از دسترس بودن مخاطب و یا خاموش بودن گوشی آن از جمله دلایل این وضعیت است.
13	ارسال پیامک لغو شده است.
14	گیرنده دریافت این پیامک را بلاک کرده است. ممکن است سرشماره یا پیامک‌های تبلیغاتی توسط گیرنده بلاک شده باشد. هزینه‌ی این پیامک به حساب شما باز میگردد.
100	شناسه پیامک نامعتبر است.

مستندات وب‌سرویس هوشمند نجوا

وب‌سرویس هوشمند نجوا با هدف بهینه‌سازی هزینه و بازخورد از کاربران نهایی برای پیامک‌هایث تراکنشی ایجاد شده است. در واقع، این سرویس با ارسال پیام در کم‌هزینه‌ترین و بهترین کانال از نظر بازخورد بین کانال‌ پیام‌رسان‌ها و پیامک، باعث می‌شود:

کاربران نهایی کسب‌وکارها در کانالی که بیشترین تعامل را با آن دارند پیام کسب‌وکار را دریافت کنند.
برای ارسال هر پیام از سمت کسب‌وکار به سمت مشتری نهایی، ابتدا کم‌هزینه‌ترین کانال بررسی شده و پیام در ادامه به سراغ کانال‌های پرهزینه هدایت می‌شود. در نتیجه این فرآیند، هزینه کلی هر پیام کاهش می‌یابد.

راز هویت در تمام endpoint ها

برای احراز هویت در تمامی endpoint‌ها، با استفاده از توکن دریافت شده در صفحه‌ی تنظیمات (API TOKEN)، این توکن را در قالب هدر (header) زیر در تمامی درخواست‌ها ارسال نمایید.

محتوا	نام هدر
Bearer <API_TOKEN>	Authorization

ارسال پیامک به مخاطب خاص

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

ساختار URL این متد:

باید از متد POST برای ارسال به این endpoint استفاده کنید.

https://sms.najva.com/v3/sms/send

پارامتر‌های ورودی:

پارامتر	نوع	تایپ	توضیحات
receptor	اجباری	String	شماره گیرنده پیام را مشخص می‌کند.
message	اجباری	String	متن پیام ارسالی
sender_map.sms	اجباری	String	شماره خط ارسال‌کننده پیام
sender_map.rubika	اختیاری	String	توکن بات روبیکای ارسال کننده پیام
sender_map.bale	اختیاری	String	آیدی بازوی بله

پارامتر‌های خروجی:

پارامتر	تایپ	توضیحات
messageid	Long	شناسه یکتای پیامک
message	String	متن پیامک ارسالی
status	Integer	وضعیت ارسال پیامک
statustext	String	متن توضیح وضعیت ارسال پیامک
receptor	String	شماره گیرنده
costmap.rubika	Integer	هزینه پیام در روبیکا (در صورتی که از روبیکا استفاده کرده باشید)
costmap.bale	Integer	هزینه پیام در بله (در صورتی که از بله استفاده کرده باشید)
costmap.sms	Integer	هزینه پیام در پیامک

نکات:

برای اطلاع از وضعیت پیامک به جدول وضعیت پیام‌ها در انتهای مستند مراجعه نمایید.
هنگامی که یک sender_map را تعریف می‌کنید، ارسال کننده‌ی پیامک اجباری است و حداقل یکی از ارسال کننده‌های بله یا روبیکا نیز اجباری هستند. می‌توانید هر دوی آن‌ها را نیز مشخص کنید که در این صورت اولویت اول با روبیکا و اولویت دوم با بله می‌باشد.

جدول خطاها:

کد خطا	توضیح
۴۰۰	پارارمتر‌های ورودی صحیح نیستند.
۴۱۸	اعتبار حساب شما کافی نیست.

نمونه درخواست ورودی:

درخواست باید به فرمت زیر در body ارسال شود.

{

“message”: “تست از سرویس هوشمند ارسال پیامک نجوا“,

“receiver”: “09120000000“,

“sender_map”: {

“rubika”: “<rubika_token_id>“,

“bale”: “<bale_bot_id>“,

“sms”: “90000“

}

نمونه پاسخ خروجی:

{
“return”: {
“status”: 200,
“message”: “تایید شد”
},
“entries”: [
{
“messageid”: 1,
“message”: “تست از سرویس هوشمند ارسال پیامک نجوا“,
“status”: 1,
“statustext”: “در صف ارسال”,
“receptor”: “09120000000“,

“cost_map”: {

“rubika”: 80,

“sms”: 104,

“bale”: 80,

}
},

]

}

جدول وضعیت پیا‌‌‌م‌ها

کد وضعیت	توضیحات
1	در صف ارسال
2	زمانبندی شده
4	ارسال شده به مخابرات
6	خطا در ارسال پیام به سرشماره مشخص شده
10	پیامک تحویل گیرنده پیام شده است
11	در تحویل پیامک مشکلی رخ داده است، از دسترس بودن مخاطب و یا خاموش بودن گوشی آن از جمله دلایل این وضعیت است.
13	ارسال پیامک لغو شده است.
14	گیرنده دریافت این پیامک را بلاک کرده است. ممکن است سرشماره یا پیامک‌های تبلیغاتی توسط گیرنده بلاک شده باشد. هزینه‌ی این پیامک به حساب شما بازمی‌گردد.
100	شناسه پیامک نامعتبر است.

مستندات فنی سرویس پوش‌نوتیفیکیشن

مستندات دریافت توکن کاربران

مستندات ارسال پوش

نمونه درخواست ورودی:

نمونه پاسخ خروجی:

نمونه درخواست ورودی:

نمونه پاسخ خروجی:

مستندات پیاده‌سازی پوش در PWA

۱. الزامات اولیه

۲. ایجاد فایل manifest.json

۳. درج پیوند فایل مانیفست در HTML

۴. پیکربندی افزونه next-pwa

مستندات فنی سرویس پیامک

ساختار URL این متد:

پارامتر‌های ورودی:

پارامتر‌های خروجی:

نکات:

جدول خطاها:

نمونه درخواست ورودی:

نمونه پاسخ خروجی:

ارسال با قالب از پیش‌تعریف‌شده پیامک

ساختار URL این متد:

پارامتر‌های ورودی:

پارامتر‌های خروجی:

نکات:

جدول خطاها:

نمونه درخواست ورودی:

نمونه پاسخ خروجی:

جدول وضعیت پیا‌‌‌م‌ها

دریافت وضعیت ارسال

ساختار URL این متد:

پارامتر‌های ورودی:

پارامتر‌های خروجی:

نکات:

جدول خطاها:

نمونه درخواست ورودی:

نمونه پاسخ خروجی:

دریافت وضعیت به وسیله localId

ساختار URL این متد:

پارامتر‌های ورودی:

پارامتر‌های خروجی:

نکات:

جدول خطاها:

نمونه درخواست ورودی:

نمونه پاسخ خروجی:

انتخاب پیامک

ساختار URL این متد:

پارامتر‌های ورودی:

پارامتر‌های خروجی:

نکات:

جدول خطاها:

نمونه درخواست ورودی:

نمونه پاسخ خروجی:

لیست ارسال‌های پیامک

ساختار URL این متد:

پارامتر‌های ورودی:

پارامتر‌های خروجی:

نکات:

جدول خطاها:

نمونه درخواست ورودی:

نمونه پاسخ خروجی:

آخرین ارسال‌های پیامک

ساختار URL این متد:

پارامتر‌های ورودی:

پارامتر‌های خروجی:

نکات:

جدول خطاها:

نمونه درخواست ورودی:

نمونه پاسخ خروجی:

تعداد ارسال‌های پیامک

ساختار URL این متد:

پارامتر‌های ورودی:

پارامتر‌های خروجی:

نکات:

جدول خطاها:

نمونه درخواست ورودی:

نمونه پاسخ خروجی:

انصراف از ارسال پیامک

ساختار URL این متد:

پارامتر‌های ورودی: