ارتباط، زندگی، سرگرمی
توسعهدهندگان سروش پلاس
راهنمای استفاده از مستربات سروش پلاس
ارایه خدمات ارزش افزوده و سرویسهای متنوع بر بستر پیامرسان سروش پلاس در جذابتر شدن این پیامرسان، تأثیر چشمگیری دارد.
این مهم تنها با کمک توسعهدهندگان عزیز صورت خواهد پذیرفت. از اینرو بستر توسعه سروش پلاس را با استفاده از «مستر بات سروش پلاس» برای شما علاقمندان فراهم آوردیم تا در کنار هم خدمات متنوعی را برای کاربران سروش پلاس فراهم کنیم.
در ادامه میتوانید از راهنمای توسعه بات سروش پلاس استفاده نمایید.
در بات سروش پلاس شما توسعه دهنده ی عزیز میتوانید انواع پیام را که در لیست زیر موجود میباشد را به کاربران خود ارسال کنید.
- متن
- عکس
- فیلم
- صدا
- عکس متحرک
- صدای ضبط شده
- موقعیت جغرافیایی
- و تمامی فرمتهای مجاز در سرور سروش پلاس
همچنین شما میتوانید با ارسال کیبورد برای بات خود فرآیند پرسش و پاسخ را در بات خود آسانتر کنید.
در این بخش شما توسعهدهنده عزیز میتوانید نحوه ساخت بات در سروش پلاس را به سادگی آموزش ببینید.
در قدم اول با عضویت در پیامرسان سروش پلاس و مراجعه به ربات مدیریت باتها به آدرس 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)
پیام ارسال شده از سمت شما باید در قالب 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 |
۳ |
|
آرایه ی دو بعدی از نوع 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 باشد
نمونه | نوع داده | داده | |
---|---|---|---|
۱ |
|
آرایه ی دو بعدی از نوع 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