Bale bot documention - اسناد بات بله

به نام خدا

نکته : این فایل از دو بخش تشکیل یافته است. در قسمت اول توضیح غیر فنی بات مطرح می‌گردد و در بخش دوم توضیحات فنی ( API ) قرار داده شده است.

چرا بله؟

بله به خاطر خدمات ویژه‌ای که در اختیار کاربران خود قرار می‌دهد، خود را از سایر پیام‌رسان‌های داخلی جدا کرده است. امکان انجام فعالیت‌های مالی در کنار گفت‌و گو‌های دوستانه، بله را به محیطی جذاب برای کاربران ایرانی ایجاد کرده است. در همین راستا بله فرصت مناسبی را برای برنامه‌نویسان ایجاد کرده است تا بتوانند با ایجاد خدمات گوناگون به کسب درآمد بپردازند. امکاناتی که پیام‌رسان بله ایجاد کرده است :

امکانات اولیه

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

برای سهولت بیشتر در استفاده از api بات تیم بله کتابخانه‌ای را در محیط جاوا اسکریپت و پایتون آماده کرده است که به راحتی سرویس‌های مورد نیاز را در اختیار شما قرار می‌دهد. در این کتابخانه موارد زیر مهیا شده است:

کارهایی که به وسیله بات می‌توان انجام داد

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

نحوه عملکرد بات ها در بله

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

نحوه ساخت بات

ابتدا باید با بات پدر با شناسه bot_father صحبت کنیم و با استفاده از دستور newbot/ از آن بخواهیم که یک بات در اختیار ما بگذارد. بات پدر بعد از پرسیدن نام و نام کاربری بات یک توکن در اختیار ما قرار می‌دهد که با استفاده از این توکن می‌توانیم به سرور بله متصل شده و بات خود را کنترل کنیم. شما نیز با دستوراتی مانند setphoto/ می‌توانید برای بات خود عکس انتخاب کنید و یا با استفاده از setdescription/ می‌توانید توضیحاتی برای بات خود در نظر بگیرید.

قابلیت مانیتورینگ

شما با استفاده از دستور watch/ در بات پدر می‌توانید مانیتورینگ بات خود را فعال کرده و بات نگهبان هرزمان که بات شما غیر فعال شود و به کاربران پاسخ ندهد به شما پیغام غیر فعال بودن بات را می‌دهد.

تفاوت بات با کاربر معمولی

نحوه ارتباط کاربران با بات

کافی است که پس از اضافه کردن بات به عنوان یک مخاطب عادی برروی دکمه شروع کلید کنید ، در این صورت مکالمه بین شما و بات اغاز می‌شود. شما میتوانید علاوه بر ارسال پیام متنی برای بات پیام‌های تصویری و یا فایل برای بات ارسال کنید .

قابلیت های Template Message

همانطور که در بالا اشاره شد توسعه دهنده بات می‌تواند از دکمه‌های template message برای پیشنهاد به کاربر خود استفاده کند. در پیام های template message توسعه دهنده بات به ازای هر پیام مشخص می‌کند که توقع چه نوعی از جواب را از کاربر دارد. برای مثال توقع دارد که کاربر یک متن ارسال کند و یا یک عکس و یا تاریخ و … که در این صورت کاربر باید همان نوع پاسخی که بات می‌خواهد به او بدهد. در این نوع پیام به ازای هر دکمه یک action مشخص می‌شود که تعیین می‌کند در صورت فشرده شدن دکمه چه عملی انجام شود. مثلا پس از فشرده‌شدن دکمه پیامی ارسال شود یا به مرورگر وب و سایتی دیگر منتقل شود.

پیام درخواست پول

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

SDK جاوا اسکریپت

بعد از مطالعه این داکیومنت شما قادر خواهید بود به راحتی بات خود را در بله راه اندازی کنید. دقت نمایید که این کتابخانه به زبان جاوا اسکریپت نوشته شده است . نیازمندی ها (برای راهنما نصب کافیست برروی لینک‌ها کلیک کنید)

NPM: node package manager https://www.npmjs.com

NPM: https://nodejs.org/en/

نحوه ساخت بات در بله

اولین قدم : در ابتدا لازم است که شما با بات bot_father@ شروع به صحبت کنید و از بات پدر بخواهید که یک بات با نام و نام کاربری دلخواهتان بسازد. بعد از انجام این فرآیند یک token در اختیار شما گذاشته می‌شود که با استفاده از این token می‌توانید با سرور بله ارتباط برقرار کنید. سپس با استفاده از دستورات زیر محیطی را فراهم آورید که بتوانید کد خود را در این محیط توسعه دهید و کتابخانه بات بله را نیز به محیط کد خود اضافه کنید.

mkdir mybot

cd mybot

npm init

npm install balebot

در صورت با موفقیت انجام شدن دستورات بالا کتابخانه بات بله به دایرکتوری node_modules شما اضافه شده است و شما می‌توانید از توابع و کلاس‌های این کتابخانه به راحتی استفاده کنید. این کتابخانه با قواعد شی گرایی سازگاری داشته و شما می‌توانید به راحتی از هر قسمت کد که لازم بود آزادانه استفاده کنید و می‌توانید داکیومنت API بات بله را نیز برای درک بیشتر مطالعه کنید. نکته: تمامی کلاس‌هایی که شما برای شروع راه اندازی بات نیاز دارید به صورت استاتیک در اختیار شما قرار گرفته است.

