آموزش ساخت ربات سروش پلاس

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

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

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

ساخت ربات سروش پلاس را در ادامه به شما آموزش خواهیم داد

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

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

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

نوع ارتباط از استاندارد (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.sapp.ir/[TOKEN]/getMessage

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

openssl s_client -connect bot.sapp.ir:443
 
GET /[TOKEN]/getMessage HTTP/1.1
host:bot.sapp.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 بوده و شامل موارد زیر می‌باشد که هرکدام به اختصار در جدول زیر توضیح داده شده است.

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

نوع پیام (فیلد 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 باشد

مثال

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

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

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

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

مثال

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

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

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

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

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

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

مثال

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

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

مثال

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

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

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

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

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

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

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

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

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

مثال

{
    "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 باشد

مثال

{
    "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 باشد

مثال

{
    "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 باشد

مثال

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

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

[POST] : https://bot.sapp.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.sapp.ir/"TOKEN"/sendMessage

• نوع پیام متنی (TYPE: TEXT)
• نوع پیام فایل (TYPE: FILE)
  • نوع پیام فایل حاوی عکس (fileType: IMAGE) یا تصویر متحرک (fileType: GIF)
  • نوع پیام فایل حاوی ویدئو (fileType: VIDEO)
  • نوع پیام فایل حاوی صدای ضبط شده (fileType: PUSH_TO_TALK)
• نوع پیام تغییر کیبورد (TYPE: CHANGE)
• کیبورد سفارشی (CUSTOM KEYBOARD)
  • کلاس CustomKey

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

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

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

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

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

مثال

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

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

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

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

مثال

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

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

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

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

مثال

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

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

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

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

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

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

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

مثال

 {
    "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 باشد

مثال

 {
    "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 باشد

مثال

 {
    "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 باشد

مثال

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

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

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

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

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

مثال

{
    "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

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

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

مثال

{
    "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"
        }]
    ]
}
        

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

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

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

[POST] : https://bot.sapp.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.sapp.ir/[TOKEN]/uploadFile

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

مثال

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

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

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

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

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

مثال

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