امکان انجام فعالیتهای مالی در کنار گفتو گوهای دوستانه، بله را به محیطی جذاب برای کاربران تبدیل کرده است. علاوه بر این، بله فرصت مناسبی را برای برنامهنویسان ایجاد کرده است تا بتوانند با ایجاد خدمات گوناگون به کسب درآمد بپردازند. در این راستا بله اقدام به معرفی قابلیت ایجاد «بازو» یا بات کرده است. این بازوها میتوانند به کاربران کمک کنند تا خدمات مورد نیاز خود را در بستر بله دریافت کنند.
برنامهنویسان در بله میتوانند «بازو»های کاربردی را برای کاربرانشان توسعه دهند. «بازو» راهکاری جذاب برای ارائه خدمات یا ایجاد کسب و کار در بله است.
توسعهدهندگان به راحتی میتوانند با کاربران خود که مایلند با بازو شروع به صحبت کنند ارتباط برقرار کرده و برای آنها پیامهای گوناگون ارسال کنند. پیامهای ارسالی میتوانند شامل انواع زیر باشند:
برای سهولت بیشتر در استفاده از api، تیم بله کتابخانهای را در محیط جاوا اسکریپت و پایتون آماده کرده است که به راحتی سرویسهای مورد نیاز را در اختیار شما قرار میدهد. در این کتابخانه موارد زیر مهیا شده است:
ایجاد خدماتی از جمله ایمیل، خبر و سایر مواردی که کاربران را ملزم میکند تا از سایتها و برنامههای مختلف استفاده کنند.
بازو اصالتا یک کاربر معمولی است که نیازمند وجود فرد خارجی نیست. کاربران میتوانند برای بازو همانند افراد دیگر پیام ارسال کنند و این پیام مستقیما به برنامهای که برای بازو اجرا شده منتقل میشود و طبق برنامهای که توسعه دهنده نوشته است پاسخی برای کاربر ارسال میشود.
کافی است که پس از اضافه کردن بازو به عنوان یک مخاطب عادی، دکمه شروع را کلیک کنید تا مکالمه بین شما و بازو آغاز شود. شما میتوانید علاوه بر ارسال پیام متنی برای بازو پیامهای تصویری و یا فایل نیز ارسال کنید.
همانطور که در بخش قبل گفته شد توسعهدهنده بات میتواند از template message برای ایجاد سهولت در رابط کاربری بازوی خود استفاده کند. در پیامهای template message توسعهدهنده به ازای هر پیام مشخص میکند که توقع چه نوع جوابی را از کاربر دارد. برای مثال توقع دارد که کاربر یک متن ارسال کند یا یک عکس یا تاریخ و … .
در این صورت کاربر باید همان نوع پاسخی که بازو از او انتظار دارد را در جواب ارسال کند. در این نوع پیام به ازای هر دکمه یک action مشخص میشود که تعیین میکند در صورت فشرده شدن دکمه چه عملی انجام شود. مثلا پس از فشردهشدن دکمه پیامی ارسال شود یا به مرورگر وب و سایتی دیگر منتقل شود و ...
پیام درخواست پول نیز از پیامهایی است که باید به صورت خاص راجع به آن بحث شود. این امکان تنها در بله فراهم است و کمک میکند که بله به بستر کسب و کار و تعاملات مالی تبدیل شود.
بازو میتواند برای کاربران عادی پیام درخواست پول ارسال کند. در صورتی که کاربران پیام درخواست پول را تایید کرده و پرداخت کنند، بازو از پرداخت آنها آگاه خواهد شد. برای ارسال این نوع پیام کافیست که بازو مقدار درخواست پول و همچنین شماره کارت را مشخص کرده و اقدام به ارسال پیام درخواست پول کند.
بعد از مطالعه این داکیومنت شما قادر خواهید بود به راحتی بازوی خود را در بله راه اندازی کنید. دقت نمایید که این کتابخانه به زبان جاوا اسکریپت نوشته شده است. (برای نصب کافی است روی لینکها کلیک کنید.)
NPM: node package manager https://www.npmjs.com
در ابتدا لازم است که شما با بازوی botfather@ شروع به صحبت کنید و از او بخواهید یک بازو با نام و نام کاربری دلخواهتان بسازد. بعد از انجام این فرآیند یک 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 دارای دو پارامتر زیر می باشد:
ورودیهای تابع callback عبارتند از:
Sensitive یک کلاس interface میباشد که با استفاده از کلاسهای فرزند آن مانند photoSensitive ، fileSensitive و textSensitive میتوانید علاوه بر اینکه برروی متنهای ارسالی از طرف کاربر شنود کنید بر روی فایل ء عکس و یا هر چیز دیگری که خودتان مایلید شنود کنید . فقط کافیست که اگر هم کلاس آن وجود ندارد خودتان کلاس را ایجاد کرده و از Sensitive ارث ببرید و متد match را باز نویسی کنید میتوانید مثالی که شامل متد hear می باشد را در زیر ببینید:
"use strict";
const SDK = require("balebot");
const BaleBot = SDK.BaleBot;
const TextMessage = SDK.TextMessage;
const PhotoMessageSensitive = SDK.PhotoMessageSensitive
let bot = new BaleBot("Your Token");
bot.hears(['whats your name', 'name', 'name?'], (message, responder) => {
responder.reply("My name is samplebot!");
});
bot.hears(new PhotoMessageSensitive(), (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 استفاده کنید.
برای ایجاد یک مکالمه که بصورت مداوم بین کاربر و بازو ادامه دارد باید یک شی از نوع 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 سه ورودی زیر را دریافت میکند :
ورودی:
مثال استفاده از این متد را در زیر مشاهده میکنید:
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 مگابایت برای عکس می باشد.
پارامتر های سازنده :
خروجی :
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 میباشد راجع انواع پیامها بیشتر صحبت کنیم.
اگر مایل به ارسال پیامی هستید که شامل فایل میباشد باید از این نوع پیام استفاده کنید . پارامترهای ساخت پیام فایل :
const SDK = require("balebot");
const BaleBot = SDK.BaleBot;
const FileMessage = SDK.FileMessage
var file = new FileMessage(fileId,fileAccessHash,name,fileSize,mimtype,caption)
همانطور که مشاهده کردید کار بسیار راحتیست …
پیام تصویری یکی از زیر مجموعهها یا فرزندان پیام فایلی می باشد. به عبارت دیگر از 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);
پیام ویدیویی یکی از زیر مجموعهها یا فرزندان پیام فایلی میباشد. به عبارت دیگر از 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);
پیام صوتی یکی از زیر مجموعه ها یا فرزندان پیام فایلی می باشد. به عبارت دیگر از fileMessage ارث می برد. اگر مایل به ارسال پیامی هستید که حاوی فایل صوتی است میتوانید از این نوع پیام استفاده کنید. پارامترهای ساخت پیام صوتی:
مثال سادهای از ساخت پیام صوتی :
const SDK = require("balebot");
const BaleBot = SDK.BaleBot;
const AudioMessage = SDK.AudioMessage
var Audio = new AudioMessage(fileId,fileAccessHash,name,fileSize,mimtype,caption,duration);
نوع خاص و بسیار جذابی از پیام که طرفدار های زیادی هم در بین توسعه دهندگان بازو دارد پیام حاوی دکمه می باشدء نام این نوع پیام در بله template message گذاشته شده است و به شما این قابلیت را می دهد که پیام هایی از هر جنس که میخواهید (به جز پیام درخواست پول) را همراه چند دکمه در پایین آن که به دلخواه خودتان مشخص میشود ارسال کنید .
پارامترهای سازنده برای ساخت template message:
پارامترهای مورد نیاز برای ساخت شی SimpleTemplate:
پارامترهای سازنده برای ساختن Button Element:
نمونه سادهای از ساخت template Message:
var simpletemplate = new SimpleTemplate(generalMessage like textMessage,buttonList,responseType like "Text");
var button = new ButtonElement(text like "salam",value like "/hello",1);
simpleTemplate.addbtn(button);
var templateMessage = new TemplateMessage(simpleTemplate);
اگر مایلید که پیامی حاوی درخواست پول برای کاربر خود ارسال کنید میتوانید از این نوع پیام استفاده کنید. پارامترهای سازنده عبارتنداز :
مثال سادهای از نحوه ساخت پیام درخواست پول را در زیر مشاهده میکنید :
var purchaseMessage = new PurchaseMessage(msg like photoMessage,accountNumber, amount,MoneyRequestType.normal);
این نوع پیام به عنوان رسید پرداخت استفاده می شود و زمانی که بازو شما درخواست پولی را ارسال کرده باشد و درخواست پول پرداخت شود پیامی از نوع رسید برای بازو شما ارسال خواهد شد. توجه: بازو نمیتواند پیام رسید ارسال کند و صرفا میتواند این پیام را دریافت کند. پارامترهای سازنده پیام رسید عبارتند از:
پارامتر transferInfo خود مجموعه ای از پارامتر هاست که عبارتند از:
خوب با توجه به این که تمامی انواع پیام را تا اینجا بررسی کردیم کافیست بدانیم که چطور میتوانیم این پیام هارا برای کاربرانمان ارسال کنیم. این کار به وسیله تابع send که در پایین توضیح داده میشود امکان پذیر است.
این متد به شما کمک میکند که پیامتان را برای کاربرتان ارسال کنید. پارامترهای ورودی این متد عبارتند از :
یک مثال ساده از نحوه ارسال پیام را در زیر مشاهده میکنید :
bot.send(any message,new User(id,accessHash));
خب همانطور که قول داده بودیم باید راجع به peer و responder بیشتر صحبت کنیم.
یک شی از هویت کاربران است که با داشتن آن میتوانیم به یک کاربر پیام دهیم و شامل پارامترهای زیر است :
دو کلاس User و Group از Peer ارث بردهاند و بهتر است برای مشخص کردن کاربر و یا گروه بجای اینکه از Peer شی بسازیم از User و Group شی بسازیم. پارامتر های سازنده شی User و Group
شی است که شامل پارامتر 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);
});
این کتابخانه به شما کمک میکند که بازو خود را در بله راه اندازی کنید و به راحتی از api های بله که در اختیار شما قرار میگیرد، استفاده نمایید. این کتابخانه با زبان پایتون توسعه داده شده است و نسخه ۳.۵+ این زبان را پشتیبانی میکند. نیازمندیها :
تمام مثال های این مستند را میتوانید در گیت هاب مشاهده کنید.
پس از نصب پایتون شما میتوانید با استفاده از ابزار pip تمام نیازمندیهای پروژه را نصب کنید:
pip3 install balebot
روش دیگر برای دریافت کتابخانه مراجعه به لینک های زیر در سایت گیت هاب است.
و همچنین مثال های کاربردی بازو را میتوانید در لینک زیر مشاهده کنید.
مثال های کاربردی بازوی بله در Github
در اولین قدم لازم است که شما با بازو botfather@ شروع به صحبت کنید و از بازو پدر بخواهید که یک بازو با نام و نام کاربری دلخواهتان بسازد. بعد از انجام این فرآیند یک 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 پایتون استفاده نمایید میتوانید از آن استفاده کنید.
بعد از انجام مراحل بالا احتمالا این به ذهن شما میرسد که چطور میتوانیم به درخواستهای کاربرانمان پاسخ دهیم یا چطور میتوانیم با کاربرانمان گفتگو کنیم. کافیست ادامه مطالب را مطالعه کنید.
یک بازو می تواند در دوحالت realtime وpolling پیام ها را از سرور دریافت کند که برای تنظیم حالت های مختلف باید قبل از ساختن شئ Updater کانفیگ را تغییر داد.در ادامه حالت های مختلف امکان پذیر برای کانفیگ این دوحالت بررسی می شوند.
مفهوم realtime :
پردازش realtime به این معنی است که یک بازو به محض دریافت یک پیام از سرور آن را پردازش و پاسخ مناسب را ارسال می کند.
مفهوم polling :
پردازش در حالت polling به این صورت است که یک بازو در بازه های زمانی مشخص به سرور درخواست می دهد تا سرور تعدادی از پیام هایش را به صورت یک بسته برای بازو ارسال کند و سپس پیام های آن بسته را پردازش می کند.
در فایل کانفیگ چهار پارامتر continue_last_processed_seq , real_time_fetch_updates, timeInterval , updates_number برای ایجاد و تنظیم حالت های مختلف دریافت پیام وجود دارد.
real_time_fetch_updates : یک پارامتر از نوع boolean بوده و درصورتی که مقدار آن true باشد بازو پیام ها را به صورت real time و در غیر این صورت پیام ها را به صورت polling دریافت خواهد کرد.( در حالت polling بعد از پردازش هر پیام بازو شماره پیام پردازش شده را در یک فایل با نام "last_seq.txt" ذخیره می کند.)
continue_last_processed_seq : یک پارامتر از نوع boolean بوده و درصورتی که مقدار آن true باشد بازو از آخرین پیام پردازش شده که شماره آن در فایل "last_seq.txt" ذخیره شده است شروع به دریافت پیام ها از سرور میکند و اگر "last_seq.txt" وجود نداشته باشد بازو پیام هارا از لحظه اجرای بازو و در حالت polling دریافت خواهد کرد. و درصورتی که مقدار آن false باشد از لحظه اجرای بازو پیام ها را از سرور دریافت می کند.
timeInterval :فاصله زمانی بین درخواست های گرفتن بسته های پیام های کاربران از سرور می باشد.
updates_number : تعداد پیام هایی است که یک بازو در حالت polling در یک بسته از سمت سرور دریافت می کند.
بدیهی است که درصورتی که یک بازو در حالت polling کار می کند مقادیر timeInterval و updates_number باید به صورت نسبی طوری باشد که بازو بتواند در بازه زمانی تعیین شده پیام های دریافتی در یک بسته را پردازش بکند.
توجه:
درصورتی که بازو در یک بازه زمانی در حالت polling و سپس بعد از آن مدتی در حالت realtime کار کرده باشد اگر دوباره کانفیگ بازو به حالت polling تغییر داده شود برای جلوگیری از پردازش دوباره پیام هایی که در بازه زمانی real time پردازش شده اند لازم است پارامتر continue_last_processed_seq برابر false بشود.
با استفاده از از کلاسهای 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 استفاده کنیم و مراحل زیر را طی کنیم :
ایجاد یک 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 یک شی از هویت کاربران یا گروههاست که با داشتن آن میتوانیم به یک کاربر پیام دهیم. و شامل پارامترهای زیر است:
دو کلاس 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")
ساده ترین نوع پیام, پیام متنی است . پارامترهای ساخت پیام متنی :
همانطور که ملاحظه میکنید برای ساخت پیام متنی صرفا کافیست که رشتهای از کاراکترها را به سازنده کلاس بدهیم و یک شی از آن را بسازیم. میتوانید در زیر مثالی از ساخت پیام متنی را مشاهده نمایید.
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")
پیام تصویری یکی از زیر مجموعهها یا فرزندان پیام فایلی میباشد. به عبارت دیگر از 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)
پیام ویدیویی یکی از زیر مجموعهها یا فرزندان پیام فایلی میباشد. به عبارت دیگر از 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)
پیام صوتی یکی از زیر مجموعهها یا فرزندان پیام فایلی میباشد. به عبارت دیگر از 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
اگر مایلید که پیامی حاوی درخواست پول برای کاربر خود ارسال کنید میتوانید از این نوع پیام استفاده کنید. پارامترهای سازنده عبارتند از:
توضیحات | نوع | نام | شماره |
پیامی که میخواهید همراه درخواست پول فرستاده شود(این پیام حتما باید از نوع عکس باشد). | BaseMessage | msg | ۱ |
شماره کارت یا حساب که مایلید پول به آن واریز شود مثلا : "**** **** ۹۹۱۸ ۶۰۳۷" |
String | account_number | ۲ |
مقدار پولی که مایلید درخواست دهید. مثلا ۱۰۰۰ریال که معادل۱۰۰ تومن می باشد.(واحد ریال است) | String | amount | ۳ |
بسته به نوع پرداخت شما متفاوت است ولی معمولا از کلاس MoneyRequestType مقدار normal را انتخاب می کنند. | MoneyRequestType | money_request_type | ۴ |
مثال سادهای از نحوه ساخت پیام درخواست پول را در زیر مشاهده میکنید:
purchase_message = PurchaseMessage(msg=text_message, account_number="6221061064199856", amount="111", money_request_type=MoneyRequestType.normal)
ما در اینجا به اختصار درباره ۳ متود اول توضیحاتی میدهیم، برای آشنایی بیشتر با متدهای دیگر میتوانید داکیومنت 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 کنید. پارامترهای ورودی این متد عبارتند از :
آپدیتی که از طرف کاربر به بازو می رسد. | FatSeqUpdate | update | 1 |
هر نوع پیامی که مایلید | BaseMessage | message | 2 |
یک مثال ساده از نحوه ارسال پیام را در زیر مشاهده میکنید :
@dispatcher.message_handler(PhotoFilter())
def some_file_received(bot, update):
bot.reply(update, message, success_callback=success, failure_callback=failure)
respond
این متد به شما کمک می کند که به راحتی در جواب پیامی که از کاربر دریافت میکنیم پیامی بفرستیم، در واقع تفاوتی که این متد با reply دارد این است که reply روی پیام دریافت شده پاسخ میفرستد ولی respond همانند send_message عمل میکند و فقط کار ارسال پاسخ را آسانتر می کند . پارامترهای ورودی این متد عبارتند از:
آپدیتی که از طرف کاربر به بازو می رسد. | FatSeqUpdate | update | 1 |
هر نوع پیامی که مایلید | BaseMessage | message | 2 |
یک مثال ساده از نحوه ارسال پیام را در زیر مشاهده میکنید :
@dispatcher.message_handler(PhotoFilter())
def some_file_received(bot, update):
bot.respond(update, message, success_callback=success, failure_callback=failure)
edit message
از این متد برای ویرایش محتوای یک پیام که از قبل ارسال شده است استفاده میشود. پارامترهای ورودی این متد عبارتند از:
کاربری که میخواهید به آن پیام ارسال کنید. | User or Group | peer | 1 |
پیام متنی، حاوی فایل و یا template message | BaseMessage | message | 2 |
شناسه پیامی که قبلا ارسال شده. | String | random_id | 3 |
یک مثال ساده از نحوه ویرایش پیام را در زیر مشاهده میکنید:
@dispatcher.command_handler(commands='/edit')
def edit(bot, update):
user_peer = update.get_effective_user()
message = TextMessage('*message edited*')
# edit a sent message
bot.edit_message(message=message, user_peer=user_peer, random_id=request_random_id,success_callback=success,failure_callback=failure)
از این متد برای گرفتن فضا در سیستم مدیریت فایل بله و آپلود کردن فایل یا عکس مورد نظر در این فضا استفاده میشود. ورودی:
در صورت موفقیت آمیز بودن عملیات وارد متد مشخص شده برای success_callback میشویم و خروجی های زیر از طریق این متد قابل دسترس هستند.
از این متد برای دانلود فایلی که در سیستم مدیریت فایل بله وجود دارد استفاده میشود. ورودی:
در صورت موفقیت آمیز بودن عملیات وارد متد مشخص شده برای 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)
ابتدا لازم است شما با آیدی botfather@ که مسئول مدیریت بازوها است، صحبت کنید.
برای شروع دستور start/ را همانند زیر وارد کنید:
دکمه help را بفشارید :
به قسمت ساخت بازوی جدید بروید:
نام یا عنوان بازوی خود را به دلخواه انتخاب کنید :
آیدی ای که قرار است با آن بازوی خود را صدا بزنید وارد کنید :
اگر پیغام بالا برای شما نمایش داده شد بدین معناست که بازوی شما با موفقیت ساخته شد.
در این پیغام شما یک توکن (token) و یک user id دریافت میکنید که برای راهاندازی بازو به آن احتیاج دارید.
نکته : در حفظ و نگهداری توکن خود کوشا باشید چون تنها راه کنترل بازوی شماست. اگر فردی توکن بازوی شما را داشته باشد بهراحتی میتواند بازوی شما را تغییر داده و امنیت آن را تهدید کند.
حال که توکن بازو را در اختیار دارید همانطور که در مثال زیر مشاهده میکنید باید توکن خود را در قسمت "YOUR TOKEN" قرار دهید.
در ابتدا شما نیاز به یک ارتباط با سرور از نوع websocket دارید.
برای این کار میتوانید از کتابخانه balebot پایتون کمک بگیرید. نمونه ساده این کار در کد زیر آمده است :
"""Simple Bot to Reply to Bale messages."""
import asyncio
from balebot.updater import Updater
# Bale Bot Authorization Token
updater = Updater(token="YOUR TOKEN",
loop=asyncio.get_event_loop())
# Define dispatcher
dispatcher = updater.dispatcher
"""
Your Code Comes here ...
"""
updater.run()
اگر اتصال موفقیت آمیز بود باید چیزی مشابه زیر را در کنسول خود مشاهده نمایید :
2018-05-12 11:31:52,669 network.py:32 DEBUG:
"connect: wss://api.bale.ai/v1/bots/TOKEN"
در غیر این صورت error زیر را مشاهده خواهید کرد :
2018-05-12 11:36:09,011 network.py:112 WARNING:
"network connection disconnected."
2018-05-12 11:36:09,012 network.py:36 ERROR:
"connect error: 500, message='Invalid response status'"
Traceback (most recent call last):
File "/home/ehsan/PycharmProjects/example_bots/venv/lib/python3.5/site-packages/balebot/connection/network.py", line 31, in connect
self._ws = await self._session.ws_connect(self.construct_url())
File "/home/ehsan/PycharmProjects/example_bots/venv/lib/python3.5/site-packages/aiohttp/helpers.py", line 109, in __await__
ret = yield from self._coro
File "/home/ehsan/PycharmProjects/example_bots/venv/lib/python3.5/site-packages/aiohttp/client.py", line 465, in _ws_connect
headers=resp.headers)
aiohttp.client_exceptions.WSServerHandshakeError: 500, message='Invalid response status'
اکنون که ارتباط بازوی شما با سرور برقرار شد می توانید شروع به طراحی بازوی خود کنید.
برای شروع به مثال ساده زیر توجه کنید :
"""Simple Bot to Reply to Bale messages."""
import asyncio
from balebot.filters import TextFilter
from balebot.models.messages import TextMessage
from balebot.updater import Updater
# Bale Bot Authorization Token
updater = Updater(token="PUT YOUR TOKEN HERE",
loop=asyncio.get_event_loop())
# Define dispatcher
dispatcher = updater.dispatcher
# Both of success and failure functions are optional
def success(response, user_data):
print("success : ", response)
print(user_data)
def failure(response, user_data):
print("failure : ", response)
print(user_data)
@dispatcher.message_handler(filters=TextFilter(keywords=["Hello"])) # filter text the client enter to bot
def echo(bot, update):
message = TextMessage('*Hello*')
# Send a message to client
bot.reply(update, message, success_callback=success, failure_callback=failure)
# Run the bot!
updater.run()
در مثال بالا بعد از برقراری ارتباط با سرور ما یک تابع به نام echo تعریف کردیم که به ازای فرستادن کلمه Hello به بازو همان کلمه را بولد شده بر می گرداند.
handler چیست؟
برای تابع مذکور از handler زیر کمک گرفتیم :
@dispatcher.message_handler(filters=TextFilter(keywords=["Hello"]))
این handler همانطور که از اسمش پیداست به ما کمک میکند تا پیامهای دریافتی از کاربر را پردازش و فیلترهای دلخواه خود را در آنها اعمال کنیم. مثلا در handler فوق ما با کمک message_handler که در کتابخانه balebot موجود است پیامهای کاربر به بازو را دریافت میکنیم. بعد از آن با استفاده از یک TextFilter میتوانیم فیلتر دلخواه خود را روی متن کاربر اعمال کنیم که میتواند با استفاده از keywords یا pattern باشد.
بعد از ارسال پیام کاربر به بازو اگر پیام فقط شامل کلمه Hello باشد، بازو وارد تابع echo میشود و ادامه میدهد.
چگونه با بازوی خود یک پیام متنی بفرستیم؟
در مرحله اول یک object از کلاس TextMessage با متن دلخواه ساخته و آن را داخل متغیر message میریزد.
در مرحله دوم با استفاده از تابع reply در کلاس bot که در کتابخانه پایتون balebot موجود است اقدام به پاسخ به کاربر میکنیم.
این تابع به دو پارامتر نیاز دارد که شامل update و message میباشد. دومی را که ما پیش از این ساخته و داخل message قرار دادهایم. update نیز از سمت سرور به بازو فرستاده میشود و جزء پارامترهای echo میباشد. پس آن را هم بهراحتی به reply پاس میدهیم.
چگونه از فرستاده شدن پیغام خود مطمئن شویم؟
در آخر از دو تابع success_callback و failure_callback برای اطمینان از فرستاده شدن پاسخ به کاربر بهره میبریم. بدین شکل که اگر پاسخ ارسال شده بود تابع reply بصورت خودکار تابع success_callback را فراخوانی کرده و دو پارامتر response و user data را که خود از سرور دریافت میکند به آن پاس میدهد. درغیر این صورت تابع failure_callback توسط reply فراخوانی شده پاسخ مناسب چاپ میشود.
تصویر تعامل یک کاربر با بازو ساده echobot:
یکی از انواع پیام ها است که برای ارسال یک محل بر روی نقشه از آن استفاده می شود.
مثال سادهای از ایجاد یک location message درزیر مشاهده میکنید.
from bale.updater import Updater
location_message = LocationMessage(longitude="51.41714821748457", latitude="35.73122955392002")
bot.send_message(location_message, user_peer, success_callback=success, failure_callback=failure)
ContactMessage یکی از نواع پیام ها برای ارسال اطلاعات تماس یک مخاطب به کاربر استو
در صورتی که مایل هستید یک مخاطب ارسال کنید میتوانید از این نوع پیام استفاده کنید.
مثال ساده ای از ساخت یک ContactMessage:
contact_message = ContactMessage(name="test contact", emails=["test@test.com"], phones=["09123456789"])
bot.send_message(contact_message, user_peer, success_callback=success, failure_callback=failure)
پیام حاوی استیکر یکی از پیام های جذاب است.در صورت تمایل برای ارسال یک پیام حاوی استیکر ابتدا نیاز است تا اطلاعات استیکر مورد نظر را به دست آورید،سپس یک پیام حاوی استیکر ایجاد کنید.
مثال سادهای از ایجاد یک پیام حاوی استیکر را میتوانید در زیر مشاهده کنید:
im_file_loc = FileLocation(file_id="-2709843113063612158", access_hash="549755813890")
im_512_loc = ImageLocation(width=512, height=512, file_size=12480, file_location=im_file_loc)
im_256_loc = ImageLocation(width=256, height=256, file_size=6618, file_location=im_file_loc)
sticker_message = StickerMessage(sticker_id=367893924, sticker_collection_id=239060415,sticker_collection_access_hash="-5500663794674697720",image512=im_512_loc,image256=im_256_loc)
bot.send_message(sticker_message, user_peer, success_callback=success, failure_callback=failure)
ساده ترین نوع پیام, پیام متنی است .
بله:
برای ارسال یک پیام متنی در بله باید پارامتر های زیر در قالب جیسون در یک درخواست ارسال پیام در ارتباط وب سوکت برای سرور بله ارسال شود.
Description | Type | Field |
value is "Text" | String |
$type
|
text of message | String |
text
|
قالب جیسون پیام متنی:
{ "$type": "Text", "text": "*Hello*" }
تلگرام
برای ارسال یک پیام متنی از طریق sendMessage پارامترهای زیر باید ارسال شود.
Description | Type | Field |
Integer or String |
chat_id
|
|
text of message | String |
text
|
پارامتر chat_id در درخواست ارسال پیام متنی میتواند از نوع رشته باشد که در این صورت باید نام کاربری کانال مورد نظر باشد.همچنین میتواند از نوع عدد باشد که در این صورت شناسه مکالمه یا شناسه مخاطب مورد خواهد بود.
همچنین پارامتر های اختیاری دیگری را نیز میتوان ارسال کرد که در زیر به توضیح مختصری درباره این پارامتر ها میپردازیم.
اگر مایل به ارسال پیامی هستید که شامل فایل میباشد باید از این نوع پیام استفاده کنید .
بله:
قبل از ارسال پیام حاوی فایل ابتدا باید فایل مورد نظر آپلود شود و fileId و accessHash آن بدست آید.
برای ارسال یک پیام حاوی فایل در بله باید پارامتر های زیر در قالب جیسون در یک درخواست ارسال پیام در ارتباط وب سوکت برای سرور بله ارسال شود.
ارسال این نوع پیام دارای محدودیت حجم ارسال 50 مگا بایتی می باشد.
Description | Type | Field |
value is "Document" | String |
$type
|
file id | Integer |
fileId
|
file access hash | String |
accessHash
|
should be 1 always | Integer |
fileStorageVersion
|
file size in bytes | Integer |
fileSize
|
name of file | String |
name
|
MimeType of file | String |
mimeType
|
Optinal(value is "checkSum") | String |
checkSum
|
Optinal(value is "algorithm") | String |
algorithm
|
Optinal | Thumb |
thumb
|
Optinal | Extra |
ext
|
Optinal | TextMessage |
caption
|
قالب جیسون پیام حاوی فایل:
{ "ext": null, "caption": { "$type": "Text", "text": "bale document message" }, "accessHash": "259204777", "fileSize": "5273", "checkSum": "checkSum", "thumb": null, "name": "flask_app.py", "fileStorageVersion": 1, "fileId": "8763054896817308674", "mimeType": "text/plain", "algorithm": "algorithm", "$type": "Document" }
تلگرام:
برای ارسال پیام حاوی سند از طریق sendDocument پارامترهای زیر باید ارسال شود.
Description | Type | Field |
Integer or String |
chat_id
|
|
String or InputFile |
document
|
پارامتر chat_id در درخواست ارسال سند میتواند از نوع رشته باشد که در این صورت باید نام کاربری کانال مورد نظر باشد.همچنین میتواند از نوع عدد باشد که در این صورت شناسه مکالمه یا شناسه مخاطب مورد خواهد بود
پارامتر document در درخواست ارسال سند میتواند از نوع رشته باشد که در این صورت باید شناسه سندی که قبلا در یکی از سرورهای تلگرام آپلود شده است و یا آدرس http یک سند موجود در اینترنت باشد تا سرورهای تلگرام از آن استفاده کنند. همچنین میتواند خود سند باشد که در این صورت سند مورد نظر در قالب multipart/form-data آپلود خواهد شد.بات های تلگرام در حال حاضر برای ارسال سند محدودیت حجم 50 مگابایتی دارند.
همچنین پارامتر های اختیاری دیگری را نیز میتوان ارسال کرد که در زیر به توضیح مختصری درباره این پارامتر ها میپردازیم.
پیام ویدیویی یکی از زیر مجموعهها یا فرزندان پیام فایلی میباشد. به عبارت دیگر از DocumentMessage ارث میبرد. اگر مایل هستید پیامی برای کاربرتان ارسال کنید که شامل فایل ویدیویی است از این نوع پیام میتوانید استفاده کنید.
بله:
قبل از ارسال پیام ویدیویی مانند پیام حاوی فایل ابتدا باید فایل مورد نظر آپلود شود و fileId و accessHash آن بدست آید.
برای ارسال پیام ویدیویی باید thumb و ext نیز مشخص شوند و پارامتر های زیر در قالب جیسون در یک درخواست ارسال پیام در ارتباط وب سوکت برای سرور بله ارسال شود.
ارسال این نوع پیام دارای محدودیت حجم ارسال 50 مگا بایتی می باشد.
Description | Type | Field |
value is "Document" | String |
$type
|
file id | Integer |
fileId
|
file access hash | String |
accessHash
|
should be 1 always | Integer |
fileStorageVersion
|
file size in bytes | Integer |
fileSize
|
name of file | String |
name
|
MimeType of file | String |
mimeType
|
Optinal(value is "checkSum") | String |
checkSum
|
Optinal(value is "algorithm") | String |
algorithm
|
Optinal | Thumb |
thumb
|
Optinal | Extra |
ext
|
Optinal | TextMessage |
caption
|
قالب جیسون پیام ویدیویی:
{ "thumb": { "thumb": "None", "width": 80, "height": 80 }, "fileSize": "664649", "fileStorageVersion": 1, "ext": { "width": 80, "$type": "Video", "duration": 9, "height": 80 }, "caption": { "text": "Bale", "$type": "Text" }, "algorithm": "algorithm", "fileId": "2901655166166697217", "accessHash": "259204777", "name": "Bale", "$type": "Document", "mimeType": "video/mpeg", "checkSum": "checkSum" }
پارامتر fileId از نوع عددی است و مشخص کننده شناسه ویدیو آپلود شد بر روی سرور های بله است.
پارامتر accessHash از نوع رشته ای و در حقیقت یک کلید یکتا برای بازو به منظور دسترسی به ویدیو مورد نظر است.
تلگرام:
برای ارسال یک پیام ویدیویی از طریق sendVideo پارامتر های زیر باید ارسال شود.
Description | Type | Field |
Integer or String |
chat_id
|
|
String or InputFile |
video
|
در حال حاضر در تلگرام فقط فرمت ویدیویی mp4 به عنوان ویدیو پشتیبانی میشود.و بقیه فرمت های ویدیویی در قالب سند ارسال میشوند.
پارامتر chat_id در درخواست ارسال پیامویدیویی میتواند از نوع رشته باشد که در این صورت باید نام کاربری کانال مورد نظر باشد.همچنین میتواند از نوع عدد باشد که در این صورت شناسه مکالمه یا شناسه مخاطب مورد خواهد بود.
پارامتر video در درخواست ارسال ویدیو میتواند از نوع رشته باشد که در این صورت باید شناسه ویدیویی که قبلا در یکی از سرورهای تلگرام آپلود شده است و یا آدرس http یک ویدیو موجود در اینترنت باشد تا سرورهای تلگرام از آن استفاده کنند. همچنین میتواند خود ویدیو باشد که در این صورت ویدیو مورد نظر در قالب multipart/form-data آپلود خواهد شد.بات های تلگرام در حال حاضر برای ارسال ویدیو محدودیت حجم 50 مگابایتی دارند.
همچنین پارامتر های اختیاری دیگری را نیز میتوان ارسال کرد که در زیر به توضیح مختصری درباره این پارامتر ها میپردازیم.
پیام تصویری یکی از زیر مجموعهها یا فرزندان پیام فایلی میباشد. به عبارت دیگر از DocumentMessage ارث میبرد. در صورتی که مایل هستید فایلی که محتوای آن عکس میباشد را برای کاربرتان ارسال کنید بهتر است از پیام تصویری استفاده کنید.
بله:
قبل از ارسال پیام تصویری مانند پیام حاوی فایل ابتدا باید تصویر مورد نظر آپلود شود و fileId و accessHash آن بدست آید.
برای ارسال پیام تصویری باید thumb و ext نیز مشخص شوند و پارامتر های زیر در قالب جیسون در یک درخواست ارسال پیام در ارتباط وب سوکت برای سرور بله ارسال شود.
ارسال این نوع پیام دارای محدودیت حجم ارسال 50 مگا بایتی می باشد.
Description | Type | Field |
value is "Document" | String |
$type
|
file id | Integer |
fileId
|
file access hash | String |
accessHash
|
should be 1 always | Integer |
fileStorageVersion
|
file size in bytes | Integer |
fileSize
|
name of file | String |
name
|
MimeType of file | String |
mimeType
|
Optinal(value is "checkSum") | String |
checkSum
|
Optinal(value is "algorithm") | String |
algorithm
|
Optinal | Thumb |
thumb
|
Optinal | Extra |
ext
|
Optinal | TextMessage |
caption
|
قالب جیسون پیام تصویری:
{ "checkSum": "checkSum", "mimeType": "image/jpeg", "fileSize": "5273", "fileId": "7772386124098241537", "algorithm": "algorithm", "fileStorageVersion": 1, "$type": "Document", "accessHash": "259204777", "caption": { "$type": "Text", "text": "Bale" }, "thumb": { "height": 80, "thumb": "None", "width": 80 }, "ext": { "$type": "Photo", "height": 80, "width": 80 }, "name": "Bale" }
تلگرام:
برای ارسال عکس از طریق sendPhoto پارامتر های زیر باید ارسال شود.
Description | Type | Field |
Integer or String |
chat_id
|
|
String or InputFile |
photo
|
پارامتر chat_id در درخواست ارسال عکس میتواند از نوع رشته باشد که در این صورت باید نام کاربری کانال مورد نظر باشد.همچنین میتواند از نوع عدد باشد که در این صورت شناسه مکالمه یا شناسه مخاطب مورد خواهد بود.
پارامتر photo در درخواست ارسال عکس میتواند از نوع رشته باشد که در این صورت باید شناسه عکسی که قبلا در یکی از سرورهای تلگرام آپلود شده است و یا آدرس http یک عکس موجود در اینترنت باشد تا سرورهای تلگرام از آن استفاده کنند. همچنین میتواند خود عکس باشد که در این صورت عکس مورد نظر در قالب multipart/form-data آپلود خواهد شد.
همچنین پارامتر های اختیاری دیگری را نیز میتوان ارسال کرد که در زیر به توضیح مختصری درباره این پارامتر ها میپردازیم.
پیام صوتی یکی از زیر مجموعهها یا فرزندان پیام فایلی میباشد. به عبارت دیگر از DocumentMessage ارث میبرد. اگر مایل به ارسال پیامی هستید که حاوی فایل صوتی است، میتوانید از این نوع پیام استفاده کنید.
بله:
قبل از ارسال پیام صوتی مانند پیام حاوی فایل ابتدا باید صوت مورد نظر آپلود شود و fileId و accessHash آن بدست آید.
برای ارسال پیام صوتی باید ext نیز مشخص شوند و پارامتر های زیر در قالب جیسون در یک درخواست ارسال پیام در ارتباط وب سوکت برای سرور بله ارسال شود.
ارسال این نوع پیام دارای محدودیت حجم ارسال 50 مگا بایتی می باشد.
Description | Type | Field |
value is "Document" | String |
$type
|
file id | Integer |
fileId
|
file access hash | String |
accessHash
|
should be 1 always | Integer |
fileStorageVersion
|
file size in bytes | Integer |
fileSize
|
name of file | String |
name
|
MimeType of file | String |
mimeType
|
Optinal(value is "checkSum") | String |
checkSum
|
Optinal(value is "algorithm") | String |
algorithm
|
Optinal | Thumb |
thumb
|
Optinal | Extra |
ext
|
Optinal | TextMessage |
caption
|
قالب جیسون پیام صوتی:
{ "fileSize": "27033", "fileId": "-355203828421884927", "thumb": null, "checkSum": "checkSum", "caption": { "$type": "Text", "text": "Bale" }, "fileStorageVersion": 1, "mimeType": "audio/ogg", "$type": "Document", "name": "Bale", "ext": { "$type": "Voice", "duration": 9 }, "accessHash": "259204777", "algorithm": "algorithm" }
تلگرام:
برای ارسال عکس از طریق sendVoice پارامتر های زیر باید ارسال شود.
Description | Type | Field |
Integer or String |
chat_id
|
|
String or InputFile |
voice
|
پارامتر chat_id در درخواست ارسال پیام صوتی میتواند از نوع رشته باشد که در این صورت باید نام کاربری کانال مورد نظر باشد.همچنین میتواند از نوع عدد باشد که در این صورت شناسه مکالمه یا شناسه مخاطب مورد خواهد بود.
پارامتر voice در درخواست ارسال پیام صوتی میتواند از نوع رشته باشد که در این صورت باید شناسه صوتی که قبلا در یکی از سرورهای تلگرام آپلود شده است و یا آدرس http یک صوت موجود در اینترنت باشد تا سرورهای تلگرام از آن استفاده کنند. همچنین میتواند خود صوت باشد که در این صورت عکس مورد نظر در قالب multipart/form-data آپلود خواهد شد.
همچنین voice ها باید با فرمت .ogg ارسال شوند و فرمت های دیگر ممکن است در قالب سند و یا موزیک ارسال شوند.
بات های تلگرام در حال حاضر برای ارسال ویدیو محدودیت حجم 50 مگابایتی دارند.
همچنین پارامتر های اختیاری دیگری را نیز میتوان ارسال کرد که در زیر به توضیح مختصری درباره این پارامتر ها میپردازیم.
اگر مایلید که پیامی حاوی درخواست پول برای کاربر خود ارسال کنید میتوانید از این نوع پیام استفاده کنید.
بله:
برای ارسال یک پیام حاوی درخواست پول در بله باید پارامتر های زیر در قالب جیسون در یک درخواست ارسال پیام در ارتباط وب سوکت برای سرور بله ارسال شود.
Description | Type | Field |
value is "PurchaseMessage" | String |
$type
|
any message(now just photo message) | Message |
msg
|
the number of card or account that you request for | String |
accountNumber
|
amount of money you want | String |
amount
|
object of type of money request(with field $type) | Object |
moneyRequestType
|
regex of the amout | String | regexAmount |
پارامتر های یک moneyRequestType:
Description | Type | Field |
value is "MoneyRequestNormal" | String |
moneyRequestType.$type
|
قالب جیسون پیام حاوی پول:
{ "amount": "10", "accountNumber": "6037991067471130", "msg": { "mimeType": "image/jpeg", "accessHash": "1208576569", "fileStorageVersion": 1, "caption": { "text": "", "$type": "Text" }, "fileSize": "164985", "checkSum": "checksum", "thumb": { "width": 67, "thumb": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAA4KCw0LCQ4NDA0QDw4RFiQXFhQUFiwgIRokNC43NjMuMjI6QVNGOj1OPjIySGJJTlZYXV5dOEVmbWVabFNbXVn/2wBDAQ8QEBYTFioXFypZOzI7WVlZWVlZWVlZWVlZWVlZWVlZWVlZWVlZWVlZWVlZWVlZWVlZWVlZWVlZWVlZWVlZWVn/wAARCABaAEMDASIAAhEBAxEB/8QAFwABAQEBAAAAAAAAAAAAAAAAAAECB//EACAQAQABBAIDAQEAAAAAAAAAAAABETFBYSGBAlFxkaH/xAAVAQEBAAAAAAAAAAAAAAAAAAAAAf/EABQRAQAAAAAAAAAAAAAAAAAAAAD/2gAMAwEAAhEDEQA/AOfaRcgpN0osoBsMgB+ABSNdh0CKk8ZVJAFQAuFOALFgA5Cm4BV7RSREIhcn6CXBAUCASmheNAKi3TAKVTIBoAD2ACC9AKmFsldAqf1cpGwBUADJUDsSoDQk3nskVU5azP1MwCEXU8uPLj0IhsyexSgs3n6A/9k=", "height": 90 }, "algorithm": "algorithm", "name": "capture_481409442272743531.jpg", "ext": { "width": 873, "$type": "Photo", "height": 1164 }, "fileId": "-4546383823826975485", "$type": "Document" }, "$type": "PurchaseMessage", "moneyRequestType": { "$type": "MoneyRequestNormal" }, "regexAmount": "[10]" }
در تلگرام معادل این نوع پیام ، پیامی وجود ندارد.
یکی از انواع پیام ها است که برای ارسال یک محل بر روی نقشه از آن استفاده می شود.
بله:
برای ارسال یک محل روی نقشه در بله باید پارامتر های زیر در قالب جیسون در یک درخواست ارسال پیام در ارتباط وب سوکت برای سرور بله ارسال شود.
Description | Type | Field |
value is "Json" | String |
$type
|
string of rawJson location | String |
rawJson
|
پارامتر rawJson از نوع رشته ای و شامل جیسون نمایش دهنده یک نقطه بر روی نقشه است.
این جیسون خود 2 پارامتر دارد:
قالب جیسون LocationMessage:
{ "$type": "Json", "rawJson": "{\"dataType\": \"location\", \"data\": {\"location\": {\"longitude\": 51.41714821748457, \"latitude\": 35.73122955392002}}}" }
تلگرام:
برای ارسال یک نقطه روی نقشه از طریق sendLocation پارامتر های زیر باید ارسال شود.
Description | Type | Field |
Latitude of the location | Float |
latitude
|
Longitude of the location | Float |
longtitude
|
همچنین پارامتر های اختیاری دیگری را نیز میتوان ارسال کرد که در زیر به توضیح مختصری درباره این پارامتر ها میپردازیم.
ContactMessage یکی از انواع پیام ها برای ارسال اطلاعات تماس یک مخاطب به کاربر است و
در صورتی که مایل هستید یک مخاطب ارسال کنید میتوانید از این نوع پیام استفاده کنید.
بله:
برای ارسال یک پیام حاوی اطلاعات یک مخاطب در بله باید پارامتر های زیر در قالب جیسون در یک درخواست ارسال پیام در ارتباط وب سوکت برای سرور بله ارسال شود.
Description | Type | Field |
value is "Json" | String |
$type
|
string of rawJson contact | String |
rawJson
|
پارامتر rawJson از نوع رشته ای و شامل جیسون نمایش دهنده یک نقطه بر روی نقشه است.
این جیسون خود 2 پارامتر دارد:
قالب جیسون ContactMessage:
{ "rawJson": "{\"data\": {\"contact\": {\"emails\": [\"test@test.com\"], \"name\": \"test contact\", \"phones\": [\"09123456789\"]}}, \"dataType\": \"contact\"}", "$type": "Json" }
تلگرام:
برای ارسال یک مخاطب از طریق sendContact پارامتر های زیر باید ارسال شود.
Description | Type | Field |
Integer or String |
chat_id
|
|
Contact's phone numbe | String |
phone_number
|
Contact's first name | String |
first_name
|
پارامتر chat_id در درخواست ارسال مخاطب میتواند از نوع رشته باشد که در این صورت باید نام کاربری کانال مورد نظر باشد.همچنین میتواند از نوع عدد باشد که در این صورت شناسه مکالمه یا شناسه مخاطب مورد خواهد بود.
همچنین پارامتر های اختیاری دیگری را نیز میتوان ارسال کرد که در زیر به توضیح مختصری درباره این پارامتر ها میپردازیم.
نوع خاص و بسیار جذابی از پیام که طرفدار های زیادی هم در بین توسعه دهندگان بات دارد پیام حاوی دکمه می باشدء نام این نوع پیام در بله template message گذاشته شده است و به شما این قابلیت را می دهد که پیام هایی از هر جنس که میخواهید (به جز پیام درخواست پول) را همراه چند دکمه در پایین آن که به دلخواه خودتان مشخص میشود ارسال کنید .
پارامتر های سازنده برای ساخت TemplateMessage :
پارامتر های سازنده برای ساختن TemplateMessageButton :
general_message = TextMessage('*temp message*')
btn_list = [TemplateMessageButton(text="yes", value="yes", action=0),
TemplateMessageButton(text="no", value="no", action=0)]
template_message = TemplateMessage(general_message=general_message, btn_list=btn_list)
نوع خاص و بسیار جذابی از پیام که طرفدار های زیادی هم در بین توسعه دهندگان بازو دارد پیام حاوی دکمه می باشدء نام این نوع پیام در بله template message گذاشته شده است و به شما این قابلیت را می دهد که پیام هایی از هر جنس که میخواهید (به جز پیام درخواست پول) را همراه چند دکمه در پایین آن که به دلخواه خودتان مشخص میشود ارسال کنید .
بله:
برای ارسال این نوع پیام در بله باید پارامتر های زیر در قالب جیسون در یک درخواست ارسال پیام در ارتباط وب سوکت برای سرور بله ارسال شود.
Description | Type | Field |
value is "TemplateMessage" | String |
$type
|
sequence number to help sequence process | Integer |
templateMessageId
|
any message that you want add button to it | Message |
generalMessage
|
a list of Button | ButtonList |
btnList
|
specify the type of response that bot developer expected like(text,date,password ....) | String |
responseType
|
ساختار یک دکمه:
Description | Type | Field |
text which show in button | String |
text
|
a value that send to server when the button clicked | String |
value
|
specify the action of button | Integer |
action
|
قالب جیسون TemplateMessage:
{ "templateMessageId": "0", "generalMessage": { "text": "*temp message*", "$type": "Text" }, "btnList": [ { "text": "yes", "action": 0, "value": "yes" }, { "text": "no", "action": 0, "value": "no" } ], "$type": "TemplateMessage" }
تلگرام:
در تلگرام به طور خاص این نوع پیام وجود ندارد.اما مشابه این نوع پیام در فیلد reply_markup نوع InlineKeyboardMarkup -است که در آن میتوان یک آرایه دو بعدی از دکمه ها را تعریف کرد و همراه هر پیام یک مجموعه دکمه نیز فرستاده شود.
پیام حاوی استیکر یکی از پیام های جذاب است.در صورت تمایل برای ارسال یک پیام حاوی استیکر ابتدا نیاز است تا اطلاعات استیکر مورد نظر را به دست آورید،سپس یک پیام حاوی استیکر ایجاد کنید.
بله:
برای ارسال استیکر در بله باید پارامتر های زیر در قالب جیسون در یک درخواست ارسال پیام در ارتباط وب سوکت برای سرور بله ارسال شود.
Description | Type | Field |
value is "Sticker" | String |
$type
|
sticker id | Integer |
stickerId
|
id of sticker collection | Integer |
stickerCollectionId
|
access hash of sticker collection | String |
stickerCollectionAccessHash
|
image location for size 256 (width, (height,file size, file location | object |
image256
|
image location for size 512(width, height,file size, file location) | object |
image512
|
set null | Byte Array |
fastPreview
|
قالب جیسون پیام حاوی استیکر:
{ "fastPreview": null, "image256": { "width": 256, "fileLocation": { "fileId": "-2709843113063612158", "fileStorageVersion": 1, "accessHash": "549755813890" }, "fileSize": 6618, "height": 256 }, "$type": "Sticker", "stickerId": "367893924", "image512": { "width": 512, "fileLocation": { "fileId": "-2709843113063612158", "fileStorageVersion": 1, "accessHash": "549755813890" }, "fileSize": 12480, "height": 512 }, "stickerCollectionId": "239060415", "stickerCollectionAccessHash": "-5500663794674697720" }
تلگرام:
برای ارسال یک استیکر از طریق sendSticker پارامتر های زیر باید ارسال شود.
Description | Type | Field |
Integer or String |
chat_id
|
|
String or InputFile |
sticker
|
پارامتر chat_id در درخواست ارسال پیام صوتی میتواند از نوع رشته باشد که در این صورت باید نام کاربری کانال مورد نظر باشد.همچنین میتواند از نوع عدد باشد که در این صورت شناسه مکالمه یا شناسه مخاطب مورد خواهد بود.
پارامتر sticker در درخواست ارسال استیکر میتواند از نوع رشته باشد که در این صورت باید شناسه استیکری که قبلا در یکی از سرورهای تلگرام آپلود شده است و یا آدرس http یک استیکر موجود در اینترنت باشد تا سرورهای تلگرام از آن استفاده کنند. همچنین میتواند خود استیکر باشد که در این صورت استیکر مورد نظر در قالب multipart/form-data آپلود خواهد شد.
همچنین پارامتر های اختیاری دیگری را نیز میتوان ارسال کرد که در زیر به توضیح مختصری درباره این پارامتر ها میپردازیم.
بله:
برای مشخص کردن اطلاعات thumb برای عکس یا ویدیو به عنوان یکی از پارامتر های این نوع پیام ها استفاده می شود.
Description | Type | Field |
height of image | Ineger |
height
|
width of image | Ineger |
width
|
base64-encoded string of the preview image | String |
thumb
|
قالب جیسون Thump:
{ "height": 80, "thumb": "None", "width": 80 }
بله:
Photo Extra:
برای مشخص کردن اطلاعات اضافی نوع ، طول و عرض عکس به عنوان یکی از پارامتر های پیام تصویری استفاده می شود.
Description | Type | Field |
value is "Photo" | String |
$type
|
height of image | Integer |
height
|
width of image | Integer |
width
|
قالب جیسون Photo Extra:
{ "$type": "Photo", "height": 80, "width": 80 }
Video Extra:
برای مشخص کردن اطلاعات اضافی نوع، طول و عرض ،مدت زمان ویدیو به عنوان یکی از پارامتر های پیام ویدیویی استفاده می شود.
Description | Type | Field |
value is "Video" | String |
$type
|
height of video | Integer |
height
|
width of video | Integer |
width
|
time duration of video | Integer |
duration
|
قالب جیسون Video Extra:
{ "width": 80, "$type": "Video", "duration": 9, "height": 80 }
Voice Extra:
برای مشخص کردن اطلاعات اضافی نوع و مدت زمان صوتبه عنوان یکی از پارامتر های پیام صوتی استفاده می شود.
Description | Type | Field |
value is "Voice" | String |
$type
|
duration in milisecond | Integer |
duration
|
قالب جیسونVoice Extra:
{ "$type": "Voice", "duration": 9 }
بله:
برای آپلود فایل ابتدا باید از سرور آدرسی برای آپلود کردن فایل مورد نظر درخواست کنید.
Description | Type | Field |
value is "files" | String |
service |
value is "Request" | String |
$type
|
body of request | Object |
body
|
unique id of request | String |
id
|
پارامتر های ارسالی در قالب بالا عبارت اند از:
Description | Type | Field |
calculated crc of file | String |
crc
|
size of file in bytes | Integer |
size
|
value is "GetFileUploadUrl " | String |
$type
|
value is "false" | Object |
isServer
|
value is "file","photo" | String |
fileType
|
نمونه جیسون ارسالی بازو برای درخواست آدرس آپلود :
{"service": "files", "$type": "Request", "body": { "crc": "3408719808", "size": 5869, "$type": "GetFileUploadUrl", "isServer": false, "fileType": "file" }, "id": "0" }
در پاسخ به این درخواست سرور جیسون زیر را برای بازو ارسال می کند:
{ "$type": "Response", "id": "0", "body": { "fileId": "8763054896817308674", "url": "https://fileserver-004-c002.bale.ai/259204777/8763054896817308674", "dup": false, "userId": 259204777 } }
در پاسخ بالا
سپس در یک درخواست put فایل مورد نظر را به آدرس دریافتی از سرور ارسال می شود.
نمونه کد ارسال درخواست put:
async def upload_data():
async with aiohttp.ClientSession() as session:
async with session.put(url, data=data, headers=headers) as upload_response:
status = upload_response.status
if status == 200:
future.set_user_data(file_id=file_id, user_id=user_id, url=url, dup=dup)
future.resolve(response=None)
else:
future.reject(response=None)
بله:
ارسال انواع درخواست از جمله ارسال پیام دربله تحت پروتکل websocket با ارسال و دریافت پیام ها در قالب جیسون انجام می شود.
<wss://api.bale.ai/v1/bots/<token
برای برقراری ارتباط وب سوکت ابتدا لازم است تا از bot father بله توکن دریافت کنید و در ادرس بالا در محل مناسب قرار دهید.
برای ارسال یک پیام، ابتدا یکی از انواع پیام ها را ایجاد و سپس در قالب جیسون زیر به عنوان پارامتر message به سرور ارسال شود.
پیام مورد نظر(در اینجا یک پیام متنی ساده) مانند زیر به سرور ارسال می شود:
{ "$type": "Request", "body": { "$type": "SendMessage", "randomId": "138551629284203874", "peer": { "$type": "User", "accessHash": "0011833586646883380", "id": "0008576569" }, "message": { "$type": "Text", "text": "*Hello*" }, "quotedMessage": null }, "service": "messaging", "id": "0" }
پارامتر های ارسالی در قالب بالا عبارت اند از:
تلگرام
ارسال انواع درخواست از جمله ارسال پیام در تلگرام تحت پروتکل https و به شکل زیر انجام میشود.
https://api.telegram.org/bot<token>/METHOD_NAME
بعد از دریافت توکن از bot fatherتلگرام برای ارسال هر درخواست لازم است تا جیسون یا فرم متناسب با آن درخواست به آدرسی در فرمت بالا ارسال شود.
به عنوان مثال گرفتن اطلاعات مربوط به بات این عمل به شکل زیر انجام میشود.
https://api.telegram.org/bot123456:ABC-DEF1234ghIklzyx57W2v1u123ew11/getMe
تلگرام از متد های post و get برای ارسال درخواست ها و همچنین چهار نوع مختلف ارسال پارامترهای مورد نیازاین درخواست ها پشتیبانی میکند.این چهار نوع عبارتاند از:
در صورت موفتیت آمیز بودن هر درخواست ارسال پیام، پیام ارسال شده، به عنوان پاسخ از سمت سرور دریافت میشود.
بله:
در بله هر پیام به یک peer ارسال می شود.user و group، هر کدام یک نوع Peerو نمایش دهنده یک کاربر یا گروه هستند.
User:
Description | Type | Field |
value is "User" | String |
$type
|
user id | Integer |
id
|
user access hash | String |
accessHash
|
Group:
Description | Type | Field |
value is "Group" | String |
$type
|
groupid | Integer |
id
|
group access hash | String |
accessHash
|
قالب جیسون User:
{ "$type": "User", "id": 12323, "accessHash": "321132" }
قالب جیسون Group:
{ "$type": "Group", "id": 12323, "accessHash": "321132" }
تلگرام:
User:
در تلگرام یک کاربر با یک جیسون با فیلد های زیر نمایش داده میشود.
Description | Type | Field |
Unique identifier for this user or bot | Integer |
id
|
True, if this user is a bot | Bolean |
is_bot
|
User‘s or bot’s first name | String | first_name |
همچنین پارامتر های اختیاری دیگری برای اطلاعات بیشتر می تواند داشته باشد.
Group:
در تلگرام مفهومی برای Group همانند آنچه که در بله داریم وجود ندارد.برای مشخص کردن یک گروه یا کانال و... از مفهوم Chat استفاده شده است.
Chat:
در تلگرام هر چت میتواند یک گروه،سوپرگروه،کانال و یا مکالمه شخصی باشد.همه انواع این چت ها در قالب یک جیسون با فیلدهای زیر نمایش داده میشوند.
Description | Type | Field |
Integer |
id
|
|
String |
type
|
همچنین پارامتر های اختیاری دیگری برای اطلاعات بیشتر می تواند داشته باشد.
بله:
این شئ نمایش دهنده محل ذخیره شدن یک فایل بر بروی سرورهای بله است.
Description | Type | Field |
file id | String |
fileId
|
file access hash | String |
accessHash
|
sould be 1 | Integer |
fileStorageVersion
|
قالب جیسون FileLocation:
{ "fileId": "234234", "accessHash": "423234", "fileStorageVersion": 1 }
اگر مایل به ارسال پیامی هستید که شامل فایل میباشد باید از این نوع پیام استفاده کنید . پارامترهای ساخت پیام فایل :
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)
سادهترین نوع پیام ء پیام متنی است . پارامترهای ساخت پیام متنی :
همانطور که ملاحظه میکنید برای ساخت پیام متنی صرفا کافیست که رشته ای از کاراکترها را به سازنده کلاس بدهیم و یک شی از آن را بسازیم. میتوانید در زیر مثالی از ساخت پیام متنی را مشاهده نمایید.
const SDK = require("balebot");
const BaleBot = SDK.BaleBot;
const TextMessage = SDK.TextMessage;
var text = new TextMessage(String you want to send);
همانطور که مشاهده کردید کار بسیار راحتیست ...
حال شاید این سوال برای شما پیش بیاید در صورتی که کاربر به بات پیامی دهد که شامل یک عبارت باشد و آن عبارت نه شروع کننده یک مکالمه باشد و نه متد 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!
});
بله:
*توجه: این سرویس در حال حاضر یک سرویس آزمایشی می باشد.
ارسال انواع درخواست از جمله ارسال پیام دربله تحت پروتکلHttp نیز با ارسال و دریافت پیام ها در قالب جیسون انجام می شود.
<https://apitest.bale.ai/v1/bots/http/<token
برای ارسال درخواست ها از طریق ارتباط Http ابتدا لازم است تا از bot father بله توکن دریافت کنیدو در ادرس بالا در محل مناسب قرار دهید. و درخواست های خود را به این آدرس از طریق درخواست Post ارسال کنید.
برای دریافت آپدیت ها توسط بازو نیز باید ابتدا یک webhookبرای بازو در سرور بله مشخص شود. و سرور تمامی updateهارا برای بازو به آن آدرس ارسال خواهد کرد.
ضمنا برای مشخص کردن و یا حذف یک آدرس webhook برای بازو نیز می تواند از توابع موجود در کتابخانه پایتون (Http) استفاده کرد.همچنین API این دو نوع درخواست نیز در همین بخش قابل دسترسی است.
برای ارسال یک پیام، ابتدا یکی از انواع پیام ها را ایجاد و سپس در قالب جیسون زیر به عنوان پارامتر message به سرور ارسال شود.
پیام مورد نظر(در اینجا یک پیام متنی ساده) مانند زیر به سرور ارسال می شود:
{ "$type": "Request", "body": { "$type": "SendMessage", "randomId": "138551629284203874", "peer": { "$type": "User", "accessHash": "0011833586646883380", "id": "0008576569" }, "message": { "$type": "Text", "text": "*Hello*" }, "quotedMessage": null }, "service": "messaging", "id": "0" }
پارامتر های ارسالی در قالب بالا عبارت اند از:
تلگرام
ارسال انواع درخواست از جمله ارسال پیام در تلگرام تحت پروتکل https و به شکل زیر انجام میشود.
https://api.telegram.org/bot<token>/METHOD_NAME
بعد از دریافت توکن از bot fatherتلگرام برای ارسال هر درخواست لازم است تا جیسون یا فرم متناسب با آن درخواست به آدرسی در فرمت بالا ارسال شود.
به عنوان مثال گرفتن اطلاعات مربوط به بازو این عمل به شکل زیر انجام میشود.
https://api.telegram.org/bot123456:ABC-DEF1234ghIklzyx57W2v1u123ew11/getMe
تلگرام از متد های post و get برای ارسال درخواست ها و همچنین چهار نوع مختلف ارسال پارامترهای مورد نیازاین درخواست ها پشتیبانی میکند.این چهار نوع عبارتاند از:
در صورت موفتیت آمیز بودن هر درخواست ارسال پیام، پیام ارسال شده، به عنوان پاسخ از سمت سرور دریافت میشود.
بله:
ثبت کردن webhook برای بازو:
برای ثبت کردن یک webhook برای یک بازو لازم است پارامتر های زیر در قالب یک درخواست مانند نمونه برای سرور ارسال شوند.
Description | Type |
Field
|
Id of bot | Integer |
userId
|
Url of webhook server | String |
endpoint
|
{ "$type": "Request", "id": "9", "service": "webhooks", "body": { "$type": "RegisterHook", "userId": 123456, "endpoint": "http://0.0.0.0:1234/v1/bots" } }
در درخواست بالا سرویس باید مقدار ثابت webhooks و پارمتر type در قسمت bodyباید مقدار ثابت RegisterHook را داشته باشد.
حذف کردن webhook برای یک بازو:
برای حذف کردن یک webhook برای یک بازو لازم است پارامتر های زیر در قالب یک درخواست مانند نمونه برای سرور ارسال شوند.
Description | Type |
Field
|
Id of bot | Integer |
userId
|
{ "$type": "Request", "id": "9", "service": "webhooks", "body": { "$type": "UnRegisterHook", "userId": 123456 } }
در درخواست بالا سرویس باید مقدار ثابت webhooks و پارمتر type در قسمت bodyباید مقدار ثابت UnRegisterHook را داشته باشد.
*توجه این نسخه از کتابخانه آزمایشی بوده و به زودی نسخه اصلی در دسترس عموم قرار می گیرد.
این کتابخانه با الهام از کتابخانه python-telegram-bot با زبان پایتون نسخه +3.5 توسعه داده شده است و به شما کمک میکند که بازو خود را در بله راه اندازی کنید و به راحتی از Api های بله که در اختیار شما قرار میگیرد استفاده کنید.
تفاوت این کتابخانه با کتابخانه balebot در نحوه برقراری ارتباط ارسال و دریافت درخواست ها و پاسخ ها و دریافت آپدیت ها از سمت سرور است که تحت پروتکل - http - انجام میشود.
نیازمندی های این کتابخانه :
certifi==2018.4.16
chardet==3.0.4
future==0.16.0
graypy==0.2.14
idna==2.7
requests==2.19.1
ujson==1.35
urllib3==1.2
برای نصب این کتابخانه ابتدا لازم است که نسخه پایتون +3.5 بر بروی سیستم عامل شما نصب باشد.سپس به کمک دستور زیر می توانید کتابخانه را نصب کنید.
pip install --extra-index-url https://test.pypi.org/simple/ python_bale_bot
برای استفاده از نسخه آزمایشی این کتابخانه در اولین قدم لازم است که شما با بازو bot_father_testi@ شروع به صحبت کنید و از بازو پدر بخواهید که یک بازو با نام و نام کاربری دلخواهتان بسازد. بعد از انجام این فرآیند یک token در اختیار شما گذاشته می شود که با استفاده از این token میتوانید با سرور بله ارتباط برقرار کنید. سپس پروژهی خود را ایجاد کرده و کتابخانه بازو بله را به آن اضافه کنید، در این مرحله شما میتوانید از توابع و کلاس های این کتابخانه به راحتی استفاده نمایید. این کتابخانه با قواعد شیگرایی سازگاری داشته و شما میتوانید به راحتی از هر قسمت کد که لازم بود آزادانه استفاده کنید همچنین میتوانید داکیومنت API بازو بله را نیز برای درک بیشتر مطالعه کنید.
همانطور که گفته شد در ابتدا لازم است که شما کتابخانه بازو بله که قبلا نصب کرده بودید را فراخوانی کنید سپس کلاسهای مورد نیاز خود را فراخوانی کرده و از آنها استفاده کنید. برای مثال برای ساخت کلاس اولیه بازو نیاز است که شما از کدی مانند کد زیر استفاده کنید:
from balebot.updater import Updater
# Bale Bot Authorization Token and ID
updater = Updater(token="<BOT TOKEN>", user_id="<BOT USER ID>")
# Define dispatcher
dispatcher = updater.dispatcher
#Get bot
bot = updater.dispatcher.bo
همان طور که مشاهده میکنید در ابتدا با استفاده از توکن بازو یک شی از کلاس Updater ساخته میشود. Updater کلاس اصلی کتابخانه میباشد که بخشهای مختلف آن را به هم وصل میکند، این کلاس پس از ساخته شدن از کلاسهایBot و Dispatcher در خود یک شئ میسازد.
کلاس Updater پیوسته update هارا از سرور دریافت میکند و آن ها را به کمک صف بهDispatcher میفرستد تا بررسی شوند، در ادامه شما میتوانیدHandler هایی را در Dispatcher ایجاد کنید تا آپدیت های دریافت شده با توجه به این Handler ها سرویسدهی شوند، در ادامه بیشتر با Handler ها و updater و dispatcher و نخوه استفاده از آن ها بیشتر آشنا خواهید شد . علاوه بر این قبل از آن که از کلاس Updater شئ بسازید میتوانید کانفیگ پیشفرض کتابخانه بازو را هم به صورت اختیاری تغییر دهید.مثال ساده :
from balebot.config import Config
Config.base_url = "YOUR CUSTOM URL"
برای دریافت update ها در کلاس dispatcher لازم است تا ابتدا آدرس ip ماشینی که بازو بر روی آن در حال اجرا است را به عنوان webhook برای این بازو اضافه کرد. برای این کار می توانید از متد set_webhook در کلاس بات استفاده کنید.در ادامه با این متد بیشتر آشنا خواهید شد
*با توجه به آزمایشی بودن نسخه این کتابخانه پروتکل پشتیبانی شده برای webhook ، http بوده اما در آینده پشتیبانی از پروتکل امن https نیز اضافه خواهد شد.
با استفاده از از کلاسهای 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(response, user_data): print("success : ", response) print(user_data)
def failure(response, user_data): print("failure : ", response) print(user_data)
@dispatcher.message_handler(filters=DefaultFilter()) def echo(bot, update): message = TextMessage("Hello World") user_peer = update.get_effective_user() bot.send_message(message, user_peer, success_callback=success, failure_callback=failure) updater.start_webhook(url_path='/v1/bots'
علاوه بر این میتوان از یک 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)
کلاس dispatcher کلاسی است که آپدیت های دریافت شده توسط شئ updater را از صف ورودی برداشته، handler مربوط به آن را پیدا کرده و آن را پردازش می کند.این پردازش می تواند در همان thread و یا در یک thread دیگر انجام شود. نحوه پردازش یک handler نیز توسط خود توسعه دهنده مشخص می شود.برای اطلاعات بیشتر بخش Concurrency مطالعه شود. پارامتر های سازنده این کلاس و شرح مختصری درباره هر پارامتر در زیر آمده است.
*pool_connections : تعداد connection pools که در کتابخانه urllib3 ساخته می شود.
*pool_maxsize :بیشترین تعداد ارتباطی که در هر pool ذخیره خواهد شد.
به صورت پیش فرض این مقدار pool_connections برابر 2 و مقدار pool_maxsize برابر 20 است. در صورت تمایل می توان به کمک فایل Config نیز این مقادیر را تغییر داد.
برای اطلاعات بیشتر می توانید از لینک زیر استفاده کنید.
http://docs.python-requests.org/en/master/api/#requests.adapters.HTTPAdapter
کلاس bot نمایان گر ی bot است. توسعه دهنده با ایجاد یک شئ از این کلاس و به کمک توابع پیاده سازی شده در این کلاس می تواند به سروردرخواست های مختلف ارسال پیام ،آپلود فایل و دانلود فایل را ارسال کند. پارامتر های سازنده این کلاس و شرح مختصری درباره هر پارامتر در زیر آمده است.
برای اطلاعات بیشتر می توانید از لینک زیر استفاده کنید.
http://docs.python-requests.org/en/master/api/#requests.adapters.HTTPAdapter
کلاس dispatcher کلاسی است که آپدیت های دریافت شده توسط شئ updater را از صف ورودی برداشته، handler مربوط به آن را پیدا کرده و آن را پردازش می کند.این پردازش می تواند در همان thread و یا در یک thread دیگر انجام شود. نحوه پردازش یک handler نیز توسط خود توسعه دهنده مشخص می شود.برای اطلاعات بیشتر بخش Concurrency مطالعه شود. . پارامتر های سازنده این کلاس و شرح مختصری درباره هر پارامتر در زیر آمده است.
این کتابخانه برای concurrency از threading پایتون استفاده می کند.همروندی در این کتابخانه در حقیقت باعث اجرای سریع تر کد نخواهد شد. مهم ترین نکته مثبت در همرندی در این کتابخانه اجرای عملیات i/o مانند ارتباطات شبکه و یا خواندن و نوشتن برروی دیسک سخت است که می تواند به صورت همروند انجام شوند.اجرای هم روند مانع از این می شود که یک فعالیت باعث مسدود شدن بقیه قعالیت ها بشود.این ارتباطات به خصوص ارتباطات تحت شبکه معمولا بخش زیادی از کار یک بازو خواهد بود.
به صورت پیش فرض همهhandler ها در thread ای که شئ dispatcher در آن در حال اجرا است،اجرا خواهند شد و اگر یک handler برای اجرا زمان زیادی نیاز داشته باشد و در صورت وجود درخواست دیگری بقیه درخواست ها منتظر اجرای کامل این درخواست خواهند شد.
برای حل این مشکل ها در کتابخانه decorator ای برای اجرای همروند توابع مختلف قرار داده شده است که به طور مشخص یک تابع را در یک thread جدا و همروند اجرا خواهد کرد.برای استفاده از این decorator مانند زیر عمل می شود:
#Import run_async:
from balebot.dispatcher import run_async
#Use it as a decorator for the echo function:
@dispatcher.message_handler(filters=TextFilter())
@run_async
def echo(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)
برای ایجاد یک مکالمه که بصورت مداوم بین کاربر و بازو ادامه دارد باید از 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(["/start"])
@run_async
def conversation_starter(bot, update):
message = TextMessage("*Hi , nice to meet you*\nplease tell me your name.")
# Get client user object by calling update's get_effective_user method
user_peer = update.get_effective_user()
# Set any user data in kwargs mode
kwargs = {"message": message, "user_peer": user_peer}
bot.send_message(message, user_peer, success_callback=success, failure_callback=failure, kwargs=kwargs)
# Set different handlers for different messages user can sent in this state and register next step handlers
dispatcher.register_conversation_next_step_handler(update, [MessageHandler(TextFilter(), ask_name),
MessageHandler(DefaultFilter(), skip_name)])
@run_async
def ask_name(bot, update):
message = TextMessage("*Thanks!*\n now please tell me your age")
user_peer = update.get_effective_user()
# Get client message object by a function called (get_effective_message)
user_message = update.get_effective_message()
# Get text form a message obj
user_message_text = user_message.text
# Set a conversation data in Memory (Not durable)
dispatcher.set_conversation_data(update=update, key="name", value=user_message_text)
kwargs = {"message": message, "user_peer": user_peer}
bot.send_message(message, user_peer, success_callback=success, failure_callback=failure, kwargs=kwargs)
# Set Regex pattern for TextFilter to accept only numbers
dispatcher.register_conversation_next_step_handler(update, MessageHandler(TextFilter(pattern="^[0-9]+$"),
finish_conversion))
@run_async
def skip_name(bot, update):
message = TextMessage("*So, you don't want to tell your name!*\nplease just tell me your age")
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="name", value="no name")
dispatcher.register_conversation_next_step_handler(update, MessageHandler(TextFilter(), finish_conversion))
@run_async
def finish_conversion(bot, update):
user_peer = update.get_effective_user()
user_name = dispatcher.get_conversation_data(update, key="name")
user_age = update.get_effective_message().text
user_info_message = TextMessage("*Name:* " + user_name + "\n" + "*Age:* " + user_age)
bot.send_message(user_info_message, user_peer, success_callback=success, failure_callback=failure)
message = TextMessage("*Thanks!*\ngoodbye ;)")
bot.send_message(message, user_peer, success_callback=success, failure_callback=failure)
# Finish conversation
dispatcher.finish_conversation(update)
# Run the bot! url_path is the path for webhook which listen on it
updater.start_webhook(url_path='/v1/bots')
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")
ساده ترین نوع پیام, پیام متنی است . پارامترهای ساخت پیام متنی :
همانطور که ملاحظه میکنید برای ساخت پیام متنی صرفا کافیست که رشتهای از کاراکترها را به سازنده کلاس بدهیم و یک شی از آن را بسازیم. میتوانید در زیر مثالی از ساخت پیام متنی را مشاهده نمایید.
from bale.models.messages import TextMessage
dispatcher = updater.dispatcher
text_message = TextMessage(text="it is a text")
اگر مایل به ارسال پیامی هستید که شامل فایل میباشد باید از این نوع پیام استفاده کنید . پارامترهای ساخت پیام فایل :
from bale.models.messages import DocumentMessage
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)
پیام تصویری یکی از زیر مجموعهها یا فرزندان پیام فایلی میباشد. به عبارت دیگر از 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)
پیام ویدیویی یکی از زیر مجموعهها یا فرزندان پیام فایلی میباشد. به عبارت دیگر از 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)
پیام صوتی یکی از زیر مجموعهها یا فرزندان پیام فایلی میباشد. به عبارت دیگر از 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 :
پارامتر های سازنده برای ساختن TemplateMessageButton :
general_message = TextMessage('*temp message*')
btn_list = [TemplateMessageButton(text="yes", value="yes", action=0),
TemplateMessageButton(text="no", value="no", action=0)]
template_message = TemplateMessage(general_message=general_message, btn_list=btn_list)
یکی از انواع پیام ها است که برای ارسال یک محل بر روی نقشه از آن استفاده می شود.
مثال سادهای از ایجاد یک location message درزیر مشاهده میکنید.
from bale.updater import Updater
location_message = LocationMessage(longitude="51.41714821748457", latitude="35.73122955392002")
bot.send_message(location_message, user_peer, success_callback=success, failure_callback=failure)
ContactMessage یکی از نواع پیام ها برای ارسال اطلاعات تماس یک مخاطب به کاربر استو
در صورتی که مایل هستید یک مخاطب ارسال کنید میتوانید از این نوع پیام استفاده کنید.
مثال ساده ای از ساخت یک ContactMessage:
contact_message = ContactMessage(name="test contact", emails=["test@test.com"], phones=["09123456789"])
bot.send_message(contact_message, user_peer, success_callback=success, failure_callback=failure)
اگر مایلید که پیامی حاوی درخواست پول برای کاربر خود ارسال کنید میتوانید از این نوع پیام استفاده کنید. پارامترهای سازنده عبارتند از:
توضیحات | نوع | نام | شماره |
پیامی که میخواهید همراه درخواست پول فرستاده شود(این پیام حتما باید از نوع عکس باشد). | BaseMessage | msg | ۱ |
شماره کارت یا حساب که مایلید پول به آن واریز شود مثلا : "**** **** ۹۹۱۸ ۶۰۳۷" |
String | account_number | ۲ |
مقدار پولی که مایلید درخواست دهید. مثلا ۱۰۰۰ریال که معادل۱۰۰ تومن می باشد.(واحد ریال است) | String | amount | ۳ |
بسته به نوع پرداخت شما متفاوت است ولی معمولا از کلاس MoneyRequestType مقدار normal را انتخاب می کنند. | MoneyRequestType | money_request_type | ۴ |
مثال سادهای از نحوه ساخت پیام درخواست پول را در زیر مشاهده میکنید:
purchase_message = PurchaseMessage(msg=text_message, account_number="6221061064199856", amount="111", money_request_type=MoneyRequestType.normal)
پیام حاوی استیکر یکی از پیام های جذاب است.در صورت تمایل برای ارسال یک پیام حاوی استیکر ابتدا نیاز است تا اطلاعات استیکر مورد نظر را به دست آورید،سپس یک پیام حاوی استیکر ایجاد کنید.
مثال سادهای از ایجاد یک پیام حاوی استیکر را میتوانید در زیر مشاهده کنید:
im_file_loc = FileLocation(file_id="-2709843113063612158", access_hash="549755813890")
im_512_loc = ImageLocation(width=512, height=512, file_size=12480, file_location=im_file_loc)
im_256_loc = ImageLocation(width=256, height=256, file_size=6618, file_location=im_file_loc)
sticker_message = StickerMessage(sticker_id=367893924, sticker_collection_id=239060415,sticker_collection_access_hash="-5500663794674697720",image512=im_512_loc,image256=im_256_loc)
bot.send_message(sticker_message, user_peer, success_callback=success, failure_callback=failure)
ما در اینجا به اختصار درباره چند متود توضیحاتی میدهیم، برای آشنایی بیشتر با متدهای دیگر میتوانید داکیومنت API بازو بله را نیز برای درک بیشتر مطالعه کنید:
send_message
این متد به شما کمک میکند که پیامتان را برای کاربرتان ارسال کنید. پارامترهای ورودی این متد عبارتند از:
یک مثال ساده از نحوه ارسال پیام را در زیر مشاهده میکنید:
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 کنید. پارامترهای ورودی این متد عبارتند از :
آپدیتی که از طرف کاربر به بازو می رسد. | FatSeqUpdate | update | 1 |
هر نوع پیامی که مایلید | BaseMessage | message | 2 |
یک مثال ساده از نحوه ارسال پیام را در زیر مشاهده میکنید :
@dispatcher.message_handler(PhotoFilter())
def some_file_received(bot, update):
bot.reply(update, message, success_callback=success, failure_callback=failure)
respond
این متد به شما کمک می کند که به راحتی در جواب پیامی که از کاربر دریافت میکنیم پیامی بفرستیم، در واقع تفاوتی که این متد با reply دارد این است که reply روی پیام دریافت شده پاسخ میفرستد ولی respond همانند send_message عمل میکند و فقط کار ارسال پاسخ را آسانتر می کند . پارامترهای ورودی این متد عبارتند از:
آپدیتی که از طرف کاربر به بازو می رسد. | FatSeqUpdate | update | 1 |
هر نوع پیامی که مایلید | BaseMessage | message | 2 |
یک مثال ساده از نحوه ارسال پیام را در زیر مشاهده میکنید :
@dispatcher.message_handler(PhotoFilter())
def some_file_received(bot, update):
bot.respond(update, message, success_callback=success, failure_callback=failure)
از این متد برای گرفتن فضا در سیستم مدیریت فایل بله و آپلود کردن فایل یا عکس مورد نظر در این فضا استفاده میشود. ورودی:
در صورت موفقیت آمیز بودن عملیات وارد متد مشخص شده برای success_callback میشویم و خروجی های زیر از طریق این متد قابل دسترس هستند.
توضیحات کامل تر در رابطه با آپلود فایل در قسمت API در دسترس قرار دارد.
از این متد برای دانلود فایلی که در سیستم مدیریت فایل بله وجود دارد استفاده میشود. ورودی:
در صورت موفقیت آمیز بودن عملیات وارد متد مشخص شده برای 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)
set_webhook
این متد برای ثبت کردن یک webhook برای یک بازو استفاده می شود.به عنوان پارامتر آدرس webhook را گرقته و درخواست ثبت webhook را برای سرور ارسال می کند.
یک مثال ساده از نحوه ثبت webhookتوسط متد های بات را در زیر مشاهده میکنید :
def success(result): print("success : ", result) def failure(result): print("failure : ", result)
bot.set_webhook(endpoint="http://0.0.0.0:1234/v1/bots",success_callback=
success,
failure
_callback
=
failure
)
delete_webhook
این متد برای حذف کردن یک webhook برای یک بازو استفاده می شود و درخواست حذف webhook را برای سرور ارسال می کند.
یک مثال ساده از نحوه حذف webhook توسط متد های بات را در زیر مشاهده میکنید :
def success(result): print("success : ", result) def failure(result): print("failure : ", result)
bot.delete_webhook(success_callback=
success,
failure
_callback
=
failure)
بله:
ارسال انواع درخواست از جمله ويرايشپيام دربله تحت پروتکل websocket با ارسال و دريافت درخواست در قالب جيسون انجام مي شود.
<wss://api.bale.ai/v1/bots/<token
براي برقراري ارتباط وب سوکت ابتدا لازم است تا از bot father بله توکن دريافت کنيد و در ادرس بالا در محل مناسب قرار دهيد.
براي ويرايش يک پيام ابتدا لازم است يکي از انواع پيام هاي متني، پيام حاوي فايل و يا template message ايجاد شود و سپس در قالب جيسون زير به عنوان پارامتر message به سرور ارسال شود.
پيام مورد نظر(در اينجا يک پيام متني ساده) مانند زير به سرور ارسال مي شود:
{ "service": "messaging", "body": { "peer": { "accessHash": "1123456789123456789", "id": "931234567", "$type": "User" }, "randomId": "1589961363976789543", "message": { "text": "*message edited*", "$type": "Text" }, "$type": "EditMessage" }, "id": "1", "$type": "Request" }
پارامتر هاي ارسالي در قالب بالا عبارت اند از:
تلگرام:
ارسال انواع درخواست از جمله ویرایش پیام در تلگرام تحت پروتکل https و به شکل زیر انجام میشود.
https://api.telegram.org/bot<token>/METHOD_NAME
برای ویرایش پیام متنی باید پارامتر های زیر به سمت سرور ارسال شود.
بله:
*توجه: این سرویس در حال حاضر یک سرویس آزمایشی می باشد.
رسال انواع درخواست از جمله ویرایش پیام دربله تحت پروتکلHttp نیز با ارسال و دریافت پیام ها در قالب جیسون انجام می شود.
{ "service": "messaging", "body": { "peer": { "accessHash": "1123456789123456789", "id": "931234567", "$type": "User" }, "randomId": "1589961363976789543", "message": { "text": "*message edited*", "$type": "Text" }, "$type": "EditMessage" }, "id": "1", "$type": "Request" }
پارامتر هاي ارسالي در قالب بالا عبارت اند از:
تلگرام:
ارسال انواع درخواست از جمله ویرایش پیام در تلگرام تحت پروتکل https و به شکل زیر انجام میشود.
https://api.telegram.org/bot<token>/METHOD_NAME
برای ویرایش پیام متنی باید پارامتر های زیر به سمت سرور ارسال شود.