شروع

همانطور که گفته شد در ابتدا لازم است که شما کتابخانه بات بله را که قبلا نصب کرده بودید را فراخوانی کنید سپس کلاس های مورد نیاز خود را فراخوانی کرده و از آنها استفاده کنید: برای مثال برای ساخت کلاس اولیه بات نیازاست که شما از کدی مانند کد زیر استفاده کنید.

const SDK = require("balebot");
const BaleBot = SDK.BaleBot;

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

let bot = new BaleBot("Your Token");

همانطور که دیدید به راحتی شما توانستید یک بات بسازید و به سرور بله متصل شوید . حال کافیست مراحل بعدی را ادامه دهیم تا بتوانیم بات خود را کامل تر کنیم. زمانی که شی بات را می‌سازید می‌توانید علاوه بر توکن مقادیر دیگری را هم به صورت اختیاری به سازنده اضافه کنید مانند: کانفیگ لاگ ها و مقادیر دیگر مانند زیر:

let options = {
  log: {
    enabled: true,
    level: "INFO" // other options: "TRACE", "DEBUG", "WARN", "ERROR", "FATAL"
  },
  requestQueue: {
    fetchInterval: 0, // in ms. the time between sending two consecutive requests.
    retryInterval: 0, // in ms. the time to wait before resending a failed request.
    timeout: 30000, // in ms. the time period to try for sending each request. if the request failed again after this time it will be rejected with the "TIME_OUT" message.
  },
  socket: {
    reconnectInterval: 30000 // in ms. when the socket disconnects, waits as much as this time and the tries to reconnect.
  }
}
 
// sample use
let bot = new BaleBot('token', options);

بعد از انجام مراحل بالا احتمالا این به ذهن شما می‌رسد که چطور می‌توانم به درخواست‌های کاربرانمان پاسخ دهیم یا چطور می‌توانیم با کاربرانمان گفتگو کنیم . کافیست ادامه را مطالعه کنید. شما می‌توانید به راحتی برروی عبارات خاص شنود کنید یا به راحتی با کاربران خودتان مکالمه داشته باشید.

Hear

با استفاده از متد hear شما به راحتی میتوانید برروی عبارات خاص شنود کنید و در صورت ارسال این عبارات از سوی کاربر شما می‌توانید در پاسخ عبارات مورد نظر خودتان را ارسال کنید مانند زیر: متد hear دارای دو پارامتر زیر می باشد:

ورودی‌های تابع callback عبارتند از:

Sensitive

Sensitive یک کلاس interface می‌باشد که با استفاده از کلاس‌های فرزند آن مانند photoSensitive ، fileSensitive و textSensitive می‌توانید علاوه بر اینکه برروی متن‌های ارسالی از طرف کاربر شنود کنید بر روی فایل ء عکس و یا هر چیز دیگری که خودتان مایلید شنود کنید . فقط کافیست که اگر هم کلاس آن وجود ندارد خودتان کلاس را ایجاد کرده و از Sensitive ارث ببرید و متد match را باز نویسی کنید می‌توانید مثالی که شامل متد hear می باشد را در زیر ببینید:

"use strict";
const SDK = require("balebot");
const BaleBot = SDK.BaleBot;
const TextMessage = SDK.TextMessage;
let bot = new BaleBot("Your Token");
bot.hears(['whats your name', 'name', 'name?'], (message, responder) => {
    responder.reply("My name is samplebot!");
});
bot.hears(new PhotoSensitive(), (message, responder) => {
    responder.reply("I received photo");
});

همانطور که مشاهده می‌کنید با استفاده از این کد بات هنگامی که کلماتی مانند “name” یا “?name” یا what’s your name را ببیند در جواب به کاربر "my name is sample bot " را ارسال می‌کند و با دریافت عکس جمله “I received photo” را برای کاربر ارسال می‌کند. همانطور که مشاهده کردید متد hear برای سوال جواب‌های کوتاه و یک مرحله‌ای بسیار مناسب می‌باشد ولی در صورتی که شما بخواهید با کاربرتان یک گفتگو طولانی داشته باشید بهتر است به جای متد hear از object دیگری با نام conversation استفاده کنید.

Coversation

برای ایجاد یک مکالمه که بصورت مداوم بین کاربر و بات ادامه دارد باید یک شی از نوع conversation بسازیم و مراحل زیر را طی کنیم : ایجاد یک شی از نوع Conversation مشخص کردن شرایطی که طبق آن شرایط مکالمه بین کاربر و بات شروع می‌شود ( دقت کنید که فقط کاربر میتواند شروع کننده یک مکالمه باشد ) مشخص کردن رفتار بات در طی مراحل مکالمه اضافه کردن این شی به عنوان یک مکالمه به شی بات مثال زیر نشان‌دهنده کدی است که مکالمه بین کاربر و بات را فراهم می آورد:

"use strict";
 
