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

توضیحات اولیه

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

توجه:
تمامی API‌های نجوا باید از سمت سرور صدا زده شوند. به دلیل این که تمامی این API ها token-base هستند، الزامی است که از سمت سرور API ها صدا زده شوند.

دریافت توکن برای احراز هویت:

در نجوا به هر فرستنده یک token اختصاص داده شده است. و سیستم نجوا از جمله API‌های آن کاربر را تنها از طریق این token می‌شناسند. لذا ضروری است که این token را از قسمت مشخصات API‌در پنل کاربری خود دریافت نمایید. همچنین در این صفحه برای هر یک از وبسایت‌ها یا اپلیکیشن‌های شما یک api-key‌ نوشته شده است. که این api-key همان شناسه یکتای وب‌سایت شماست و در توضیح API  ها که در زیر آمده است هر جا api-key‌آمده است منظور همینی است که در صفحه ی مشخصات API موجود است.

API ارسال نوتیفیکیشن برای اعضای یک وب‌سایت یا اپلیکیشن

توضیحات:

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

مثال:

در زیر یک نمونه ورودی و خروجی این API‌ آورده شده است:

URL: https://app.najva.com/api/v1/notifications/
HTTP-Method: POST
HTTP-Headers:
	Content-Type: application/json
	Authorization: Token <YOUR_TOKEN>

{

"api_key": <YOUR_API_KEY>,
"title": "title",
"body": "body",
"onclick_action": "<YOUR_ACTION>",
"url": "http://example.com",
"content": "some content",
"icon": "http://example.com/static/icon.png",
"image": "http://example.com/static/img.png",
"sent_time": "2018-12-04T12:00:00",
"segments_include": [1, 22],
"segments_exclude": [12],
"one_signal_enabled": true,
"one_signal_accounts": [21, 102]
}

با توجه به این که به چه صورت API‌ را صدا زده باشید یکی از حالت های زیر اتفاق می‌افتد:

ردیف status-code Body
1 200 {
“detail”: “notification created successfully!”
}
2 401 {
“detail”: “unauthorized”
}
3 403 {
“detail”: “you are not owner of this website”
}
4 404 {
“detail”: “user with this Token does not exists”
}

تمامی فیلد‌هایی که به عنوان ورودی به API‌ داده می‌شود در جدول زیر به صورت کامل توضیح داده شده است:

important-note description required value-type filed
این شناسه به صورت اجباری باید ارسال شود؛ در غیر این صورت اطلاعات ارسالی شما توسط نجوا پذیرفته نمی‌شود. این همان شناسه یکتای و‌ب‌سایت یا اپلیکیشن شماست که می‌توانید از قسمت api ها در پنل خود آن را دریافت کنید. yes uuid api_key
این فیلد اجباری است. اگر یک نوتیفیکیشن عنوان نداشته باشد ارسال نمی‌شود. عنوان نوتیف ارسالی با این فیلد مقدار می‌گیرد. رشته‌ای که به این فیلد نسبت داده می‌شود باید حداکثر ۱۰۰ کاراکتر باشد. yes string title
این فیلد اجباری است. اگر یک نوتیفیکیشن بدنه نداشته باشد ارسال نمی‌شود. توضیح یا بدنه نوتیف ارسالی با این فیلد مقدار می‌گیرد. رشته‌ای که به این فیلد نسبت داده می‌شود باید حداکثر ۲۰۰ کاراکتر باشد. yes string body
در صورتی که این فیلد از سمت شما ارسال نشود به صورت دیفالت برابر با

open-link

در نظر گرفته می شود.

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

Open-link: باز کردن لینکی که در فیلد url داده شده است.

Open-sms: باز کردن صفحه sms با شماره‌ای که در فیلد url داده شده است و با متن پیش فرضی که در فیلد content داده شده است.

Open-call: باز کردن صفحه شماره گیر تلفن همراه با شماره‌ای که در فیلد url داده شده است.

