ارتباط، زندگی، سرگرمی

توسعه‌دهندگان سروش پلاس

راهنمای استفاده از مستربات سروش پلاس

ارایه خدمات ارزش افزوده و سرویس‌های متنوع بر بستر پیام‌رسان سروش پلاس در جذاب‌تر شدن این پیام‌رسان، تأثیر چشمگیری دارد.
این مهم تنها با کمک توسعه‌دهندگان عزیز صورت خواهد پذیرفت. از این‌رو بستر توسعه سروش پلاس را با استفاده از «مستر بات سروش پلاس» برای شما علاقمندان فراهم آوردیم تا در کنار هم خدمات متنوعی را برای کاربران سروش پلاس فراهم کنیم.
در ادامه می‌توانید از راهنمای توسعه بات سروش پلاس استفاده نمایید.

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

متن
عکس
فیلم
صدا
عکس متحرک
صدای ضبط شده
موقعیت جغرافیایی
و تمامی فرمتهای مجاز در سرور سروش پلاس

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

در این بخش شما توسعه‌دهنده عزیز می‌توانید نحوه ساخت بات در سروش پلاس را به سادگی آموزش ببینید.

در قدم اول با عضویت در پیام‌رسان سروش پلاس و مراجعه به ربات مدیریت بات‌ها به آدرس mrbot@ مراحل پیاده‌سازی بات خود را آغاز خواهید کرد.

انتخاب گزینه‌ی ایجاد بات و ثبت شناسه‌ی بات. رعایت موارد بشرح ذیل ضروری‌ست:
- حداقل تعداد حروف هر شناسه می‌بایست ۳ حرف باشد.
- حروف استفاده شده می‌بایست انگلیسی باشد.
- نام انتخابی می‌بایست یکتا باشد که در زمان انتخاب نام در «مستر بات» این مورد در لحظه بررسی شده و نتیجه به شما اطلاع داده خواهد شد.
دریافت توکن و ذخیره‌ی آن
ثبت اطلاعات بات که شامل، نام نمایشی بات، پیام آغازین، اطلاعات پروفایل بات و عکس بات می‌باشد.

توسعه‌دهندگان برای برقراری ارتباط و دریافت پیام‌های کاربران می‌بایست به این طریق ارتباط خود را برقرار کنند:

                Version 1 =  [GET] : https://bot.splus.ir/[TOKEN]/getMessage
OR
Version 2 =  [GET] : https://bot.splus.ir/v2/[TOKEN]/getMessage

مقدار TOKEN در ابتدای ثبت نام بات به شما داده شده است.
تفاوت نسخه ی شماره ۲ getMessage نسبت به نسخه ی ۱ آن در متد ارسال پیام HEALTH_CHECK میباشد این پیام شما را از وصل بودن بات به سرور مطلع کرده. از همین رو توصیه میشود از نسخه ی ۲ getMessage برای دریافت پیام استفاده کنید. توضیحات کاملتر این پیام در بخش ' اجزای پیام کاربران بات ' قابل مشاهده است.