const SDK = require("balebot");
const BaleBot = SDK.BaleBot;
const TextMessage = SDK.TextMessage;
const BotStatus = SDK.BotStatus;
const User = SDK.User;
const Conversation = SDK.Conversation;
 
let bot = new BaleBot("Your Token");
 
let conv = new Conversation(); // Step 1
 
let tracer = conv.startsWith(["lets talk"]); // Step 2
tracer.then((message, session, responder) => {
    //STATE 0
    //The first state definitely matches with the "starts with" sensitive. In this case: "lets talk"
    responder.reply("OK. Whats your name?");
    //Go to the next state
    session.next();
}).then((message, session, responder) => {
    //STATE 1
    if (message.text.length < 7) {
        responder.reply("Nice name. I like " + message.text);
        //Ok. go to the next state...
        session.next();
    } else {
        responder.reply("What a long name! Give me a shorter name! :|");
        // Don't call session.next() to remain in the current state.
    }
}); // Step 3
 
bot.setConversation(conv); // Step 4

همانطور که در کامنت‌ها نیز مشاهده می‌کنید مراحل ایجاد یک مکالمه مرحله به مرحله گفته شده است. در هر حالت از مکالمه بات باید رفتاری از خود نشان بدهد که همانطور که مشاهده می‌کنید در هر حالت شی Conversation سه ورودی زیر را دریافت می‌کند :

"/ و سپس با استفاده از این سه ورودی شما می‌توانید رفتار بات خود را در هریک از این حالت‌ها مشخص کنید. حال شاید این سوال برای شما پیش بیاید در صورتی که کاربر به بات پیامی دهد که شامل یک عبارت باشد و آن عبارت نه شروع کننده یک مکالمه باشد و نه متد hear برای آن صدا زده شده باشد چه می‌شود؟ چگونه باید رفتار بات را برای این مواقع مشخص کرد؟ متد setDefaultCallback جواب این سوال‌هاست... #### SetDefaultCallback با استفاده از این متد می‌توان مشخص کرد که اگر عباراتی را کاربر برای بات ارسال کرد و این عبارات از طرف توسعه دهنده بات غیر قابل پیش بینی بود بات باید چه رفتاری از خود نشان دهد. ورودی این متد یک تابع است و مقادیر ورودی تابع که برای پاسخ گویی به کاربر قابل استفاده می‌باشد عبارتنداز :

در پایین مثالی را مشاهده می‌کنید که می‌توانیداز طریق آن به پیام‌های پیش بینی نشده کاربر پاسخ دهید.

"use strict";
const SDK = require("balebot");
const BaleBot = SDK.BaleBot;
let bot = new BaleBot("Bot Token");
bot.hears(["hello", "Hi"], (message,responder) => {
    //The user said something like hello!
});
bot.setDefaultCallback((message,responder) => {
    //The user said something unexpected!
});

upload

ورودی:

مثال استفاده از این متد را در زیر مشاهده می‌کنید:

bot.UploadFile(fileBuffer,fileType).then(response => {
    // you can save the location of uploadedfile
    let fileId = response.fileId
    let fileAccessHash = response.accessHash
    let fileٰVersion = response.version
}).catch((err)=>{
// you can do any thing with err :))))
});

همانطور که مشاهده می‌کنید بعد از اینکه upload با موفقیت انجام شود then متد صدا زده شده و شی response به شما برگردانده می‌شود که داخل آن مقادیر زیر موجود است :

و در صورتی که عملیات آپلود با مشکل مواجه شود وارد قسمت catchمی‌شویم و شی error بازگردانده می‌شود. توجه : مقادیر بالا که در response موجود است برای ارسال پیام غیر متنی مانند تصویر و فایل و ویدیو لازم است. توجه: دقت کنید که هر بات برای آپلود دارای محدودیت 50 مگابایت برای فایل و 10 مگابایت برای عکس می باشد.

Download

پارامتر های سازنده :

خروجی :

Promise که در صورت با موفقیت انجام شدن وارد then می‌شود و در غیر این صورت وارد catch می‌شود. مثال استفاده از این متد را در زیر مشاهده می‌کنید :

bot.DownloadFile(fileId,fileAccesshash,fileType).then(response => {
    // you can save the response as file
   fs.writeFile(response);
}).catch((err)=>{
// you can do any thing with err :))))
});

همانطور که مشاهده می کنید در صورتی که دانلود با موفقیت به اتمام برسد وارد then. میشویم و شی response برگردانده میشود که حاوی فایل دانلود شده است. و درصورتی که دانلود با شکست مواجه شود وارد catch. میشود و error بازگردانده می شود.

توجه : دقت کنید که هر بات برای دانلود دارای محدودیت 20 مگابایت برای فایل و محدودیت 5 مگابایت برای عکس می باشد. بهتر است که قبل از اینکه سراغ متداول‌ترین متد که send می‌باشد راجع انواع پیام‌ها بیشتر صحبت کنیم.

MESSAGES

ساده‌ترین نوع پیام ء پیام متنی است . پارامتر‌های ساخت پیام متنی :

همانطور که ملاحظه می‌کنید برای ساخت پیام متنی صرفا کافیست که رشته ای از کاراکتر‌ها را به سازنده کلاس بدهیم و یک شی از آن را بسازیم. می‌توانید در زیر مثالی از ساخت پیام متنی را مشاهده نمایید.

