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

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

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

توجه داشته باشید «مِستِر بات» سروش بصورت آزمایشی راه‌اندازی شده است.

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

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

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

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

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

  1. انتخاب گزینه‌ی ایجاد بات و ثبت شناسه‌ی بات. رعایت موارد بشرح ذیل ضروری‌ست:
    • حداقل تعداد حروف هر شناسه می‌بایست ۳ حرف باشد.
    • حروف استفاده شده می‌بایست انگلیسی باشد.
    • نام انتخابی می‌بایست یکتا باشد که در زمان انتخاب نام در «مستر بات» این مورد در لحظه بررسی شده و نتیجه به شما اطلاع داده خواهد شد.
  2. دریافت توکن و ذخیره‌ی آن
  3. ثبت اطلاعات بات که شامل، نام نمایشی بات، پیام آغازین، اطلاعات پروفایل بات و عکس بات می‌باشد.
توسعه‌دهندگان برای برقراری ارتباط و دریافت پیام‌های کاربران می‌بایست به این طریق ارتباط خود را برقرار کنند:
                [GET] : https://bot.sapp.ir/"TOKEN"/getMessage
              

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

نوع ارتباط از استاندارد (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 بوده و شامل موارد زیر می‌باشد که هرکدام به اختصار در جدول زیر توضیح داده شده است.

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

توضیحات اجباری نوع نام
۱ ادرس فرستنده‌ی پیام true String from
۲ محتوای داده‌ی ارسالی کاربر true String body
۳ نوع محتوای ارسال شده که می‌تواند : START,STOP,TEXT , LOCATION , FILE , CHANGE باشد . 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: شامل موقعیت جغرافیایی می‌باشد .

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

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

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

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

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

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

مثال

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

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

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

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

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

مثال

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

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

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

جدول ۲: اجزای پیام، اگر پیام از نوع 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.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
                    

 

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

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

توضیحات اجباری نوع نام
۱ آدرس گیرنده ی پیام true String to
۲ محتوای داده ی ارسالی به کاربر false String body
۳ نوع محتوای ارسالی که می‌تواند : 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

نوع پیام متنی (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"
}
                    
                

نوع پیام مکان (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.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
					

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

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