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

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

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

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

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

 

 

امکانات بات سروش :

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

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

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

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

 

 

قدم اول :

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

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

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

 

 

دریافت پیام کاربران :

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

Version 1 =  [GET] : https://bot.sapp.ir/[TOKEN]/getMessage
OR
Version 2 =  [GET] : https://bot.sapp.ir/[TOKEN]/v2/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.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 باشد

نمونه نوع داده داده
۱ 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.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 باشد

نمونه نوع داده داده
۱ 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 باشد

جدول ، بدلیل بهم ریختگی سایت حذف گردید
جدول ، بدلیل بهم ریختگی سایت حذف گردید
جدول ، بدلیل بهم ریختگی سایت حذف گردید

در صورت انتخاب یکی از 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 باشد

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

مثال


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

نوع داده مقدار وضعیت توضیح
۱ 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.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

                        

 

 

 

کتابخانه ها در ساخت ربات سروش پلاس :

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

کتابخانه‌ی php:
https://github.com/soroush-app/bot-php-sdk
کتابخانه‌ی python:
https://github.com/soroush-app/bot-python-sdk

 

 

 

لینک کوتاه:

https://a4fran3.ir/?p=16823

Subscribe
Notify of
guest
2 نظرات
Inline Feedbacks
مشاهده همه نظرات
سینا
سینا
3 سال پیش

سلام من با پایتون یه ربات نوشتم. حالا نمیدونم چطور روی هاست قرارش بدم.
لطفا کمکم کنید

مطالب تصادفی