const SDK = require("balebot");
const BaleBot = SDK.BaleBot;
const TextMessage = SDK.TextMessage;
var text = new TextMessage(String you want to send);

همانطور که مشاهده کردید کار بسیار راحتیست ...

File Message

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

const SDK = require("balebot");
const BaleBot = SDK.BaleBot;
const FileMessage = SDK.FileMessage
var file = new FileMessage(fileId,fileAccessHash,name,fileSize,mimtype,caption)

همانطور که مشاهده کردید کار بسیار راحتیست …

Photo Message

پیام تصویری یکی از زیر مجموعه‌ها یا فرزندان پیام فایلی می باشد. به عبارت دیگر از fileMessage ارث می‌برد. در صورتی که مایل هستید فایلی که محتوای آن عکس می‌باشد را برای کاربرتان ارسال کنید بهتر است از پیام تصویری استفاده کنید پارامتر های ساخت پیام تصویری:

مثال ساده‌ای از ایجاد یک پیام تصویری را می‌توانید در زیر مشاهده کنید.

const SDK = require("balebot");
const BaleBot = SDK.BaleBot;
const PhotoMessage = SDK.PhotoMessage
var photo = new PhotoMessage(fileId,fileAccessHash,name,fileSize,mimtype,caption,width,heigth,image thumbnail base64);

Video Message

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

مثال ساده‌ای از ساخت پیام ویدیویی:

const SDK = require("balebot");
const BaleBot = SDK.BaleBot;
const VideoMessage = SDK.VideoMessage
var video = new viedoMessage(fileId,fileAccessHash,name,fileSize,mimtype,caption,width,heigth,video thumbnail base64,duration);

Audio Message

پیام صوتی یکی از زیر مجموعه ها یا فرزندان پیام فایلی می باشد. به عبارت دیگر از fileMessage ارث می برد. اگر مایل به ارسال پیامی هستید که حاوی فایل صوتی است می‌توانید از این نوع پیام استفاده کنید. پارامتر‌های ساخت پیام صوتی:

مثال ساده‌ای از ساخت پیام صوتی :

const SDK = require("balebot");
const BaleBot = SDK.BaleBot;
const AudioMessage = SDK.AudioMessage
var Audio = new AudioMessage(fileId,fileAccessHash,name,fileSize,mimtype,caption,duration);

TemplateMessage

نوع خاص و بسیار جذابی از پیام که طرفدار های زیادی هم در بین توسعه دهندگان بات دارد پیام حاوی دکمه می باشدء نام این نوع پیام در بله template message گذاشته شده است و به شما این قابلیت را می دهد که پیام هایی از هر جنس که میخواهید (به جز پیام درخواست پول) را همراه چند دکمه در پایین آن که به دلخواه خودتان مشخص میشود ارسال کنید .

پارامتر‌های سازنده برای ساخت template message:

پارامترهای مورد نیاز برای ساخت شی SimpleTemplate:

پارامتر‌های سازنده برای ساختن Button Element:

نمونه ساده‌ای از ساخت template Message:

var simpletemplate = new SimpleTemplate(generalMessage like textMessage,buttonList,responseType like "Text");
var button = new Button(text like "salam",value like "/hello",1);
simpleTemplate.addbtn(button);
var templateMessage = new TemplateMessage(simpleTemplate);

Purchase Message

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

مثال ساده‌ای از نحوه ساخت پیام درخواست پول را در زیر مشاهده می‌کنید :