Open-app: باز کردن اپلیکیشن شما (همان اپلیکیشنی که sdk را در آن قرار داده‎‌اید.

Open-activity: باز کردن اکتیویتی‌ای که در فیلد url داده شده است.

Open-telegram-channel: باز کردن کانال تلگرامی که id آن در فیلد url وارد شده است.

Join-telegram-channel: اضافه کردن کاربر به کانال تلگرامی که آدرس آن در فیلد url وارد شده است.

no string onclick_action
این فیلد اجباری است. این فیلد مقصد نهایی کاربر پس از کلیک روی نوتیف را مشخص می‌کند. که مثلا میتواند آدرس سایت خود شما باشد. yes string url
این فیلد تنها زمانی استفاده می شود که شما حالت باز شدن صفحه اس ام اس را انتخاب کرده باشید. و مقدار این فیلد به عنوان نوشته پیش فرض اس ام اس در نظر گرفته میشود. false string content
در صورتی که این فیلد ارسال نشود از آیکن وبسایت شما که در پنل ثبت کرده اید استفاده می‌شود. این فیلد آدرس url یک فایل عکس است که به عنوان آیکون نوتیفیکیشن تنظیم می‌شود. که در مثال بالا نمونه آن آورده شده است. no string icon
این فیلد آدرس url یک فایل عکس است که به عنوان عکس بزرگ نوتیفیکیشن تنظیم می‌شود. که در مثال بالا نمونه آن آورده شده است. no string image
این فیلد زمان ارسال نوتیف را مشخص می‌کند. و فرمت آن بصورت زیر است:

“2018-12-05T13:00:00”

yes string sent_time
لیست شناسه سگمنت‌های دربرگرفته شده در این فیلد قرار می‌گیرند. در صورتی که این فیلد برابر با لیست خالی باشد برای تمام کاربرانی که مستثنی نشده اند ارسال می‌شود. no List of integers segments_include
لیست شناسه سگمنت‌های مستثنی شده در این فیلد قرار می‌گیرند. no List of integers segments_exclude
اگر مایل باشید این نوتیف برای کاربران وان سیگنالی خود نیز ارسال شود باید این فیلد را برابر با true‌ قرار دهید. درغیر این صورت مقدار آن را false‌ قرار دهید. yes boolean one_signal_enabled

API ارسال نوتیفیکیشن برای کاربران خاص با استفاده از توکن کاربران وبسایت یا اپلیکیشن

توضیحات:

اگر تابع همگام‌سازی کاربران خود با کاربران نجوا را که در بخش راهنمای راه‌اندازی sdk-android و راهنمای وب پوش توضیح داده شده است پیاده سازی کرده باشید می‌توانید برای کاربران خود با استفاده از توکن آن‌ها نوتیفیکیشن ارسال کنید. مزیت این روش این است که می‌توانید به صورت کاملا کاستومایز شده برای کاربران خود نوتیفیکیشن ارسال کنید.

مثال:

در زیر یک نمونه ورودی و خروجی این API‌ آورده شده است:

URL: https://app.najva.com/notification/api/v1/notifications/
HTTP-Method: POST
HTTP-Headers:
Content-Type: application/json
Authorization: Token <YOUR_TOKEN>
{
"api_key": <YOUR_API_KEY>,
"subscriber_tokens": [TOKEN1, TOKEN2, ...],
"title": "title",
"body": "body",
"onclick_action": "<YOUR_ACTION>",
"url": "http://example.com",
"content": "some content",
"icon": "https://images.pexels.com/photos/236047/pexels-photo-236047.jpeg?cs=srgb&dl=clouds-cloudy-countryside-236047.jpg&fm=jpg",
"image": "https://images.pexels.com/photos/236047/pexels-photo-236047.jpeg?cs=srgb&dl=clouds-cloudy-countryside-236047.jpg&fm=jpg",
"sent_time": "2019-01-07T12:00:00"
  }
 

با توجه به این که به چه صورت API‌ را صدا زده باشید یکی از حالت های زیر اتفاق می‌افتد:

ردیف status-code Body
1 201 {
“result”: “Notification is created successfully.”,
“count”: 2,
“details”: {
“title”: “title”,
“body”: “body”,
“url”: “http://example.com”,
“icon”: “/static/media/upload/icon_uploads/13946ba7-0c0a-47ae-8fc1-012e5c83e637.jpeg”,
“image”: “/static/media/upload/icon_uploads/416380cb-e530-48a7-8184-29f77890855e.jpeg”,
“sent_time”: “2019-01-07T12:00:00”,
}
}
2 400 {
“result”: “Passed data is invalid.”,
“details”: {
“api_key”: [
“این فیلد لازم است.”
],
“subscriber_tokens”: [
“این فیلد لازم است.”
],
“title”: [
“این فیلد لازم است.”
],
“body”: [
“این فیلد لازم است.”
],
“url”: [
“این فیلد لازم است.”
],
“sent_time”: [
“این فیلد لازم است.”
]
}
}
3 403 {
“detail”: “Authentication credentials were not provided.”
}

تمامی فیلد‌هایی که به عنوان ورودی به API‌ داده می‌شود در جدول زیر به صورت کامل توضیح داده شده است:

important-note description required value-type field
این شناسه به صورت اجباری باید ارسال شود؛ در غیر این صورت اطلاعات ارسالی شما توسط نجوا پذیرفته نمی‌شود. این همان شناسه یکتای و‌ب‌سایت یا اپلیکیشن شماست که می‌توانید از قسمت api ها در پنل خود آن را دریافت کنید. yes uuid api_key
اگر این فیلد یک لیست خالی باشد نوتیفیکیشن برای کسی ارسال نمی‌شود. این فیلد لیست شناسه کاربران شماست که باید ارسال شود. و نوتیفیکیشن تنها برای همین کاربران شما ارسال می‌شود. yes List of uuid subscriber_tokens
این فیلد اجباری است. اگر یک نوتیفیکیشن عنوان نداشته باشد ارسال نمی‌شود. عنوان نوتیف ارسالی با این فیلد مقدار می‌گیرد. رشته‌ای که به این فیلد نسبت داده می‌شود باید حداکثر ۱۰۰ کاراکتر باشد. yes string title
این فیلد اجباری است. اگر یک نوتیفیکیشن بدنه نداشته باشد ارسال نمی‌شود. توضیح یا بدنه نوتیف ارسالی با این فیلد مقدار می‌گیرد. رشته‌ای که به این فیلد نسبت داده می‌شود باید حداکثر ۲۰۰ کاراکتر باشد. yes string body
در صورتی که این فیلد از سمت شما ارسال نشود به صورت دیفالت برابر با open-link در نظر گرفته می شود. این فیلد مشخص می کند که پس از کلیک روی نوتیف چه اکشن‌ای رخ دهد. این فیلد می‌تواند یکی از مقادیر زیر را داشته باشد:

Open-link: باز کردن لینکی که در فیلد url داده شده است.

Open-sms: باز کردن صفحه sms با شماره‌ای که در فیلد url داده شده است و با متن پیش فرضی که در فیلد content داده شده است.

Open-call: باز کردن صفحه شماره گیر تلفن همراه با شماره‌ای که در فیلد url داده شده است.

Open-app: باز کردن اپلیکیشن شما (همان اپلیکیشنی که sdk را در آن قرار داده‎‌اید.

Open-activity: باز کردن اکتیویتی‌ای که در فیلد url داده شده است.

Open-telegram-channel: باز کردن کانال تلگرامی که id آن در فیلد url وارد شده است.

Join-telegram-channel: اضافه کردن کاربر به کانال تلگرامی که آدرس آن در فیلد url وارد شده است.

no string onclick_action
این فیلد اجباری است. این فیلد مقصد نهایی کاربر پس از کلیک روی نوتیف را مشخص می‌کند. که مثلا میتواند آدرس سایت خود شما باشد. yes string url
این فیلد تنها زمانی استفاده می شود که شما حالت باز شدن صفحه اس ام اس را انتخاب کرده باشید. و مقدار این فیلد به عنوان نوشته پیش فرض اس ام اس در نظر گرفته میشود. false string content
در صورتی که این فیلد ارسال نشود از آیکن وبسایت شما که در پنل ثبت کرده اید استفاده می‌شود. این فیلد آدرس url یک فایل عکس است که به عنوان آیکون نوتیفیکیشن تنظیم می‌شود. که در مثال بالا نمونه آن آورده شده است. no string icon
این فیلد آدرس url یک فایل عکس است که به عنوان عکس بزرگ نوتیفیکیشن تنظیم می‌شود. که در مثال بالا نمونه آن آورده شده است. no string image
این فیلد زمان ارسال نوتیف را مشخص می‌کند. و فرمت آن بصورت زیر است:

“2018-12-05T13:00:00”

yes string sent_time

API دریافت شناسه‌های تمامی سگمنت‌های ساخته شده در پنل نجوا

توضیحات:

برای این که در API ارسال نوتیف بتوانید از سگمنت‌های خود استفاده کنید باید شناسه آن‌ها را در اختیار داشته باشید. به همین منظور می‌توانید از این API استفاده کرده و این شناسه‌ها را دریافت نمایید.

مثال:

در زیر یک نمونه ورودی و خروجی این API‌ آورده شده است:

URL: https://app.najva.com/api/v1/websites/<website-api-key>/segments/
HTTP-Method: GET
HTTP-Headers:
            Content-Type: application/json
            Authorization: Token <YOUR_TOKEN>

نکته: در url بالا منظور از < website-api-key > همان api-key وب‌سایت است که از پنل نجوا می‌توانید دریافت نمایید.

با توجه به این که به چه صورت API‌ را صدا زده باشید یکی از حالت های زیر اتفاق می‌افتد:

ردیف status-code Body
1 200 [
 {
   “id”: 2,
   “name”: “segment1”,
   “human_readable_name”: “مشترکینی که آخرین کلیک‌شان در ۶ ساعت اخیر بوده است.”,
   “subsriber_count”: 100
 }
]
2 401 {
 “detail”: “unauthorized”
}
3 403 {
 “detail”: “you are not owner of this website”
}
4 404 {
 “detail”: “user with this Token does not exists”
}

نکته: پاسخ این API به صورت لیستی از اطلاعات سگمنت‌های این وبسایت است که شامل اطلاعاتی نظیر (id, name, human_readable_name, subscriber_count) می‌باشد. در API ارسال نوتیف باید id‌ ای که در پاسخ این API دریافت شده است را در قالب لیست ارسال نمایید.

API دریافت شناسه‌های تمامی اکانت‌های onesignal ساخته شده در پنل نجوا

توضیحات:

برای این که در API ارسال نوتیف بتوانید از اکانت‌های onesignal خود استفاده کنید باید شناسه آن‌ها را در اختیار داشته باشید. به همین منظور می‌توانید از این API استفاده کرده و این شناسه‌ها را دریافت نمایید.

مثال:

در زیر یک نمونه ورودی و خروجی این API‌ آورده شده است:

URL: https://app.najva.com/api/v1/one-signals/
HTTP-Method: GET
HTTP-Headers:
	Content-Type: application/json
	Authorization: Token <YOUR_TOKEN>

با توجه به این که به چه صورت API‌ را صدا زده باشید یکی از حالت های زیر اتفاق می‌افتد:

ردیف status-code Body
۱ 200 [
 {
   “id”: 22,
   “name”: “one-signal-1”
 },
 {
   “id”: 45,
   “name”: “one-signal-2”
 }
]
۲ 401 {
 “detail”: “unauthorized”
}
۳ 404 {
 “detail”: “user with this Token does not exists”
}

نکته: پاسخ این API به صورت لیستی از اطلاعات اکانت‌های one-signal است که شامل اطلاعاتی نظیر (id, name) می‌باشد. در API ارسال نوتیف باید id‌ ای که در پاسخ این API دریافت شده است را در قالب لیست ارسال نمایید.