نوع ارتباط از استاندارد (Server Sent Events (SSE پشتیبانی می‌کند، که در آن پس از برقراری اتصال با سرور بات، که آدرس آن در بالا آورده شد، ارتباط به صورت زنده باقی می‌ماند و پیام‌های دریافتی بات شما بر روی همین اتصال برای شما ارسال می‌شود. توجه داشته باشید که برای دریافت پیام نیازی به ارسال مجدد درخواست getMessage مانند روش long polling نبوده و در اولین تلاش برای دریافت پیام آن اتصال قطع نخواهد شد و پیام ها یک به یک به دست شما خواهد رسید. از مزیت روش SSE نسبت به روش قدیمی تر webhook میتوان به این موضوع اشاره کرد که شما دیگر برای دریافت پیام نیازی به داشتن آدرس معتبر نداشته و میتوانید فقط با اتصال به اینترنت پیام های خود را دریافت کرده و به آنها پاسخ دهید. توسعه دهندگان می‌بایست در زمان برقراری ارتباط یکی از دو مقدار زیر را در HTTP HEADER درخواست قرار دهند.

نمونه‌ی اول:

                Content-Type = application/stream+json
Accept = application/stream+json

نمونه‌ی دوم:

                Content-Type = text/event-stream
Accept = text/event-stream

نمونه درخواست getMessage با استفاده از curl:

			  curl https://bot.splus.ir/[TOKEN]/getMessage

نمونه درخواست با استفاده از openssl:

                openssl s_client -connect bot.splus.ir:443
 
GET /[TOKEN]/getMessage HTTP/1.1
host:bot.splus.ir
Content-Type : application/stream+json
Accept : application/stream+json

نمونه درخواست با استفاده از کتابخانه‌ی PHP:

			  <?php
require dirname(__FILE__) . '/../vendor/autoload.php';
$bot_token = 'your bot token';
$bot = new Soroush\Client($bot_token);
try {
$messages = $bot->getMessages();
foreach ($messages as $message) {
$data = $message->getData();
echo "New Message Received: ";
var_dump($data);
}
} catch (Exception $e) {
die($e->getMessage());
}

نمونه درخواست با استفاده از کتابخانه ی Python:

			  from sys import path
path.append('..')
from client import Client
bot_token = 'your bot token'
bot = Client(bot_token)
try:
   messages = bot.get_messages()
   for message in messages:
   print("New Message Received: " + str(message))
except Exception as e:
   print(e.args[0])

پیام ارسال شده به سمت شما در قالب JSON بوده و شامل موارد زیر می‌باشد که هرکدام به اختصار در جدول زیر توضیح داده شده است.

جدول ۱: همه فیلدهایی که در پیام کلاینت به بات ممکن است موجود باشد

	توضیحات	اجباری	نوع	نام
۱	ادرس فرستنده‌ی پیام	true	String	from
۲	محتوای داده‌ی ارسالی کاربر	true	String	body
۳	نوع محتوای ارسال شده که می‌تواند : START,STOP,TEXT , LOCATION , FILE , HEALTH_CHECK باشد .	true	Type	type
۴	زمان ارسال پیام بر اساس میلی ثانیه از 1970	true	String	time
۵	شناسه‌ی فایل اپلود شده در سروش پلاس	false	String	fileId
۶	نام فایل اپلود شده	false	String	fileName
۷	نوع فایل اپلود شده که می‌تواندIMAGE , VIDEO,GIF,PUSH_TO_TALK,ATTACHMENT باشد .	false	fileType	fileType
۸	حجم فایل اپلود شده	false	Double	fileSize
۹	ادرس فایل اپلود شده	false	String	fileUrl
۱۰	ادرس عکس بند انگشتی	false	String	thumbnailUrl
۱۱	میزان سایز عرض عکس	false	Double	imageWidth
۱۲	میزان سایز طول عکس	false	Double	imageHeight
۱۳	زمان ویدیو	false	Double	fileDuration
۱۴	میزان سایز عرض عکس بند انگشتی	false	Double	thumbnailWidth
۱۵	میزان سایز طول عکس بند انگشتی	false	Double	thumbnailHeight
۱۶	نام مخاطب ارسال شده	false	String	nickName
۱۷	ادرس عکس مخاطب ارسال شده	false	String	avatarUrl
۱۸	شماره‌ی تلفن مخاطب ارسال شده	false	Double	phoneNo
۱۹	عرض جغرافیایی	false	Double	latitude
۲۰	طول جغرافیایی	false	Double	longitude

نوع پیام (فیلد TYPE): محتوای ارسالی در این فیلد از نوع String بوده و می‌تواند یکی از مقادیر زیر باشد.

START: پیام آغاز به کار بات، که در زمان زدن دکمه ی شروع در صفحه ی بات به شما ارسال میشود.
STOP: پیام متوقف کردن بات، که در زمان زدن دکمه ی متوقف کردن بات به شما ارسال میشود.
TEXT: فقط شامل پیام متنی است. فیلد body حتما دارای مقدار است .
FILE: شامل فایل می‌باشد. فیلد‌های مربوط به فایل حتما دارای مقدار هستند و فیلد body نیز در صورت کپشن‌دار بودن فایل ارسال می‌شود.
LOCATION: شامل موقعیت جغرافیایی می‌باشد .
HEALTH_CHECK: پیام اطلاع از وصل بودن بات شما به سرور که هر ۵ دقیقه یکبار برای شما ارسال میشود. (در صورت عدم دریافت این پیام در زمانی بیش از ۵ دقیقه شما میبایست ارتباط خود با سرور را برای دریافت پیام مجددا وصل کنید)

نوع فایل (فیلد FileType): محتوای فایل ارسالی از نوع String بوده و می‌تواند یکی از نوع‌های زیر می‌تواند باشد:

IMAGE: تصویر
GIF: تصویر متحرک
VIDEO: فیلم
PUSH_TO_TALK: صدا (ویس)
CONTACT: مخاطب
ATTACHMENT: تمامی فایل‌هایی که جزو موارد بالا نباشند.

نوع پیام متنی (TYPE: START)

در صورتی که داده ی START در متغیر TYPE باشد، موارد زیر دارای مقدار می‌باشند.

جدول ۲: اجزای پیام، اگر پیام از نوع START باشد

	نمونه	نوع داده	داده
۱	user	String	from
۲	" "	String	body
۳	" 1505744054437"	String	time
۴	START	TYPE	type

مثال

                {
"from": "lJ1ddrR1YqyNgSRfUR_t9LSEbTO9JbXRDn1xGMgnkwma0OJXjw4h8IagAME",
"body": " ",
"type": "START",
"time": "1530348296947"
}

نوع پیام متنی (TYPE: STOP)

در صورتی که داده ی STOP در متغیر TYPE باشد، موارد زیر دارای مقدار می‌باشند.

جدول ۲: اجزای پیام، اگر پیام از نوع STOP باشد

	نمونه	نوع داده	داده
۱	user	String	from
۲	" "	String	body
۳	" 1505744054437"	String	time
۴	STOP	TYPE	type

مثال

                {
"from": "lJ1ddrR1YqyNgSRfUR_t9LSEbTO9JbXRDn1xGMgnkwma0OJXjw4h8IagAME",
"body": " ",
"type": "STOP",
"time": "1530348296947"
}

نوع پیام متنی (TYPE: HEALTH_CHECK)

در صورتی که داده ی HEALTH_CHECK در متغیر TYPE باشد، موارد زیر حتما دارای مقدار می‌باشند.

نوع پیام متنی (TYPE: TEXT)

در صورتی که داده ی TEXT در متغیر TYPE باشد، موارد زیر دارای مقدار می‌باشند.

جدول 2: اجزای پیام، اگر پیام از نوع HEALTH_CHECK باشد

	نمونه	نوع داده	داده
۱	MrBot	String	from
۲	" 1505744054437"	String	time
۳	HEALTH_CHECK	TYPE	type

مثال

                {
"from": "MrBot",
 "type":"HEALTH_CHECK",
"time":"1544991722877"
}

جدول ۲: اجزای پیام، اگر پیام از نوع TEXT باشد

	نمونه	نوع داده	داده
۱	user	String	from
۲	" SALAM "	String	body
۳	" 1505744054437"	String	time
۴	TEXT	TYPE	type

مثال

                {
"from": "lJ1ddrR1YqyNgSRfUR_t9LSEbTO9JbXRDn1xGMgnkwma0OJXjw4h8IagAME",
"body": " سلام ",
"type": "TEXT",
"time": "1530348296947"
}

نوع پیام فایل (TYPE: FILE)

در صورتی که داده ی FILE در متغیر TYPE باشد، موارد زیر دارای مقدار می‌باشند.

جدول ۳: اجزای پیام، اگر پیام از نوع FILE باشد

	نمونه	نوع داده	داده
۱	user	String	from
۲	"salam"	String	body
۳	" 1505744054437"	String	time
۴	FILE	TEXT , FILE , LOCATION	type
۵	"13235694"	String	fileId
۶	"user"	String	fileName
۷	IMAGE or VIDEO or …	IMAGE , VIDEO , GIF , PUSH_TO_TALK , ATTACHMENT	fileType
۸	"http://url"	String	fileUrl
۹	123.456	Double	fileSize

مقدار fileType می‌تواند به صورت زیر قرار بگیرد:

جدول ۳.۱: اجزای داده‌ی fileType

	نمونه	نوع داده	داده
۱	image.png	(Image files like : (.jpg , .png , .bmp	IMAGE
۲	video.mp4	(Video files like : (.mpg , .mp4, .3gp	VIDEO
۳	image.gif	(Gif images file : (.gif	GIF
۴	audio.amr	(Recorded sound file like : (.amr, .m4a, .aac	PUSH_TO_TALK
۵	text.pdf	All file type	ATTACHMENT

نوع پیام فایل حاوی عکس (fileType: IMAGE) یا تصویر متحرک (fileType: GIF)

در صورتی که مقدار fileType برابر IMAGE و یا GIF باشد متغیر‌های زیر نیز در کنار متغیر های جدول ۳ شامل مقدار هستند:

جدول ۳.۲: اجزای پیام، اگر فایل از نوع IMAGE یا GIF باشد

	نمونه	نوع داده	داده
۱	"http://image.png"	String	thumbnailUrl
۲	120.2	Double	imageWidth
۳	250.6	Double	imageHeight

مثال

                

{
    "from": "lJ1ddrR1YqyNgSRfUR_t9LSEbTO9JbXRDn1xGMgnkwma0OJXjw4h8IagAME",
    "body": " ",
    "type": "FILE",
    "time": "1530348016892",
    "fileId": "22f3a8e2509d48f3ec669963eb8fcaab0a5639bf.png",
    "fileName": "22f3a8e2509d48f3ec669963eb8fcaab0a5639bf.png",
    "fileType": "IMAGE",
    "fileSize": 376544,
    "fileUrl": "fe6exI5y960OYa8BOB5UfgZis7k4knrjmd-njP0wC2ThoAUi9-k0wVCkmPqurFmuODyxzSXDuN1E9wSe5AtkosCzyuD2URqxew5SjoKriyhC8ZRNYW7mWCYS--p1xpiHzns70ZEYeR_kkWRBkK4TP0DrC4agXBkqfJjpGK1bY2NjMwEhf2d1E9YzlPA-QEQqKptNkfWvWLdewcsUan2pRCwEkKPpTZgFUGCytr1gEP0gKvjiteQSpXRVKndYfJIpMTQn2uQe1Is9WNfdYggEHR8d9Hvy7cExf43KsNz-UuhWUpELbA55YiIzUvc",
    "thumbnailUrl": "V4DxQzw6jpDXpUebbyrzeytd6Jg96akyr5_dkR538wpYqIVKXtJyVADQSfKxE7osxhho_LIxDhDWExuUdnUXs2cLzFz-oaCLm2dcsudnTz0V9JhLOkhDSnldxnzdf2nzdv5ja9YeMGIekRmZd856l5RNB3UZVQajk19YN4ZOl5cBPJFlqP6WK-vY71EjkAZ9E5201zMo7vpk6sIQR7lO-wxjjPYxOQ14ZB5ABo6f-UeqsIWi-HZ5R16lo0WR3VFHZTqJAbXOq-08qeZ2nxAh7dE0-sVcqfj-S-1hhmeqZJxlQzkCpWKwmZdfbR4",
    "imageWidth": 698,
    "imageHeight": 411
}

نوع پیام فایل حاوی ویدئو (fileType: VIDEO)

در صورتی که مقدار fileType برابر VIDEO باشد متغیر‌های زیر نیز در کنار متغیر های جدول ۳ شامل مقدار هستند:

جدول ۳.۳: اجزای پیام، اگر فایل از نوع VIDEO باشد

	نمونه	نوع داده	داده
۱	720000	String	fileDuration
۲	"http://video.png"	String	thumbnailUrl
۳	120.0	Double	thumbnailWidth
۴	250.6	Double	thumbnailHeight

مثال

                
{
    "from": "lJ1ddrR1YqyNgSRfUR_t9LSEbTO9JbXRDn1xGMgnkwma0OJXjw4h8IagAME",
    "body": " ",
    "type": "FILE",
    "time": "1530348060448",
    "fileId": "59134719a84d68da6528d3908435d86c84335c98.mp4",
    "fileName": "PostSazBot1506080694.mp4",
    "fileType": "VIDEO",
    "fileSize": 158669,
    "fileUrl": "7U3eoysRgTUFatjZdt9Sgniond_LRxt1zTtN_HNvXvSTOMV-JI4Rt-WFY5MOPGv_Ialjr6lCJ2KeCRapz26pQj9gdnUQB0v6qPhhVO_zZhQBwteOkyG4l6Ahs2V_aAliCq7xI9NbIGEGSbW-jaaLHp3R0j6tQC8-040qMfsJGt9QcIOO53vzR3HmTarD17LbzKKqAdtjJccpcSohhsuzEDfjCtZYvE_yIzVEkdWdQl6ZRRUrbSlFZUEBbSeKBcW1hcjAZNH4hex6dMmstGWl62vBkfwZtcF7lhTfJ85yvrSUvWF5iMroFqaoQsc",
    "thumbnailUrl": "Q33H9PB7mNelwNgQwh8Vvy7RaKhDrUdfcA3LLynBNMu-PuNq4QGEedQasjEdGbWnBvsDUVyJJ512FSX8dp7YqproW2vwOCwTeBGCqUWPfCM9YgHyfn5RspnM68uGGquDPWCi9UqkZDdd32MIHhiUjMcM0d1Tr-SxG1ayYUlSKmO7xCGPC6KEiDIP5oIzqvFa8BPRhano_vSCMVGGMq7M3vH4I7q8GtkU55yVKARSVA9_tvyh9bAUn5S6GNpfmYs0JJLVLqV6UQeebIZZu12PSEJ0_lxvCNaLeWhV45SY_rw8Jzzye0bAuULHLUM",
    "fileDuration": 11400,
    "thumbnailWidth": 512,
    "thumbnailHeight": 512
}

نوع پیام فایل حاوی صدای ضبط شده (fileType: PUSH_TO_TALK)

در صورتی که مقدار fileType برابر PUSH_TO_TALK باشد متغیر زیر نیز در کنار متغیر های جدول ۳ شامل مقدار هست:

جدول ۳.۴: اجزای پیام، اگر فایل از نوع PUSH_TO_TALK باشد

	نمونه	نوع داده	داده
۱	720000	Double	fileDuration

مثال

                
{
    "from": "lJ1ddrR1YqyNgSRfUR_t9LSEbTO9JbXRDn1xGMgnkwma0OJXjw4h8IagAME",
    "body": " ",
    "type": "FILE",
    "time": "1530359924047",
    "fileId": "d58d07567153abfe77083c0057f093e610c2d1af.m4a",
    "fileName": "2018_5_30.m4a",
    "fileSize": 16149,
    "fileUrl": "hlrwMiCwwkJvSN9wuCQ4a1FL2LaAg0SXdAkNZSXQY8cRj2O3kJQuLJBLbMHODPXoJx0WZ2TKoQrRRk9UZu_g69gHIt7Aun27_dpY0vqFbeCNWcHPWPNd02278pNsSu9q_ JcKvFtenBi2nVHavKHxV3Z3Qj8tAFtmx53JUegricFEyorimYjawxgBGvTBOZ0yjwHiLnsN46R_EG8OiTPIj2tR9G1AKJzfLBKzNBf- SmzlA6JoHimhJA0aYkoi7f7T3B-hLPC4WDi5fLhW7D2hH68Lw4g62x2upPtOARQkJnYWkbEMMZg7xBFrNuI",
    "fileDuration": 2670
}

نوع پیام مکان (TYPE: LOCATION)

در صورتی که داده ی LOCATION در متغیر TYPE باشد، موارد زیر دارای مقدار می‌باشند.

جدول ۴: اجزای پیام، اگر پیام از نوع LOCATION باشد

	نمونه	نوع داده	داده
۱	user	String	from
۲	" 1505744054437"	String	time
۳	LOCATION	LOCATION	type
۴	35.6892	Double	latitude
۵	51.3890	Double	longitude

مثال

                
{
    "from": "lJ1ddrR1YqyNgSRfUR_t9LSEbTO9JbXRDn1xGMgnkwma0OJXjw4h8IagAME",
    "body": " ",
    "type": "LOCATION",
    "time": "1530360463987",
    "latitude": 35.705553132681416,
    "longitude": 51.35423647239804
}

توسعه‌دهندگان برای ارسال پیام به کاربران می‌بایست به این طریق ارتباط خود را برقرار کنند:

                [POST] : https://bot.splus.ir/[TOKEN]/sendMessage

مقدار TOKEN در ابتدای ثبت نام بات به شما داده شده است.

در صورت موفقیت‌آمیز بودن مقدار http status برگشتی 200 می‌باشد.

توسعه‌دهندگان می‌‌توانند در زمان برقراری ارتباط در HEADER HTTP مشخص کنند که نوع داده‌ی ارسالی به چه صورتی باشد. نوع داده می‌تواند به صورت XML یا JSON باشد. برای استفاده شما می‌بایست به صورت زیر اقدام کنید:

                    
Content-Type = Application/json or Application/xml
Accept = Application/json or Application/xml

نمونه درخواست ارسال پیام با استفاده از curl:

                        curl -XPOST -d '{"to":"mI06WMPeNi0glvTkx0CIEmWx98iBzc5qRQFy8oQws5k0OlMW7tjDCKOOsig","type":"TEXT","body":"Hi"}' -H 'Content-Type: application/json' -H 'Accept: application/json' https://bot.splus.ir/"TOKEN"/sendMessage

نوع پیام متنی (TYPE: TEXT)
نوع پیام فایل (TYPE: FILE)
نوع پیام تغییر کیبورد (TYPE: CHANGE)
کیبورد سفارشی (CUSTOM KEYBOARD)
- کلاس CustomKey

پیام ارسال شده از سمت شما باید در قالب JSON باشد و شامل بخشی از موارد زیر می‌باشد که هرکدام به اختصار در جدول زیر توضیح داده شده است.

جدول ۵: همه فیلدهایی که در پیام بات به کلاینت ممکن است موجود باشد.

	توضیحات	اجباری	نوع	نام
۱	آدرس گیرنده ی پیام	true	String	to
۲	محتوای داده ی ارسالی به کاربر	false	String	body
۳	نوع استفاده محتوای ارسالی که می‌تواند : BOT , CHANNEL باشد. (همچنین برای سازگاری با نسخه های قبل در صورت وجود نداشتن این مقدار، مقدار پیشفرض BOT در نظر گرفته می‌شود)	false	MajorType	majorType
۴	نوع محتوای ارسالی که می‌تواند : TEXT , LOCATION , FILE , KEYBOARD_CHANGE باشد.	true	Type	type
۵	زمان ارسال پیام بر اساس میلی ثانیه از 1970	false	String	time
۶	نام فایل آپلود شده	false	String	fileName
۷	نوع فایل آپلود شده که می‌تواندIMAGE ,VIDEO,GIF,PUSH_TO_TALK,ATTACHMENT باشد.	false	FileType	fileType
۸	حجم فایل آپلود شده	false	Double	fileSize
۹	ادرس فایل آپلود شده در سرور‌های سروش پلاس	false	String	fileUrl
۱۰	آدرس عکس بند انگشتی	false	String	thumbnailUrl
۱۱	میزان سایز عرض عکس	false	Double	imageWidth
۱۲	میزان سایز طول عکس	false	Double	imageHeight
۱۳	زمان ویدیو	false	Double	fileDuration
۱۴	میزان سایز عرض عکس بند انگشتی	false	Double	thumbnailWidth
۱۵	میزان سایز طول عکس بند انگشتی	false	Double	thumbnailHeight
۱۶	نام مخاطب ارسال شده	false	String	nickName
۱۷	آدرس عکس مخاطب ارسال شده	false	String	avatarUrl
۱۸	شماره ی تلفن مخاطب ارسال شده	false	Double	phoneNo
۱۹	عرض جغرافیایی	false	Double	latitude
۲۰	طول جغرافیایی	false	Double	longitude

ننوع استفاده ی پیام (MAJOR_TYPE: BOT)

برای ارسال پیام به بات نیازی به گذاشتن مقدار majorType نمیباشد ولی در صورت گذاشتن این فیلد مقدار آن باید BOT باشد که می‌باست جدول زیر شامل مقدار باشد :

جدول6: اجزای پیام، اگر پیام از نوع BOT باشد

	نمونه	نوع داده	داده
۱	user	String	to
۲	"salam"	String	body
۳	TEXT	TYPE	type

مثال

                        
{
    "to": "lJ1ddrR1YqyNgSRfUR_t9LSEbTO9JbXRDn1xGMgnkwma0OJXjw4h8IagAME",
    "type": "TEXT",
    "body": "سلام"
}

نوع استفاده ی پیام (MAJOR_TYPE: CHANNEL)

برای ارسال پیام به کانال شما میبایست مقدار majorType را CHANNEL قرار دهید و در فیلد to نیز لینک کانال را ارسال کنید که می‌باست جدول زیر شامل مقدار باشد :

جدول6: اجزای پیام، اگر پیام از نوع CHANNEL باشد

	نمونه	نوع داده	داده
۱	channelLink	String	to
۲	"salam"	String	body
۳	TEXT	TYPE	type
۴	CHANNEL	MajorType	majorType

مثال

                        
{
    "to": "lJ1ddrR1YqyNgSRfUR_t9LSEbTO9JbXRDn1xGMgnkwma0OJXjw4h8IagAME",
    "type": "TEXT",
    "body": "سلام"
	"majorType":"CHANNEL"
}

نوع پیام متنی (TYPE: TEXT)

برای ارسال TEXT می‌بایست جدول زیر شامل مقدار باشد:

جدول۶: اجزای پیام، اگر پیام از نوع TEXTباشد

	نمونه	نوع داده	داده
۱	user	String	to
۲	"salam"	String	body
۳	TEXT	TEXT	type

مثال

                        
{
    "to": "lJ1ddrR1YqyNgSRfUR_t9LSEbTO9JbXRDn1xGMgnkwma0OJXjw4h8IagAME",
    "type": "TEXT",
    "body": "سلام"
}

نوع پیام فایل (TYPE: FILE)

برای ارسال FILE می‌بایست جدول زیر شامل مقدار باشد:

جدول ۷: اجزای پیام، اگر پیام از نوع FILE باشد

	نمونه	نوع داده	داده
۱	user	String	to
۲	"salam"	String	body
۳	FILE	FILE	type
۴	"user"	String	fileName
۵	IMAGE or VIDEO or …	IMAGE , VIDEO , GIF , PUSH_TO_TALK , ATTACHMENT	fileType
۶	"http://url"	String	fileUrl
۷	123.456	Double	fileSize

در صورت انتخاب یکی از fileType‌ ها شما می‌بایست جدول مربوط به آن را نیز در کنار جدول ۷ ارسال کنید.

نوع پیام فایل حاوی عکس (fileType: IMAGE) یا تصویر متحرک (fileType: GIF)

جدول ۸: اجزای پیام، اگر فایل از نوع IMAGE یا GIF باشد

	نمونه	نوع داده	داده
۱	"http://image.png"	String	thumbnailUrl
۲	120.2	Double	imageWidth
۳	250.6	Double	imageHeight

مثال

                    
 {
    "to": "lJ1ddrR1YqyNgSRfUR_t9LSEbTO9JbXRDn1xGMgnkwma0OJXjw4h8IagAME",
    "type": "FILE",
    "fileType": "IMAGE",
    "fileSize": "18169",
    "fileName": "3.png",
    "imageWidth": "559",
    "imageHeight": "213",
    "fileUrl": "fGSU0Aaqbm8hvHM1HKw3M_F4R4MuLI6uBxHLYURcy0EaCkfqa42JWpVLjg6GPa4-AnwCl-FbcfV-7II2idYMc1nSElgWJn_piK02f5i8-ZFktWq2fas5WgqIERukMJ2cZQeIENAjbznBLGGB2PyP4XdIiMsHH2Ebb8hGsBVlDYq3LLuxNYpa1fy_3L_LHlmFdWO9UhP1spQEkJ1kQ3lXdc2TWNx0uJTXrdm9HwW2s6ktlqzgtFnMxk7764nE2xFlTeYGWMF8Pr8bvYTD9M NvVNQtQUITH2i6Cr5PIvogwjeM1kIY1aASV5x2t9I",
    "thumbnailUrl": "xwlfqqxXqAZaofly7XidbFFZFwifi1x1sHt2nyWfL_rbdKxtMKdO8RRhYTltzKWuIgA5b9ga4ciICxkg_xjYJS7MR_vs80vJd8BEzjKRBmn6kYc1lZ0wrO2uLnaI97as7XJd3T-wkcNpWeGdM3gZ6st5DoIhnM12C7YrJGmb-eYz-cMK5jVqIvC71c3pBvH5H3HszQh3RayxIbB2JeC1nTitdIzPat97PuahE8OPqyBh2X2VTSN0oIRKK9xhLVJNqeTCc3GnRUiElp8p65DeJHfF0Gnd03uY1k7xco1kvtDWmWv935vPHSuwwo_hsjWSlV9ZddC4FokmA _Iu9cB4oPpYTK0im3o_fDhSLOjtadJc317dOJ3j1OzKG37Fqovfpio Gzoom027vb68tyx6025RbSWrSNpFccw4lYkhuGlOfgJWv-lhQpBio0y0wyb6wJT-Jgr604mhyVVaeg3ToDk7a9y_BxnYdPHi5ecC0LZkb1TpzNKzTJmniIns"
}

نوع پیام فایل حاوی ویدئو (fileType: VIDEO)

جدول ۹: اجزای پیام، اگر فایل از نوع VIDEO باشد

	نمونه	نوع داده	داده
۱	720000	String	fileDuration
۲	"http://video.png"	String	thumbnailUrl
۳	120.0	Double	thumbnailWidth
۴	250.6	Double	thumbnailHeight

مثال

                    
 {
    "to": "lJ1ddrR1YqyNgSRfUR_t9LSEbTO9JbXRDn1xGMgnkwma0OJXjw4h8IagAME",
    "type": "FILE",
    "fileType": "VIDEO",
    "fileSize": "5095373",
    "fileDuration": "99010",
    "fileName": "ee33f066fad71ecb12e2e694c10ec5247313e90d.mp4",
    "thumbnailWidth": "512",
    "thumbnailHeight": "288",
    "fileUrl": "IZtp8fzbz5Frb0I3rilhP1uLWnAb6YUKkmKJlurYIj1GbhLm8TNx1YxVuKZlOi169sXdaTehOqCt_HywgkS-bGo-H-7U2XjOE4ep6Wig1o8MMoRXXlg6dJJ4ZsrLNeQMgGlqmVqa4Hxp1jBJmqq9I36GAplGiZGAyCAXjSO-XELifWesnpEgcVMVeoEc5KgRiTeGPLvWjKx7oFublNwmwQ2PczvZjwUjww96UDwtgVeThQMGy8QtCZiAmVb9lqux6iv81fnar8r2KlxyKdICd91sN40b_xJG_GFUyYfGROixV70mCrwqjA6IjfE",
    "thumbnailUrl": "Su4u44w0gnhOoYAWBCGB1UUvNvWY7NrcI3wZYiEaLseB52l_hM6q9C8LgHJGaOW6j6hTXUU2A99YjErUUCodbrPG2WGvpMg34y6QnNoB0jegjFRdO7POtqPz-0PW-n_yzxX0wA_Krd4vrkyzup-GT67Mf6lWl83c1CYqX1QYqHna2QNMVP_Jtvd0PnIScmjBwPbDzZ3fpvuxQniASO-tk34pXRP1jgGuuUK3KWM_j2Y2tP_6m8uGH2CoK0_oBChBzQgP5LjkYj9pUfH_bLqjheovcmGeEnOtNaXdJTsTQ6ZBO7xoCCdE8IVrMLg"
}

نوع پیام فایل حاوی صدای ضبط شده (fileType: PUSH_TO_TALK)

جدول ۱۰: اجزای پیام، اگر فایل از نوع PUSH_TO_TALK باشد

نمونه	نوع داده	داده
720000	Double	fileDuration

مثال

                    
 {
    "to": "lJ1ddrR1YqyNgSRfUR_t9LSEbTO9JbXRDn1xGMgnkwma0OJXjw4h8IagAME",
    "body": " ",
    "type": "FILE",
    "fileName": "2018_5_30.m4a",
    "fileSize": "16149",
    "fileType": "PUSH_TO_TALK",
    "fileUrl": "hlrwMiCwwkJvSN9wuCQ4a1FL2LaAg0SXdAkNZSXQY8cRj2O3kJQuLJBLbMHODPXoJx0WZ2TKoQrRRk9UZu_g69gHIt7Aun27_dpY0vqFbeCNWcHPWPNd02278pNsSu9q_ JcKvFtenBi2nVHavKHxV3Z3Qj8tAFtmx53JUegricFEyorimYjawxgBGvTBOZ0yjwHiLnsN46R_EG8OiTPIj2tR9G1AKJzfLBKzNBf-SmzlA6JoHimhJA0aYkoi7f7T3B-hLPC4WDi5fLhW7D2hH68Lw4g62x2upPtOARQkJnYWkbEMMZg7xBFrNuI",
    "fileDuration": "2670"
}

نوع پیام فایل حاوی دیگر فرمت های مجاز (fileType: ATTACHMENT)

جدول ۱۰: اجزای پیام، اگر فایل از نوع PUSH_TO_TALK باشد

مثال

                    
 {
    "to": "ETQiHESnLSgYXN0LD8vJChE8YoEEFM8Zk4Ainn5ExkyXKFlgYfgNE5JwL2o",
    "body": "test",
    "type": "FILE",
    "time": "1538399819589",
    "fileName": "test.mp3",
    "fileType": "FILE_TYPE_OTHER",
    "fileSize": 3742868,
    "fileUrl": "w8yDyrJk9qVjuvQlI7piEUyu3VoK4tQf25O-QTQUmGcFZBBwKz5QVRZFJzx78qB1iLm9r8ZlBN9V5PwjRVMEMtljuG2bfcda-6FSzYRK1Fg9vLnUljzGCt0Dhld0AUUkIm4Fmd0CL4f1DrzK2JSDQNGuNhg1WR8FJSzE9tGeywF4Xwp-Etj16hbSrD9hrhQ7IVhYBkJV4S1XF3lxY54ypTANs2gGKBSA5NUt0CWY57HhekMPUKo90U_OTOpj6xJrIlzdHgZbqdHiZaVc0ys7LLNpt1_KRhGd7JcCT_pOsLdcESBwgOzqWCz5_2I"
}

نوع پیام مکان (TYPE: LOCATION)

برای ارسال LOCATION می‌بایست جدول زیر شامل مقدار باشد:

جدول ۱۲: اجزای پیام، اگر پیام از نوع LOCATION باشد

	نمونه	نوع داده	داده
۱	user	String	to
۲	LOCATION	LOCATION	type
۳	35.6892	Double	latitude
۴	51.3890	Double	longitude

مثال

                    
{
    "to": "lJ1ddrR1YqyNgSRfUR_t9LSEbTO9JbXRDn1xGMgnkwma0OJXjw4h8IagAME",
    "type": "LOCATION",
    "latitude": "35.6892",
    "longitude": "51.3890"
}

نوع پیام تغییر کیبورد (TYPE: CHANGE)

برای ارسال KEYBOARD_CHANGE می‌بایست جدول زیر شامل مقدار باشد:

جدول ۱۳: اجزای پیام، اگر پیام از نوع CHANGE باشد

	نمونه	نوع داده	داده
۱	user	String	to
۲	CHANGE	CHANGE	type
۳	`[[{"command":"1.1","text": "row 1 , column 1"}, {"command":"1.2",]]>"text": "row 1 , column 2"}]]`	آرایه ی دو بعدی از نوع CustomKey	keyboard

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

مثال

                        
{
    "to": "lJ1ddrR1YqyNgSRfUR_t9LSEbTO9JbXRDn1xGMgnkwma0OJXjw4h8IagAME",
    "type": "CHANGE",
    "keyboard": [
        [{
            "command": "1.1",
            "text": "row 1 , column 1"
        }, {
            "command": "1.2",
            "text": "row 1 , column 2"
        }]
    ]
}

کیبورد سفارشی (CUSTOM KEYBOARD)

برای ارسال کیبورد شما می‌بایست در پیام ارسالی به همراه فیلد‌های ذکر شده در جدول ۶، ۷ یا ۱۲ ، فیلد keyboard را نیز قرار دهید.

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

جدول 14: اجزای پیام اگر شامل فیلد Keyboard باشد

	نمونه	نوع داده	داده
۱	`[[{"command":"1.1","text": "row 1 , column 1"}, {"command":"1.2",]]> "text": "row 1 , column 2"}]]`	آرایه ی دو بعدی از نوع CustomKey	keyboard

کلاس CustomKey

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

جدول ۱۴.۱: اجزای فیلد CustomKey در keyboard

	نوع داده	مقدار	وضعیت	توضیح
۱	text	String	Not NULL	داده ای که مقدار آن برای کاربر نمایش داده می‌شود .
۲	command	String	Not NULL	داده ای که مقدار آن در صورت کلیک کردن بر روی دکمه ی آن در کلاینت برای شما فرستاده می‌شود.

مثال

        
{
    "to": " lJ1ddrR1YqyNgSRfUR_t9LSEbTO9JbXRDn1xGMgnkwma0OJXjw4h8IagAME ",
    "type": "TEXT",
    "body": "سلام",
    "keyboard": [
        [{
            "command": "1.1",
            "text": "row 1 , column 1"
        }, {
            "command": "1.2",
            "text": "row 1 , column 2"
        }],
        [{
            "command": "2.1",
            "text": "row 2 , column 1"
        }, {
            "command": "2.2",
            "text": "row 2 , column 2"
        }],
        [{
            "command": "3.1",
            "text": "row 3 , column 1"
        }, {
            "command": "3.2",
            "text": "row 3 , column 2"
        }, {
            "command": "3.3",
            "text": "row 3 , column 3"
        }]
    ]
}

نمونه‌ی خروجی مشاهده شده توسط کاربر:

	Row1,column2	Row1,column1
	Row2,column2	Row2,column1
Row3,column3	Row3,column2	Row3,column1

نکته ۱: در صورت عدم ارسال فیلد keyboard، در صورت موجود بودن کیبورد در پیام قبلی، همان کیبورد برای پیام جدید شما نیز نمایش داده خواهد شد.
نکته ۲: در صورت ارسال کیبورد و خالی بودن مقدار آن، کیبوردی به کاربر نمایش داده نمی‌شود.

توسعه‌دهندگان برای ارسال فایل به کاربران می‌بایست به این طریق ارتباط خود را برقرار کنند:

                        [POST] : https://bot.splus.ir/"TOKEN"/uploadFile

مقدار TOKEN در ابتدای ثبت نام بات به شما داده شده است.

شما می‌بایست فایل مورد نظر را به صورت MultiPart با کلید واژه ی file برای سرور ارسال کنید. در صورت موفقیت امیز بودن مقدار http status برگشتی 200 می‌باشد. و پیامی در قالب JSON به شما ارسال می‌شود که شامل url فایل شما می‌باشد.

نمونه درخواست ارسال فایل با استفاده از curl:

					curl -X POST -H "Content-Type: multipart/form-data" -F "file=@/home/Pictures/1.png" https://bot.splus.ir/[TOKEN]/uploadFile

جدول ۱۶: اجزای پیام دریافتی در پاسخ به درخواست آپلود فایل

	نمونه	نوع داده	داده
۱	... hlrwMiCwwkJvSN9wuCQ4a1FL2LaAg0SXdAkN	String	fileUrl
۲	OK	String	resultMessage
۳	200	Integer	resultCode

مثال

                        
 {
    "fileUrl": "itU76wTedFe2jawUeh7JPNNOBNcePkNNAssK57vrEWh6u8m_WMqKc3pTs52Puk1jSSjy7q9e8HZf6k5_DiGlg9ttS6dyDT7JuXEnOBi4A9uL2DDP0maVepqroSK3dstGRb0brCTRbTeUaSFE6Z9hbR-vnIPJRaczvwyDIrOdBxC7A3k2fgPIKwMCmDBnsn8hFPmznmMNU6AwOi4Fs6uLsOywHOEb95St1d8ux_sIrYtQhGan2DVi4_ZcweSzXdqSGk5UAcqS0U7Ae884oroxjikzDz3LSRwLpAJeahOoj70JlUB_
36AuvkoVbajFem80vFVy9u1jluhYyNZr0jRT2yTrlArGQF8eD9zqvmXa05atDEbG3Cz3GH4uEC7e_DToeqvXFYad7nsFSze93cjy30StOvcCurY7Vy1Uiw5PWLoEgjbVyT6l0Elt2LwAF-MiW9YZmn-hfxRBA1CAA1oDfQxb_1URL0xCDkehiUIH4iawloC5jL5TEXx4IXg",
    "resultCode": 200,
    "resultMessage": "OK"
}

توسعه‌دهندگان برای دریافت فایل می‌بایست به این طریق ارتباط خود را برقرار کنند:

                        [GET] : https://bot.splus.ir/"TOKEN"/downloadFile/"URL"

مقدار TOKEN در ابتدای ثبت نام بات به شما داده شده است.

شما می‌بایست fileUrl خود را در انتهای درخواست http خود قرار دهید و مانند نمونه‌ی بالا برای ما ارسال کنید.

مثال

                        
https://bot.splus.ir/jh3C1OVMYHTlNNwhro-fxBNT2j8KDrma25DSJc_mnI1 ... /downloadFile/itU76wTedFe2jawUeh7JPNNOBNcePkNNAssK57vrEWh6u8m_WMqKc3pTs52Puk1jSSjy7q9e8HZf6k5_DiGlg9ttS6dyDT7JuXEnOBi4A9uL2DDP0maVepqroSK3dstGRb0brCTRbTeUaSFE6Z9hbR-vnIPJRaczvwyDIrOdBxC7A3k2fgPIKwMCmDBnsn8hFPmznmMNU6AwOi4Fs6uLsOywHOEb95St1d8ux_sIrYtQhGan2DVi4_ZcweSzXdqSGk5UAcqS0U7Ae884oroxjikzDz3LSRwLpAJeahOoj70JlUB_
36AuvkoVbajFem80vFVy9u1jluhYyNZr0jRT2yTrlArGQF8eD9zqvmXa05atDEbG3Cz3GH4uEC7e_DToeqvXFYad7nsFSze93cjy30StOvcCurY7Vy1Uiw5PWLoEgjbVyT6l0Elt2LwAF-MiW9YZmn-hfxRBA1CAA1oDfQxb_1URL0xCDkehiUIH4iawloC5jL5TEXx4IXg

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

کتابخانه‌ی php:

                    https://github.com/soroush-app/bot-php-sdk

کتابخانه‌ی python:

                    https://github.com/soroush-app/bot-python-sdk

ارتباط، زندگی، سرگرمی

توسعه‌دهندگان سروش پلاس

راهنمای استفاده از مستربات سروش پلاس

نوع پیام متنی (TYPE: START)

نوع پیام متنی (TYPE: STOP)

نوع پیام متنی (TYPE: HEALTH_CHECK)

نوع پیام متنی (TYPE: TEXT)

نوع پیام فایل (TYPE: FILE)

نوع پیام فایل حاوی عکس (fileType: IMAGE) یا تصویر متحرک (fileType: GIF)

نوع پیام فایل حاوی ویدئو (fileType: VIDEO)

نوع پیام فایل حاوی صدای ضبط شده (fileType: PUSH_TO_TALK)

نوع پیام مکان (TYPE: LOCATION)

ننوع استفاده ی پیام (MAJOR_TYPE: BOT)

نوع استفاده ی پیام (MAJOR_TYPE: CHANNEL)

نوع پیام متنی (TYPE: TEXT)

نوع پیام فایل (TYPE: FILE)

نوع پیام فایل حاوی عکس (fileType: IMAGE) یا تصویر متحرک (fileType: GIF)

نوع پیام فایل حاوی ویدئو (fileType: VIDEO)

نوع پیام فایل حاوی صدای ضبط شده (fileType: PUSH_TO_TALK)

نوع پیام فایل حاوی دیگر فرمت های مجاز (fileType: ATTACHMENT)

نوع پیام مکان (TYPE: LOCATION)

نوع پیام تغییر کیبورد (TYPE: CHANGE)

کیبورد سفارشی (CUSTOM KEYBOARD)

کلاس CustomKey

کتابخانه‌ی php:

کتابخانه‌ی python:

با ما در ارتباط باشید