var purchaseMessage = new PurchaseMessage(msg like photoMessage,accountNumber, amount,money_request_type;

ReceiptMessage

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

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

خوب با توجه به این که تمامی انواع پیام را تا اینجا بررسی کردیم کافیست بدانیم که چطور می‌توانیم این پیام هارا برای کاربرانمان ارسال کنیم. این کار به وسیله تابع send که در پایین توضیح داده می‌شود امکان پذیر است.

send

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

یک مثال ساده از نحوه ارسال پیام را در زیر مشاهده می‌کنید :

bot.send(any message,new User(id,accessHash));

خب همانطور که قول داده بودیم باید راجع به peer و responder بیشتر صحبت کنیم.

Peer

peer یک شی از هویت کاربران است که با داشتن آن می‌توانیم به یک کاربر پیام دهیم و شامل پارامترهای زیر است :

دو کلاس User و Group از Peer ارث برده‌اند و بهتر است برای مشخص کردن کاربر و یا گروه بجای اینکه از Peer شی بسازیم از User و Group شی بسازیم. پارامتر های سازنده شی User و Group

responder

شی است که شامل پارامتر peer است و همچنین دارای متدی است به نام reply که شما می‌توانید به وسیله آن بدون اینکه نیاز باشد از متد send بات استفاده کنید به کاربر مورد نظر پیام دهید. ورودی متد reply به شکل زیر است :

مثالی از نحوه استفاده از متد reply و همچنین شی peer را درزیر مشاهده می‌کنید :

bot.hears(["hello", "Hi"], (message,responder) => {
    // Short version
    responder.reply("Hello! What's goin on?");
    // Standard version
    let msg = new TextMessage("Hello! What's goin on?");
    let receiver = responder.peer;
    bot.send(msg, receiver);
});

SDK پایتون

این کتابخانه به شما کمک می‌کند که بات خود را در بله راه اندازی کنید و به راحتی از api های بله که در اختیار شما می‌گیرد، استفاده نمایید. این کتابخانه با زبان پایتون توسعه داده شده است و نسخه ۳.۵+ این زبان را پشتیبانی می‌کند. نیازمندی‌ها :

تمام مثال های این مستند را میتوانید در گیت هاب مشاهده کنید.

Python 3.5

Asyncio

Aiohttp

Graypy

پس از نصب پایتون شما می‌توانید با استفاده از ابزار pip تمام نیازمندی‌های پروژه را نصب کنید:

pip3 install balebot

نحوه ساخت بات در بله

در اولین قدم لازم است که شما با باتbot_father@ شروع به صحبت کنید و از بات پدر بخواهید که یک بات با نام و نام کاربری دلخواهتان بسازد. بعد از انجام این فرآیند یک token در اختیار شما گذاشته می شود که با استفاده از این token می‌توانید با سرور بله ارتباط برقرار کنید. سپس پروژه‌ی خود را ایجاد کرده و کتابخانه بات بله را به آن اضافه کنید، در این مرحله شما می‌توانید از توابع و کلاس های این کتابخانه به راحتی استفاده نمایید. این کتابخانه از با قواعد شی‌گرایی سازگاری داشته و شما می‌توانید به راحتی از هر قسمت کد که لازم بود آزادانه استفاده کنید و می‌توانید داکیومنت API بات بله را نیز برای درک بیشتر مطالعه کنید. شروع همانطور که گفته شد در ابتدا لازم است که شما کتابخانه بات بله را که قبلا نصب کرده بودید را فراخوانی کنید سپس کلاس‌های مورد نیاز خود را فراخوانی کرده و از آنها استفاده کنید. برای مثال برای ساخت کلاس اولیه بات نیاز است که شما از کدی مانند کد زیر استفاده کنید :

from balebot.handlers import *
from balebot.filters import *
from balebot.models.base_models import Peer
from balebot.models.messages import *
from balebot.updater import Updater
from balebot.config import Config
 
updater = Updater(token="Your Token") 
dispatcher = updater.dispatcher

همان طور که مشاهده می‌کنید در ابتدا با استفاده از توکن بات یک شی از کلاس Updater ساخته شود. Updater کلاس اصلی کتابخانه می‌باشد که بخش‌های مختلف آن را به هم وصل می‌کند، این کلاس پس از ساخته شدن از کلاس‌های Network و Bot وDispatcher در خود شئ می‌سازد . Network و Dispatcher بوسیله‌ی یک صف ( Queue ) باهم تبادل اطلاعات می‌کنند، کلاس Network پیوسته update ها و response های سرور را دریافت می‌کند و آن ها را به کمک صف بهDispatcher می‌فرستد تا بررسی شوند، در ادامه شما می‌توانید‌Handler هایی را در Dispatcher ایجاد کنید تا آپدیت های دریافت شده با توجه به این Handler ها سرویس‌دهی شوند، در ادامه بیشتر با Handler ها آشنا خواهید شد . علاوه بر این قبل از آن که که از کلاس Updater شئ بسازید میتوانید کانفیگ پیشفرض بات را هم به صورت اختیاری تغییر دهید : مثال ساده :

updater = Updater(token="YOUR TOKEN")

مثالی از تغییر کانفیگ قبل از ساخت شئ Updater :

from balebot.models.messages import *
from balebot.updater import Updater
from balebot.config import Config
 
Config.base_url = "YOUR CUSTOM URL"
Config.request_timeout = 10  # in ms. the time period to try for sending each request. if the request failed again after this time it will be rejected with the "TIME_OUT" message
Config.use_graylog = False  # if you want regular log messages in output, set to False
Config.graylog_host = "127.0.0.1"
Config.graylog_port = 12201
Config.log_facility_name = "FACILITY_NAME"
Config.log_level = logging.DEBUG
 
updater = Updater(token="YOURTOKEN",
                  loop=asyncio.get_event_loop())

نکته : متغیر loop اختیاری است و در صورتی که بخواهید در بات خود از کتابخانه ی asyncio پایتون استفاده نمایید میتوانید از آن استفاده کنید . بعد از انجام مراحل بالا احتمالا این به ذهن شما میرسد که چطور می‌توانم به درخواست‌های کاربرانمان پاسخ دهیم یا چطور می‌توانیم با کاربرانمان گفتگو کنیم . کافیست ادامه را مطالعه کنید. شما می‌توانید به راحتی برروی پیام‌ها و عبارات خاص شنود کنید یا به راحتی با کاربران خودتان مکالمه داشته باشید.

Handlers

با استفاده از از کلاس‌های Handler به راحتی می‌توانید برروی عبارات خاص شنود(گوش کنید) کنید و در صورت ارسال این عبارات از سوی کاربر شما می‌توانید در پاسخ عبارات مورد نظر خودتان را ارسال کنید . برای این کار میتوانید از دوکلاس MessageHandler و CommandHandler استفاده کنید .علاوه بر این می‌توانید از error_handler ‌‌ها نیز استفاده کنید .

این کلاس‌ها در ورودی تابع سازنده خود متد callback می‌گیرند که در صورت دریافت نوع پیام مورد انتظار این متد صدا زده خواهد شد. پراستفاده‌ترین نوع Handler کلاس MessageHandler می‌باشد که می‌تواند انواع پیام‌ها ( عکس، فایل، صدا، ویدئو، نوشته و … ) را فیلتر و شنود کند که برای این کار باید Filter مناسب به آن‌ها داده شود، توضیح این Filter ها در جدول زیر آمده است :

ورودی‌های تابع callback عبارتند از :

نکته : فیلد update که از نوع FatSeqUpdate (پیام‌هایی که از طرف کاربران به بات ارسال می‌شود)است چند متد کاربردی دارد که می‌توانید از آن‌ها استفاده نمایید : get_effective_user این متد کاربر یا گروهی که توسط آن برای شما پیام فرستاده شده است را به صورت یک شئ از کلاس Peer می‌دهد. ( درباره این کلاس در ادامه صحبت خواهیم کرد ) get_effective_message در ضورتی که پیام یا آپدیت دریافت شده از نوع message باشد این متد یک شئ از پیام دریافت شده برمی‌گرداند و در غیر این صورت None می‌دهد.

برای راحتی استفاده ازHandler می‌توانید از decorator های پایتون استفاده کنید که مثال‌هایی از این روش در زیر آمده‌اند :

def success(result):
    print("success : ", result)
 
 
def failure(result):
    print("failure : ", result)
 
 
@dispatcher.message_handler(filters=[TextFilter(keywords=["iran", "tehran", "سلام"], pattern="^hello(.)+"),TemplateResponseFilter(keywords=["hellooo"])])
def text_received(bot, update):
    message = update.get_effective_message()
    user_peer = update.get_effective_user()
    bot.send_message(message, user_peer, success_callback=success, failure_callback=failure)
 
 
@dispatcher.message_handler([DocumentFilter(), PhotoFilter(), VoiceFilter(), VideoFilter(), StickerFilter()])
def start_command(bot, update):
    message = update.get_effective_message()
    print("received messages forwarded to sender.")
    bot.reply(update, message, success_callback=success, failure_callback=failure)
 
 
@dispatcher.command_handler("/start")
def start_command(bot, update):
    message = update.get_effective_message()
    bot.respond(update, message, success_callback=success, failure_callback=failure)
 
 
@dispatcher.command_handler(["/skip", "/help"])
def skip_or_help_command_received(bot, update):
    bot.reply(update, "do you need help?\nor you want to skip?", success_callback=success, failure_callback=failure)
  
 
@dispatcher.error_handler()
def error_handler(bot, update, error):
    if update:
        print(update)
    print(error, "  :  handled by error_handler")
 
updater.run()

علاوه بر این می‌توان از یک Handler ویژه به نام default_handler استفاده کنیم. با استفاده از این متد می‌توان مشخص کرد که اگر عباراتی را کاربر برای بات ارسال کرد و این عبارات از طرف توسعه‌دهنده بات غیر قابل پیش‌بینی بود بات باید چه رفتاری از خود نشان دهد:

@dispatcher.default_handler()
def default_handler_func(bot, update):
    bot.reply(update, "default handler is replying.", success_callback=success, failure_callback=failure)

همچنین اگر می‌خواهید از دکوراتور ها استفاده نکنید، می‌توانید به شیوه‌ای دیگر هم از Handlerها استفاده کنید :

def default_handler_dunc_without_decorator(bot, update):
    bot.reply(update, "default handler is replying.", success_callback=success, failure_callback=failure)
 
 
def echo_message(bot, update):
    message = TextMessage("thanks \ngoodbye ;)")
    user_peer = update.get_effective_user()
    bot.send_message(message, user_peer, success_callback=success, failure_callback=failure)
 
def error_handler(bot, update, error):
    print(error, "  :  handled by error_handler")
 
 
some_message_handler = MessageHandler(TextFilter(keywords=["mountain", "cloud"], pattern="good..e"), echo_message)
document_handler = MessageHandler(DocumentFilter(), echo_message)
default_handler = MessageHandler(DefaultFilter(), default_handler_dunc_without_decorator)
 
dispatcher.add_handler(some_message_handler)
dispatcher.add_handler(document_handler)
dispatcher.add_handler(default_handler)
dispatcher.add_error_handler(error_handler)
 
updater.run()
 

conversation

برای ایجاد یک مکالمه که بصورت مداوم بین کاربر و بات ادامه دارد باید از conversation استفاده کنیم و مراحل زیر را طی کنیم :
ایجاد یک Handler به عنوان آغازگر Conversation ) در واقع شرایطی که طبق آن، مکالمه بین کاربر و بات شروع میشود را مشخص میکنیم) ایجاد متد هایی برای مراحل ( state ) های بعدی Conversation در هر مرحله با استفاده از متد register_conversation_next_step_handler کلاس Bot ، مرحله‌ی بعدی مکالمه و همچنین Handler هایی که با آن ها می‌توان به مرحله‌ی بعدی منتقل شد را می‌توان مشخص کرد. ( در واقع توسعه دهنده‌ی بات می‌تواند برای خود یک state machine شبیه سازی کند ) مشخص‌کردن پایان Conversation با استفاده از متد finish_conversation کلاس Bot همچنین در مکالمه نیز قابلیت استفاده از default_handler ها وجود دارد ) در اینجا باید از کلاس DefaultFilter استفاده نماییم ) علاوه بر این، این امکان وجود دارد که با استفاده از متد‌های set_conversation_data و get_conversation_data در بخش‌های مختلف مکالمه متغیرهایی را به صورت key-value ذخیره و استفاده کرد، این متغیرها با اتمام مکالمه خودبه خود پاک می‌شوند . مثال زیر نشان‌دهنده کدی است که مکالمه بین کاربر و بات را فراهم می‌آورد:

@dispatcher.command_handler(["talk"])
def conversation_starter(bot, update):
     message = TextMessage("hi , nice to meet you :)\nplease tell me your name.")
     user_peer = update.get_effective_user()
     bot.send_message(message, user_peer, success_callback=success, failure_callback=failure)
     dispatcher.set_conversation_data(update=update, key="my_data", value="my_value")
     dispatcher.register_conversation_next_step_handler(update, [MessageHandler(TextFilter(), ask_name),
     MessageHandler(DefaultFilter(), skip_name)])
 
 
def ask_name(bot, update):
     message = TextMessage("thanks \nplease send me your photo")
     user_peer = update.get_effective_user()
     bot.send_message(message, user_peer, success_callback=success, failure_callback=failure)
     dispatcher.register_conversation_next_step_handler(update, MessageHandler(PhotoFilter(), ask_photo))
 
 
def skip_name(bot, update):
     message = TextMessage("so, you don't want to tell your name !\nplease send me your photo")
     user_peer = update.get_effective_user()
     my_data = dispatcher.get_conversation_data(update=update, key="my_data")
     bot.send_message(message, user_peer, success_callback=success, failure_callback=failure)
     dispatcher.register_conversation_next_step_handler(update, MessageHandler(PhotoFilter(), ask_photo))
     
 
def ask_photo(bot, update):
     message = TextMessage("thanks \ngoodbye ;)")
     user_peer = update.get_effective_user()
     bot.send_message(message, user_peer, success_callback=success, failure_callback=failure)
     dispatcher.finish_conversation(update)
 
updater.run() 

Peer

peer یک شی از هویت کاربران یا گروه‌هاست که با داشتن آن می‌توانیم به یک کاربر پیام دهیم. و شامل پارامتر‌های زیر است:

دو کلاس UserPeer و GroupPeer از Peer ارث برده‌اند و بهتر است برای مشخص‌کردن کاربر و یا گروه بجای اینکه از Peer شی بسازیم از User و Group شی بسازیم. پارامتر های سازنده شی User و Group :

مثال ساده‌ای از ساخت Peer :

from bale.models.base_models import Peer
peer = Peer(peer_type="User", peer_id=770227559, access_hash="6760314230338855869")

Text Message

ساده ترین نوع پیام, پیام متنی است . پارامتر‌های ساخت پیام متنی :

همانطور که ملاحظه می‌کنید برای ساخت پیام متنی صرفا کافیست که رشته‌ای از کاراکتر‌ها را به سازنده کلاس بدهیم و یک شی از آن را بسازیم. می‌توانید در زیر مثالی از ساخت پیام متنی را مشاهده نمایید.

from bale.updater import Updater
from bale.models.messages import TextMessage
 
updater = Updater(token="Your Token")
dispatcher = updater.dispatcher
 
text_message = TextMessage(text="it is a text")

Document Message

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

from bale.updater import Updater
from bale.models.messages import DocumentMessage
 
updater = Updater(token="Your Token")
dispatcher = updater.dispatcher
 
document_message = DocumentMessage(file_id=file_id, access_hash=access_hash, name=name, file_size=file_size,
                mime_type=mime_type, caption_text=caption_text)

Photo Message

پیام تصویری یکی از زیر مجموعه‌ها یا فرزندان پیام فایلی می‌باشد. به عبارت دیگر از DocumentMessage ارث می‌برد. در صورتی که مایل هستید فایلی که محتوای آن عکس می‌باشد را برای کاربرتان ارسال کنید بهتر است از پیام تصویری استفاده کنید. پارامتر‌های ساخت پیام تصویری:

مثال ساده‌ای از ایجاد یک پیام تصویری را می‌توانید در زیر مشاهده کنید.

photo_message = PhotoMessage(file_id=file_id, access_hash=access_hash, name=name, file_size=file_size,
                             mime_type=mime_type, thumb=thumb, width=80, height=80, caption_text=caption_text)  

Video Message

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

مثال ساده‌ای از ساخت پیام ویدیویی:

video_message = VideoMessage(file_id=file_id, access_hash=access_hash, name=name, file_size=file_size,
                             mime_type=mime_type, thumb=thumb, duration=duration, width=80, height=80,
                             caption_text=caption_text) 

Voice Message

پیام صوتی یکی از زیر مجموعه‌ها یا فرزندان پیام فایلی می‌باشد. به عبارت دیگر از DocumentMessage ارث می‌برد. اگر مایل به ارسال پیامی هستید که حاوی فایل صوتی است، می‌توانید از این نوع پیام استفاده کنید. پارامتر‌های ساخت پیام صوتی:

مثال ساده‌ای از ساخت پیام صوتی:

voice_message = VoiceMessage(file_id=file_id, access_hash=access_hash, name=name, file_size=file_size,
                             mime_type=mime_type, duration=duration, caption_text=caption_text)

Template Message

نوع خاص و بسیار جذابی از پیام که طرفدار های زیادی هم در بین توسعه دهندگان بات دارد پیام حاوی دکمه می‌باشد نام این نوع پیام در بله TemplateMessage گذاشته شده است و به شما این قابلیت را می‌دهد که پیام‌هایی از هر جنس که می‌خواهید ( به جز پیام درخواست پول ) را همراه چند دکمه در پایین آن که به دلخواه خودتان مشخص می‌شود، ارسال کنید .

پارامتر‌های سازنده برای ساخت TemplateMessage:

پارامتر های سازنده برای ساختن TemplateMessageButton :

نمونه ساده ای از ساخت Template Message :

from bale.updater import Updater
from bale.models.messages import TemplateMessage,TemplateMessageButton
from bale.models.messages import TextMessage
 
updater = Updater(token="Your Token")
dispatcher = updater.dispatcher
 
btn_list = [TemplateMessageButton(text="yes", value="yes", action=0), TemplateMessageButton("no", "no", 0)]
template_message1 = TemplateMessage(general_message=text_message, btn_list=btn_list)

Purchase Message

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

مثال ساده‌ای از نحوه ساخت پیام درخواست پول را در زیر مشاهده می‌کنید:

purchase_message = PurchaseMessage(msg=text_message, account_number="6221061064199856", amount="111", money_request_type=MoneyRequestType.normal)

متد‌های کلاس ‌Bot

ما در اینجا به اختصار درباره ۳ متود اول توضیحاتی می‌دهیم، برای آشنایی بیشتر با متد‌های دیگر می‌توانید داکیومنت API بات بله را نیز برای درک بیشتر مطالعه کنید:

send_message

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

یک مثال ساده از نحوه ارسال پیام را در زیر مشاهده می‌کنید:

updater = Updater(token="Your Token")
dispatcher = updater.dispatcher
bot = updater.bot
 
def success(result):
    print("success : ", result)
 
def failure(result):
    print("failure : ", result)
 
text_message = TextMessage(text="it is a text")
peer = Peer(peer_type="User", peer_id="*********", access_hash="*******************", success_callback=success,failure_callback=failure)
bot.send_message(message=text_message, peer=peer)

reply

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

یک مثال ساده از نحوه ارسال پیام را در زیر مشاهده می‌کنید :

@dispatcher.message_handler(PhotoFilter())
def some_file_received(bot, update):
    bot.respond(update, message, success_callback=success, failure_callback=failure)

respond

این متد به شما کمک می کند که به راحتی در جواب پیامی که از کاربر دریافت می‌کنیم پیامی بفرستیم، در واقع تفاوتی که این متد با reply دارد این است که reply روی پیام دریافت شده پاسخ می‌فرستد ولی respond همانند send_message عمل می‌کند و فقط کار ارسال پاسخ را آسان‌تر می کند . پارامتر‌های ورودی این متد عبارتند از:

یک مثال ساده از نحوه ارسال پیام را در زیر مشاهده می‌کنید :

@dispatcher.message_handler(PhotoFilter())
def some_file_received(bot, update):
    bot.reply(update, message, success_callback=success, failure_callback=failure)

upload_file :

از این متد برای گرفتن فضا در سیستم مدیریت فایل بله و آپلود کردن فایل یا عکس مورد نظر در این فضا استفاده میشود. ورودی:

در صورت موفقیت آمیز بودن عملیات وارد متد مشخص شده برای success_callback میشویم و خروجی های زیر از طریق این متد قابل دسترس هستند.

download_file:

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

در صورت موفقیت آمیز بودن عملیات وارد متد مشخص شده برای success_callback میشویم و خروجی های زیر از طریق این متد قابل دسترس هستند.

نکته : متغیر byte_stream با استفاده از عملیات فایل پایتون به راحتی قابل ذخیره سازی در مکان دلخواه میباشد.

مثال از بکارگیری متد های upload_file , download_file :

 
def failure(result, user_data):
    print("failure : ", result)
    print(user_data)
 
def final_download_success(result, user_data):
    print("d success : ", result)
    stream = user_data.get("byte_stream", None)
 
    with open("hello", "wb") as file:
        file.write(stream)
        file.close()
 
 
def file_upload_success(result, user_data):
    print("u success : ", result)
    print(user_data)
 
    file_id = user_data.get("file_id", None)
    user_id = user_data.get("user_id", None)
    url = user_data.get("url", None)
    dup = user_data.get("dup", None)
 
    bot.download_file(file_id=file_id, user_id=user_id, file_type="file",
                      success_callback=final_download_success,
                      failure_callback=failure)
 
    bot.upload_file(file="test data", file_type="file", success_callback=file_upload_success, failure_callback=failure)
 

ارتباط با ما