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

برنامه‌نویسان در بله می‌توانند «بازو»های کاربردی را برای کاربرانشان توسعه دهند. «بازو» راهکاری جذاب برای ارائه خدمات یا ایجاد کسب و کار در بله است.

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

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

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

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

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

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

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

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

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

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

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

NPM: https://nodejs.org/en

در ابتدا لازم است که شما با بازوی 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 Button(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 های بله که در اختیار شما قرار می‌گیرد، استفاده نمایید. این کتابخانه با زبان پایتون توسعه داده شده است و نسخه ۳.۵+ این زبان را پشتیبانی می‌کند. نیازمندی‌ها :

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

Python 3.5

Asyncio

Aiohttp

Graypy

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

pip3 install balebot

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

کتابخانه بازوی بله در گیت هاب

و همچنین مثال های کاربردی بازو را میتوانید در لینک زیر مشاهده کنید.
مثال های کاربردی بازوی بله

در اولین قدم لازم است که شما با بازو 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

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

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

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 کنید. پارامتر‌های ورودی این متد عبارتند از :

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

@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 عمل می‌کند و فقط کار ارسال پاسخ را آسان‌تر می کند . پارامتر‌های ورودی این متد عبارتند از:

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

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

edit message

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

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

@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)

upload_file :

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

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

download_file:

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

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

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

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

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

ابتدا لازم است شما با آیدی botfather@ که مسئول مدیریت بازوها است، صحبت کنید.

برای شروع دستور start/ را همانند زیر وارد کنید:

دکمه help را بفشارید :

به قسمت ساخت بازوی جدید بروید:

نام یا عنوان بازوی خود را به دلخواه انتخاب کنید :

آیدی ای که قرار است با آن بازوی خود را صدا بزنید وارد کنید‌ :

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

در این پیغام شما یک توکن (token) و یک user id دریافت می‌کنید که برای راه‌اندازی بازو به آن احتیاج دارید.

نکته : در حفظ و نگهداری توکن خود کوشا باشید چون تنها راه کنترل بازوی شماست. اگر فردی توکن بازوی شما را داشته باشد به‌راحتی می‌تواند بازوی شما را تغییر داده و امنیت آن را تهدید کند.

حال که توکن بازو را در اختیار دارید می‌توانید به‌راحتی و فقط با اجرای چند خط کد بازو را run نمایید.

در ابتدا شما نیاز به یک ارتباط با سرور از نوع 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:

یکی از انواع پیام ها است که برای ارسال یک محل بر روی نقشه از آن استفاده می شود.
مثال ساده‌ای از ایجاد یک locati‌on 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)

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

بله: 

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

$type

text

• پارامتر $type از نوع رشته ای و مشخص کننده نوع پیام است.برای پیام متنی این پارامتر باید برابر  Text باشد.
• پارامتر text از نوع رشته ای و مشخص کننده متن پیام ارسالی است.

قالب جیسون پیام متنی:

{
 "$type": "Text",
 "text": "*Hello*"
} 

تلگرام

برای ارسال یک پیام متنی از طریق sendMessage پارامتر­های زیر باید ارسال شود.

chat_id

text

پارامتر chat_id ­در درخواست ارسال پیام متنی می­تواند از نوع رشته باشد که در این صورت باید نام کاربری کانال مورد نظر باشد.هم­چنین می­تواند از نوع عدد باشد که در این صورت شناسه مکالمه یا شناسه مخاطب مورد خواهد بود.

همچنین پارامتر های اختیاری دیگری را نیز می­توان ارسال کرد که در زیر به توضیح مختصری درباره این پارامتر ها میپردازیم.

• parse_mode: نحوه نمایش متن به شکل  bold, italic, fixed-width text or inline URLs را مشخص می­کند.
• disable_web_page_preview: این پارامتر از نوع بولی است ومشخص کننده پیش نمایش لینک هاست.
• disable_notification: این پارامتر از نوع بولی است و مشخص کننده این است که کاربر پیام را با صدا یا بدون صدا دریافت کند.
• reply_to_message_id: این پارامتر از نوع عدد است.اگر پیام ارسالی یک reply  به پیام دیگری باشد این پارامتر حاوی شناسه پیام اصلی است.
• reply_markup:این پارامتر مشخص کننده انوع کیبورد است که می­توان همراه یک پیام به کاربر ارسال کرد تا کاربر به انتخاب از بین گزینه های موجود در کیبورد مجبور شود.

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

بله:

قبل از ارسال پیام حاوی فایل ابتدا باید فایل مورد نظر آپلود شود و fileId و accessHash آن بدست آید.

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

ارسال این نوع پیام دارای محدودیت حجم ارسال 50 مگا بایتی می باشد.

$type

fileId 

accessHash 

fileStorageVersion 

fileSize 

name 

mimeType 

checkSum 

algorithm

thumb 

ext 

caption 

• پارامتر $type از نوع رشته ای و مشخص کننده نوع پیام است.برای پیام حاوی فایل این پارامتر باید برابر  Document باشد.
• پارامتر fileId از نوع عددی است و مشخص کننده شناسه فایل آپلود شد بر روی سرور های بله است.
• پارامتر accessHash از نوع رشته ای و در حقیقت یک کلید یکتا برای بازو به منظور دسترسی به فایل مورد نظر است.
• پارامتر fileStorageVersion از نوع عددی و مشخص کننده محل ذخیره فایل مورد نظر است.مقدار این پارامتر باید برابر 1 باشد.
• پارامتر  fileSize  از نوع عددی و مشخص کننده اندازه فایل مورد نظر در واحد بایت است.
• پارامتر name از نوع رشته ای و مشخص کننده نام فایل مورد نظر است.
• پارامتر mimeType  از نوع رشته ای و مشخص کننده نوع فایل مورد نظر است.
• پارامتر checkSum  از نوع رشته ای و مشخص کننده این است که آیا بررسی checkSum  انجام بشود یا خیر.مقدار این پارامتر باید برابر checkSum  باشد.
• پارامتر algorithm از نوع رشته ای است و مقدار این پارامتر باید برابر algorithm باشد.
• پارامتر thumb یک جیسون از نوع Thumbو نمایانگر یک thumbnail برای بعضی از انواع پیام ها است.
• پارامتر ext یک جیسون از نوع Extra  و حاوی اطلاعاتی مانند طول و عرض برای بعضی از انواع پیام ها است.
•  پارامتر 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 پارامتر­های زیر باید ارسال شود.

chat_id

document

پارامتر chat_id ­در درخواست ارسال سند می­تواند از نوع رشته باشد که در این صورت باید نام کاربری کانال مورد نظر باشد.هم­چنین می­تواند از نوع عدد باشد که در این صورت شناسه مکالمه یا شناسه مخاطب مورد خواهد بود

پارامتر document در درخواست ارسال سند می­تواند از نوع رشته باشد که در این صورت باید شناسه سندی که قبلا در یکی از سرورهای تلگرام آپلود شده است و یا آدرس http یک سند موجود در اینترنت باشد تا سرورهای تلگرام از آن استفاده کنند. هم­چنین می­تواند خود سند باشد که در این صورت سند مورد نظر در قالب multipart/form-data آپلود خواهد شد.بات های تلگرام در حال حاضر برای ارسال سند محدودیت حجم 50 مگا­بایتی دارند.

همچنین پارامتر های اختیاری دیگری را نیز می­توان ارسال کرد که در زیر به توضیح مختصری درباره این پارامتر ها میپردازیم.

• thumb: این پارامتر فقط زمانی که درخواست در قالب multipart/form-data باشد، ارسال می­شود.اندازه این پارامتر باید کمتر از 200 کیلوبایت و ابعاد آن کمتر از 90 باشد.ارسال این پارامتر فقط یک بار انجام می­شود و این پارامتر برای استفاده دوباره نیست.
• caption: این پارامتر از نوع رشته است و متن دلخواهی ست که همراه با سندی در پیام ارسال می­شود.محدودیت 200 حرف در ارسال این پارامتر وجود دارد.
• parse_mode: نحوه نمایش متن به شکل  bold, italic, fixed-width text or inline URLs را مشخص می­کند.
• disable_notification: این پارامتر از نوع بولی است و مشخص کننده این است که کاربر پیام را با صدا یا بدون صدا دریافت کند.
• reply_to_message_id: این پارامتر از نوع عدد است.اگر پیام ارسالی یک reply  به پیام دیگری باشد این پارامتر حاوی شناسه پیام اصلی است.
• reply_markup:این پارامتر مشخص کننده انوع کیبورد است که می­توان همراه یک پیام به کاربر ارسال کرد تا کاربر به انتخاب از بین گزینه های موجود در کیبورد مجبور شود.

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

قبل از ارسال پیام ویدیویی مانند پیام حاوی فایل ابتدا باید فایل مورد نظر آپلود شود و fileId و accessHash آن بدست آید.

برای ارسال پیام ویدیویی باید thumb و ext نیز مشخص شوند و پارامتر های زیر در قالب جیسون در یک درخواست ارسال پیام در ارتباط وب سوکت برای سرور بله ارسال شود.

ارسال این نوع پیام دارای محدودیت حجم ارسال 50 مگا بایتی می باشد.

$type

fileId 

accessHash 

fileStorageVersion 

fileSize 

name 

mimeType 

checkSum 

algorithm

thumb 

ext 

caption

• پارامتر $type از نوع رشته ای و مشخص کننده نوع پیام است.برای پیام ویدیویی مقدار این پارامتر باید برابر  Document باشد.
• پارامتر fileId از نوع عددی است و مشخص کننده شناسه ویدیو آپلود شد بر روی سرور های بله است.
• پارامتر accessHash از نوع رشته ای و در حقیقت یک کلید یکتا برای بازو به منظور دسترسی به ویدیو مورد نظر است.
• پارامتر fileStorageVersion از نوع عددی و مشخص کننده محل ذخیره ویدیو مورد نظر است.مقدار این پارامتر در حال حاضر باید برابر 1 باشد.
• پارامتر  fileSize  از نوع عددی و مشخص کننده اندازه ویدیو مورد نظر در واحد بایت است.
• پارامتر name از نوع رشته ای و مشخص کننده نام ویدیو مورد نظر است.
• پارامتر mimeType  از نوع رشته ای و مشخص کننده نوع ویدیو مورد نظر است.
• پارامتر checkSum  از نوع رشته ای و مشخص کننده این است که آیا بررسی checkSum  انجام بشود یا خیر.مقدار این پارامتر باید برابر checkSum  باشد.
• پارامتر algorithm از نوع رشته ای است و مقدار این پارامتر باید برابر algorithm باشد.
• پارامتر thumb یک جیسون از نوع Thumbو نمایانگر یک thumbnail برای این پیام است.
• پارامتر ext یک جیسون از نوع Extraشامل پارامتر های طول ،عرض،مدت زمان و نوع پیام است.
•  پارامتر 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 پارامتر های زیر باید ارسال شود.

chat_id

video

در حال حاضر در تلگرام فقط فرمت ویدیویی mp4 به عنوان ویدیو پشتیبانی می­شود.و بقیه فرمت های ویدیویی در قالب سند ارسال می­شوند.

پارامتر chat_id ­در درخواست ارسال پیامویدیویی می­تواند از نوع رشته باشد که در این صورت باید نام کاربری کانال مورد نظر باشد.هم­چنین می­تواند از نوع عدد باشد که در این صورت شناسه مکالمه یا شناسه مخاطب مورد خواهد بود.

پارامتر video در درخواست ارسال ویدیو می­تواند از نوع رشته باشد که در این صورت باید شناسه ویدیویی که قبلا در یکی از سرورهای تلگرام آپلود شده است و یا آدرس http یک ویدیو موجود در اینترنت باشد تا سرورهای تلگرام از آن استفاده کنند. همچنین می­تواند خود ویدیو باشد که در این صورت ویدیو مورد نظر در قالب multipart/form-data آپلود خواهد شد.بات های تلگرام در حال حاضر برای ارسال ویدیو محدودیت حجم 50 مگا­بایتی دارند.

همچنین پارامتر های اختیاری دیگری را نیز می­توان ارسال کرد که در زیر به توضیح مختصری درباره این پارامتر ها میپردازیم.

• duration: این پارامتر از نوع عدد و مشخص کننده مدت زمان ویدیو است.
• width: این پارامتر از نوع عدد و مشخص کننده بعد عرض ویدیو است.
• height:این پارامتر از نوع عدد و مشخص کننده بعد ارتفاع ویدیو است.
• thumb: این پارامتر فقط زمانی که درخواست در قالب multipart/form-data باشد، ارسال می­شود.اندازه این پارامتر باید کمتر از 200 کیلوبایت و ابعاد آن کمتر از 90 باشد.ارسال این پارامتر فقط یک بار انجام می­شود و این پارامتر برای استفاده دوباره نیست.
• caption: این پارامتر از نوع رشته است و متن دلخواهی ست که همراه با سندی در پیام ارسال می­شود.محدودیت 200 حرف در ارسال این پارامتر وجود دارد.
• parse_mode: نحوه نمایش متن به شکل  bold, italic, fixed-width text or inline URLs را مشخص می­کند.
• supports_streaming: این پارامتر از نوع بولی است و مشخص کننده این است که آیا ویدیو آپلود شده برای streaming مناسب است.
• disable_notification: این پارامتر از نوع بولی است و مشخص کننده این است که کاربر پیام را با صدا یا بدون صدا دریافت کند.
• reply_to_message_id: این پارامتر از نوع عدد است.اگر پیام ارسالی یک reply  به پیام دیگری باشد این پارامتر حاوی شناسه پیام اصلی است.
• reply_markup:این پارامتر مشخص کننده انوع کیبورد است که می­توان همراه یک پیام به کاربر ارسال کرد تا کاربر به انتخاب از بین گزینه های موجود در کیبورد مجبور شود.

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

بله:

قبل از ارسال پیام تصویری مانند پیام حاوی فایل ابتدا باید تصویر مورد نظر آپلود شود و fileId و accessHash آن بدست آید.

برای ارسال پیام تصویری باید thumb و ext نیز مشخص شوند و پارامتر های زیر در قالب جیسون در یک درخواست ارسال پیام در ارتباط وب سوکت برای سرور بله ارسال شود.

ارسال این نوع پیام دارای محدودیت حجم ارسال 50 مگا بایتی می باشد.

$type

fileId 

accessHash 

fileStorageVersion 

fileSize 

name 

mimeType 

checkSum 

algorithm

thumb 

ext 

caption

• پارامتر $type از نوع رشته ای و مشخص کننده نوع پیام است.برای پیام حاوی فایل این پارامتر باید برابر  Document باشد.
• پارامتر fileId از نوع عددی است و مشخص کننده شناسه عکس آپلود شد بر روی سرور های بله است.
• پارامتر accessHash از نوع رشته ای و در حقیقت یک کلید یکتا برای بازو به منظور دسترسی به عکس مورد نظر است.
• پارامتر fileStorageVersion از نوع عددی و مشخص کننده محل ذخیره عکس مورد نظر است.مقدار این پارامتر در حال حاضر باید برابر 1 باشد.
• پارامتر  fileSize  از نوع عددی و مشخص کننده اندازه عکس مورد نظر در واحد بایت است.
• پارامتر name از نوع رشته ای و مشخص کننده نام فایل مورد نظر است.
• پارامتر mimeType  از نوع رشته ای و مشخص کننده نوع عکس مورد نظر است.
• پارامتر checkSum  از نوع رشته ای و مشخص کننده این است که آیا بررسی checkSum  انجام بشود یا خیر.مقدار این پارامتر باید برابر checkSum  باشد.
• پارامتر algorithm از نوع رشته ای است و مقدار این پارامتر باید برابر algorithm باشد.
• پارامتر thumb یک جیسون از نوع Thumbو نمایانگر یک thumbnail برای یک عکس است.
• پارامتر ext یک جیسون از نوع Extra، شامل پارامتر های طول ،عرض و نوع پیام است.
•  پارامتر 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 پارامتر های زیر باید ارسال شود.

chat_id

photo

پارامتر chat_id ­در درخواست ارسال عکس می­تواند از نوع رشته باشد که در این صورت باید نام کاربری کانال مورد نظر باشد.هم­چنین می­تواند از نوع عدد باشد که در این صورت شناسه مکالمه یا شناسه مخاطب مورد خواهد بود.

پارامتر photo در درخواست ارسال عکس می­تواند از نوع رشته باشد که در این صورت باید شناسه عکسی که قبلا در یکی از سرورهای تلگرام آپلود شده است و یا آدرس http یک عکس موجود در اینترنت باشد تا سرورهای تلگرام از آن استفاده کنند. همچنین می­تواند خود عکس باشد که در این صورت عکس مورد نظر در قالب multipart/form-data آپلود خواهد شد.

همچنین پارامتر های اختیاری دیگری را نیز می­توان ارسال کرد که در زیر به توضیح مختصری درباره این پارامتر ها میپردازیم.

• caption: این پارامتر از نوع رشته است و متن دلخواهی ست که همراه با سندی در پیام ارسال می­شود.محدودیت 200 حرف در ارسال این پارامتر وجود دارد.
• parse_mode: نحوه نمایش متن به شکل  bold, italic, fixed-width text or inline URLs را مشخص می­کند.
• disable_notification: این پارامتر از نوع بولی است و مشخص کننده این است که کاربر پیام را با صدا یا بدون صدا دریافت کند.
• reply_to_message_id: این پارامتر از نوع عدد است.اگر پیام ارسالی یک reply  به پیام دیگری باشد این پارامتر حاوی شناسه پیام اصلی است.
• reply_markup:این پارامتر مشخص کننده انوع کیبورد است که می­توان همراه یک پیام به کاربر ارسال کرد تا کاربر به انتخاب از بین گزینه های موجود در کیبورد مجبور شود.

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

بله:

قبل از ارسال پیام صوتی مانند پیام حاوی فایل ابتدا باید صوت مورد نظر آپلود شود و fileId و accessHash آن بدست آید.

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

ارسال این نوع پیام دارای محدودیت حجم ارسال 50 مگا بایتی می باشد.

$type

fileId 

accessHash 

fileStorageVersion 

fileSize 

name 

mimeType 

checkSum 

algorithm

thumb 

ext 

caption

• پارامتر $type از نوع رشته ای و مشخص کننده نوع پیام است.برای پیام حاوی فایل این پارامتر باید برابر  Document باشد.
• پارامتر fileId از نوع عددی است و مشخص کننده شناسه صوتی آپلود شد بر روی سرور های بله است.
• پارامتر accessHash از نوع رشته ای و در حقیقت یک کلید یکتا برای بازو به منظور دسترسی به  صوتی مورد نظر است.
• پارامتر fileStorageVersion از نوع عددی و مشخص کننده محل ذخیره صوت مورد نظر است.
• پارامتر  fileSize  از نوع عددی و مشخص کننده اندازه صوت مورد نظر در واحد بایت است.
• پارامتر name از نوع رشته ای و مشخص کننده نام  صوت مورد نظر است.
• پارامتر mimeType  از نوع رشته ای و مشخص کننده نوع صوت مورد نظر است.
• پارامتر checkSum  از نوع رشته ای و مشخص کننده این است که آیا بررسی checkSum  انجام بشود یا خیر.مقدار این پارامتر باید برابر checkSum  باشد.
• پارامتر algorithm از نوع رشته ای است و مقدار این پارامتر باید برابر algorithm باشد.
• پارامتر ext یک جیسون از نوع Extraو شامل پارامتر های مدت زمان و نوع پیام است.
•  پارامتر 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 پارامتر های زیر باید ارسال شود.

chat_id

voice

پارامتر chat_id ­در درخواست ارسال پیام صوتی می­تواند از نوع رشته باشد که در این صورت باید نام کاربری کانال مورد نظر باشد.هم­چنین می­تواند از نوع عدد باشد که در این صورت شناسه مکالمه یا شناسه مخاطب مورد خواهد بود.

پارامتر  voice در درخواست ارسال پیام صوتی می­تواند از نوع رشته باشد که در این صورت باید شناسه صوتی که قبلا در یکی از سرورهای تلگرام آپلود شده است و یا آدرس http یک صوت موجود در اینترنت باشد تا سرورهای تلگرام از آن استفاده کنند. همچنین می­تواند خود صوت باشد که در این صورت عکس مورد نظر در قالب multipart/form-data آپلود خواهد شد.

همچنین voice ها باید با فرمت .ogg ارسال شوند و فرمت های دیگر ممکن است در قالب سند و یا موزیک ارسال شوند.

بات های تلگرام در حال حاضر برای ارسال ویدیو محدودیت حجم 50 مگا­بایتی دارند.

همچنین پارامتر های اختیاری دیگری را نیز می­توان ارسال کرد که در زیر به توضیح مختصری درباره این پارامتر ها میپردازیم.

• caption: این پارامتر از نوع رشته است و متن دلخواهی ست که همراه با سندی در پیام ارسال می­شود. محدودیت 200 حرف در ارسال این پارامتر وجود دارد.
• parse_mode: نحوه نمایش متن به شکل  bold, italic, fixed-width text or inline URLs را مشخص می­کند.
• duration: این پارامتر از نوع عدد و مشخص کننده مدت زمان ویدیو است.
• disable_notification: این پارامتر از نوع بولی است و مشخص کننده این است که کاربر پیام را با صدا یا بدون صدا دریافت کند.
• reply_to_message_id: این پارامتر از نوع عدد است.اگر پیام ارسالی یک reply  به پیام دیگری باشد این پارامتر حاوی شناسه پیام اصلی است.
• reply_markup:این پارامتر مشخص کننده انوع کیبورد است که می­توان همراه یک پیام به کاربر ارسال کرد تا کاربر به انتخاب از بین گزینه های موجود در کیبورد مجبور شود.

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

بله:

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

$type

msg

accountNumber

amount

moneyRequestType

• پارامتر $type از نوع رشته ای و مشخص کننده نوع پیام است.برای پیام حاوی درخواست پول این پارامتر باید برابر  PurchaseMessage باشد.
• پارامتر msg از نوع یکی از انواع پیام های موجود و مشخص کننده یک پیام همراعه با درخواست پول است. در حال حاضر این پارامتر فقط می تواند پیام تصویری باشد.
• پارامتر accountNumber از نوع رشته ای و مشخص کننده شماره کارت دریافت کننده پول است.
• پارامتر moneyRequestType یک شئ از نوع جیسون که خود شامل پارامتر $type است.پارامتر $type باید MoneyRequestNormal باشد.
• پارامتر regexAmount از نوع رشته ای و مشخص کننده عبارت با قاعده مقدار پول درخواستی است.در صورتی که کاربر بخواهد درخواست پول با مقدار پول متغیر ارسال کند مقدار عبارت با قاعده در این پارامتر باید خالی باشد[] و در غیر این صورت مقدار باید مقدار پول مورد نظر خود را در قالب عبارت با قاعده ارسال کند.[100]

پارامتر های یک moneyRequestType:

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

در تلگرام معادل این نوع پیام ، پیامی وجود ندارد.

یکی از انواع پیام ها است که برای ارسال یک محل بر روی نقشه از آن استفاده می شود.

بله:

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

$type

rawJson

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

• dataType: که از نوع رشته ای و مقدار آن  location است.
• data: که خود یک جیسون و شامل پارامتر های longtitiude , latitude است.

قالب جیسون LocationMessage:

{
  "$type": "Json",
  "rawJson": "{\"dataType\": \"location\", \"data\": {\"location\": {\"longitude\": 51.41714821748457, \"latitude\": 35.73122955392002}}}"
}

تلگرام:

برای ارسال  یک نقطه روی نقشه از طریق sendLocation پارامتر های زیر باید ارسال شود.

latitude

longtitude

همچنین پارامتر های اختیاری دیگری را نیز می­توان ارسال کرد که در زیر به توضیح مختصری درباره این پارامتر ها میپردازیم.

• live_period:این پارامتر از نوع عدد است ومدت زمانی است پیام ارسال محل در حال به روزرسانی خواهد بود.این مدت زمان بین 60 ثانیه تا 86400 ثانیه خواهد بود.
• disable_notification: این پارامتر از نوع بولی است و مشخص کننده این است که کاربر پیام را با صدا یا بدون صدا دریافت کند.
• reply_to_message_id: این پارامتر از نوع عدد است.اگر پیام ارسالی یک reply  به پیام دیگری باشد این پارامتر حاوی شناسه پیام اصلی است.
• reply_markup:این پارامتر مشخص کننده انوع کیبورد است که می­توان همراه یک پیام به کاربر ارسال کرد تا کاربر به انتخاب از بین گزینه های موجود در کیبورد مجبور شود.

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

بله:

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

$type

rawJson

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

• dataType: که از نوع رشته ای و مقدار آن contact است.
• data: که خود یک جیسون و شامل پارامتر های emails(لیستی از پست الکترونیکی های مخاطب) ، name و phones( لیستی از شماره تلفن های مخاطب) است.  

قالب جیسون ContactMessage:

{
  "rawJson": "{\"data\": {\"contact\": {\"emails\": [\"test@test.com\"], \"name\": \"test contact\", \"phones\": [\"09123456789\"]}}, \"dataType\": \"contact\"}",
  "$type": "Json"
}

تلگرام:

برای ارسال  یک مخاطب از طریق sendContact پارامتر های زیر باید ارسال شود.

chat_id

phone_number

first_name

پارامتر chat_id ­در درخواست ارسال مخاطب می­تواند از نوع رشته باشد که در این صورت باید نام کاربری کانال مورد نظر باشد.هم­چنین می­تواند از نوع عدد باشد که در این صورت شناسه مکالمه یا شناسه مخاطب مورد خواهد بود.

همچنین پارامتر های اختیاری دیگری را نیز می­توان ارسال کرد که در زیر به توضیح مختصری درباره این پارامتر ها میپردازیم.

• vcard:این پارامتر از نوع رشته و شامل اطلاعات اضافی دیگر درباره مخاطب در فرمت استاندارد vcard است.
• last_name:این پارامتر از نوع رشته و مشخص کننده نام خانوادگی مخاطب است.
• disable_notification: این پارامتر از نوع بولی است و مشخص کننده این است که کاربر پیام را با صدا یا بدون صدا دریافت کند.
• reply_to_message_id: این پارامتر از نوع عدد است.اگر پیام ارسالی یک reply  به پیام دیگری باشد این پارامتر حاوی شناسه پیام اصلی است.
• reply_markup:این پارامتر مشخص کننده انوع کیبورد است که می­توان همراه یک پیام به کاربر ارسال کرد تا کاربر به انتخاب از بین گزینه های موجود در کیبورد مجبور شود.

نوع خاص و بسیار جذابی از پیام که طرفدار های زیادی هم در بین توسعه دهندگان بات دارد پیام حاوی دکمه می باشدء نام این نوع پیام در بله 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 گذاشته شده است و به شما این قابلیت را می دهد که پیام هایی از هر جنس که میخواهید (به جز پیام درخواست پول) را همراه چند دکمه در پایین آن که به دلخواه خودتان مشخص میشود ارسال کنید .

بله:

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

$type

templateMessageId

generalMessage

btnList

responseType

• پارامتر $type از نوع رشته ای و مشخص کننده نوع پیام است.برای این نوع پیام این پارامتر باید برابر  TemplateMessage باشد.
• پارامتر templateMessageId از نوع عددی و مشخص کننده شناسه پیامایی از این نوع است.همانند شناسه برای هر پیام معمولی است این شناسه باید برای هر پیام یک مقدار یکتا داشته باشد.به همین دلیل با شروع به کار یک بازو این پیام ها با شناسه 0 شروع به ارسال شدن کرده و در هر مرحله شناسه 1 واحد افزایش می یابد.
• پارامتر generalMessage از نوع یکی از انواع پیام هاست و مشخص کننده پیامی است که دکمه ها در پایین آن اضافه می شوند.
• پارامتر btnList یک لیست از دکمه های  مختلف است.
• پارامتر responseType از نوع رشته ای و مشخص کننده نوع پاسخی است که کاربر میتواند به این نوع پیام بدهد.

ساختار یک دکمه:

text

value

action

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

قالب جیسون 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 -است که در آن میتوان یک آرایه دو بعدی از دکمه ها را تعریف کرد و همراه هر پیام یک مجموعه دکمه نیز فرستاده شود.

پیام حاوی استیکر یکی از پیام های جذاب است.در صورت تمایل برای ارسال یک پیام حاوی استیکر ابتدا نیاز است تا اطلاعات استیکر مورد نظر را به دست آورید،سپس یک پیام حاوی استیکر ایجاد کنید.

بله:

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

$type

stickerId

stickerCollectionId

stickerCollectionAccessHash

image256

image512

fastPreview

• پارامتر $type از نوع رشته ای و مشخص کننده نوع پیام است.برای پیام حاوی استیکر این پارامتر باید برابر  Stickerباشد.
• پارامتر stickerId از نوع عددی و مشخص کننده شناسه استیکر مورد نظر است.
• پارامتر stickerCollectionId از نوع عددی و مشخص کننده شناسه مجموعه ای است که استیکر در آن قرار دارد.
• پارامتر image256 و image512 اشیا از نوع جیسون و مشخص کننده اطلاعاتی مانند طول، عرض، اندازه و محل ذخیره شدن فایل مربوط به استیکر در سرور بله هستند.

قالب جیسون پیام حاوی استیکر:

{
  "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 پارامتر های زیر باید ارسال شود.

chat_id

sticker

پارامتر chat_id ­در درخواست ارسال پیام صوتی می­تواند از نوع رشته باشد که در این صورت باید نام کاربری کانال مورد نظر باشد.هم­چنین می­تواند از نوع عدد باشد که در این صورت شناسه مکالمه یا شناسه مخاطب مورد خواهد بود.

پارامتر  sticker در درخواست ارسال استیکر می­تواند از نوع رشته باشد که در این صورت باید شناسه استیکری که قبلا در یکی از سرورهای تلگرام آپلود شده است و یا آدرس http یک استیکر موجود در اینترنت باشد تا سرورهای تلگرام از آن استفاده کنند. همچنین می­تواند خود استیکر باشد که در این صورت استیکر مورد نظر در قالب multipart/form-data آپلود خواهد شد.

همچنین پارامتر های اختیاری دیگری را نیز می­توان ارسال کرد که در زیر به توضیح مختصری درباره این پارامتر ها میپردازیم.

• disable_notification: این پارامتر از نوع بولی است و مشخص کننده این است که کاربر پیام را با صدا یا بدون صدا دریافت کند.
• reply_to_message_id: این پارامتر از نوع عدد است.اگر پیام ارسالی یک reply  به پیام دیگری باشد این پارامتر حاوی شناسه پیام اصلی است.
• reply_markup:این پارامتر مشخص کننده انوع کیبورد است که می­توان همراه یک پیام به کاربر ارسال کرد تا کاربر به انتخاب از بین گزینه های موجود در کیبورد مجبور شود.

بله:

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

height

width

thumb

قالب جیسون Thump:

 {
  "height": 80,
  "thumb": "None",
  "width": 80
 }

بله:

Photo Extra: 

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

$type

height

width

• پارامتر $type از نوع رشته ای و مشخص کننده نوع پیام مربوط به این اطلاعات است.برای پیام تصویری این پارامتر باید برابر Photo باشد.
• پارامتر height از نوع عددی و مشخص کننده ارتفاع عکس در پیام است.
• پارامترwidth از نوع عددی و مشخص کننده عرض عکس در پیام است.

قالب جیسون Photo Extra:

{
  "$type": "Photo",
  "height": 80,
  "width": 80
}

Video Extra: 

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

$type

height

width

duration

• پارامتر $type از نوع رشته ای و مشخص کننده نوع پیام مربوط به این اطلاعات است.برای پیام ویدیویی این پارامتر باید برابر Video باشد.
• پارامتر height از نوع عددی و مشخص کننده ارتفاع ویدیو در پیام است.
• پارامترwidth از نوع عددی و مشخص کننده عرض ویدیو در پیام است.
• پارامترduration از نوع عددی و مشخص کننده مدت زمان ویدیو به ثانیه است.

قالب جیسون Video Extra:

 {
 "width": 80,
 "$type": "Video",
 "duration": 9,
 "height": 80
 }

Voice Extra: 

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

$type

duration

• پارامتر $type از نوع رشته ای و مشخص کننده نوع پیام مربوط به این اطلاعات است.برای پیام صوتی  این پارامتر باید برابر Voice باشد.
• پارامترduration از نوع عددی و مشخص کننده مدت زمان صوت به ثانیه است.

قالب جیسونVoice Extra:

 {
  "$type": "Voice",
  "duration": 9
 }

بله: 

آپلود فایل:

برای آپلود فایل  ابتدا باید از سرور آدرسی برای آپلود کردن فایل مورد نظر درخواست کنید.

service

$type

body

id

پارامتر های ارسالی در قالب بالا عبارت اند از:

• id: یک شناسه برای هر پیام است.این شناسه باید برای هر پیام یک مقدار یکتا داشته باشد.به همین دلیل با شروع به کار یک بازو پیام ها با شناسه 0 شروع به ارسال شدن کرده و در هر مرحله شناسه 1 واحد افزایش می یابد.
• service:این پارامتر از نوع رشته ای و مشخص کننده نوع سرویسی است که یک پیام از آن استفاده می کند.برای آپلود یک فایل مقدار این پارامتر باید files باشد.
• $type:این پارامتر از نوع رشته و مشخص کننده نوع پیام ارسالی است.برای ارسال پیام مقدار این پارامتر باید Requestباشد.
• body:این پارامتر یک جیسون و شامل  چند پارامتر دیگر است که عبارت اند از:

crc

size

$type

isServer

fileType

• size:این پارامتر از نوع عددی  و مشخص کننده اندازه فایل مورد نظر در واحد بایت برای  آپلود فایل است.
• crc:این پارامتر از نوع رشته ای و مقدار crc محاسبه شده برای فایل مورد نظر است.از این پارامتر برای اطمینان از صحت ارسال و دریافت استفاده می شود.
• $type:این پارامتر از نوع رشته ای و مشخص کننده نوع درخواست است.برای آپلود فایل لازم است ابتدا یک آدرس از سرور دریافت شود.به این منظور مقدار این پارامتر باید GetFileUploadUrl باشد.
• isServer: این پارامتر از نوع بولی است و مقدار آن باید false باشد.
• fileType: این پارامتر از نوع رشته ای و مقدار آن متناسب با نوع فایل می تواند file یا photo باشد.

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

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

در پاسخ بالا

• پارامتر url آدرسی است که فایل مورد نظر باید در آنجا آپلود شود.
• پارامتر fileId ، شناسه ایجاد شده برای فایل مورد نظر است .از این شناسه در ارسال فایل موردنظر استفاده می شود.
• پارامتر userId، نیز در واقع همان fileAccessHash است که در ارسال فایل مورد نظر استفاده می شود.

سپس در یک درخواست 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"
}

پارامتر های ارسالی در قالب بالا عبارت اند از:

• $type:این پارامتر از نوع رشته و مشخص کننده نوع پیام ارسالی است.برای ارسال پیام مقدار این پارامتر باید Requestباشد.
• service:این پارامتر از نوع رشته ای و مشخص کننده نوع سرویسی است که یک پیام از آن استفاده می کند.برای ارسال یک پیام مقدار این پارامتر بایدmessaging باشد.
• id: یک شناسه برای هر پیام است.این شناسه باید برای هر پیام یک مقدار یکتا داشته باشد.به همین دلیل با شروع به کار یک بازو پیام ها با شناسه 0 شروع به ارسال شدن کرده و در هر مرحله شناسه 1 واحد افزایش می یابد.
• body:این پارامتر یک جیسون و تشکیل شده از چند پارامتر دیگر است که عبارت اند از:
• peer:این پارامتر مشخص کننده گیرنده یک پیام است.توضیحات بیشتر در باره این پارامتر در بخش USER/GROUP آمده است.
• quotedMessage:در صورتی که پیام ارسالی یک پاسخ به پیام دیگر باشد حاوی اطلاعات پیام اصلی است.
• message: این پارامتر مشخص کننده پیام مورد نظر برای ارسال توسط بازو است.
• $type: این پارامتر مشخص کننده نوع درخواست ارسالی برای بازو است.مقدار این پارامتر برای درخواست ارسال پیام SendMessage است.
• randomId: یک شناسه رندم برای هر پیام است.

تلگرام

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

https://api.telegram.org/bot<token>/METHOD_NAME

بعد از دریافت توکن از bot fatherتلگرام برای ارسال هر درخواست لازم است تا جیسون یا فرم متناسب با آن درخواست به آدرسی در فرمت بالا ارسال شود.
به عنوان مثال گرفتن اطلاعات مربوط به بات این عمل به شکل زیر انجام می­شود.

https://api.telegram.org/bot123456:ABC-DEF1234ghIklzyx57W2v1u123ew11/getMe

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

• URL query string
• application/x-www-form-urlencoded
• application/json (except for uploading files)
• multipart/form-data (use to upload files)

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

بله:

در بله هر پیام به یک peer  ارسال می شود.user و group، هر کدام یک نوع Peerو نمایش دهنده یک کاربر یا گروه هستند.

User:

$type

id

accessHash 

• پارامتر $type از نوع رشته ای و مشخص کننده نوع peer است.برای peer کاربر مقدار این پارامتر برابر User است.
• پارامتر id از نوع عددی و شناسه یکتاست که به هر peer اختصاص داده می شود.
• پارامتر accessHash از نوع رشته ای و در حقیقت یک کلید یکتا برای بازو به منظور دسترسی به peer مورد نظر و ارسال پیام به آن است.

Group:

$type

id

accessHash 

• پارامتر $type از نوع رشته ای و مشخص کننده نوع peer است.برای peer گروه یا کانال مقدار این پارامتر برابر  Group است.
• پارامتر id از نوع عددی و شناسه یکتاست که به هر peer اختصاص داده می شود.
• پارامتر accessHash از نوع رشته ای و در حقیقت یک کلید یکتا برای بازو به منظور دسترسی به peer مورد نظر و ارسال پیام به آن است.

قالب جیسون User:

{
    "$type": "User",
    "id": 12323,
    "accessHash": "321132"
}

قالب جیسون Group:

{
    "$type": "Group",
    "id": 12323,
    "accessHash": "321132"
}

تلگرام:

User:

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

id

is_bot

همچنین پارامتر های اختیاری دیگری برای اطلاعات بیشتر می تواند داشته باشد.

Group:

در تلگرام مفهومی برای Group همانند آنچه که  در بله داریم وجود ندارد.برای مشخص کردن یک گروه یا کانال و... از مفهوم Chat استفاده شده است.

Chat:

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

id

type

همچنین پارامتر های اختیاری دیگری برای اطلاعات بیشتر می تواند داشته باشد.

بله:

این شئ نمایش دهنده محل ذخیره شدن یک فایل بر بروی سرورهای بله است. 

fileId

accessHash

fileStorageVersion

• پارامتر fileId از نوع رشته ای و شناسه فایلی است که مورد نیاز است.این شناسه پس از آپلود کردن فایل درسرور های بله در پاسخ برای کاربر ارسال می شود.
• پارامتر accessHash از نوع رشته ای و در حقیقت یک کلید یکتا برای بازو به منظور دسترسی به فایل مورد نظر است.
• پارامتر fileStorageVersion از نوع عددی و مشخص کننده محل ذخیره فایل مورد نظر است.مقدار این پارامتر باید برابر 1 باشد.

قالب جیسون 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"
}

پارامتر های ارسالی در قالب بالا عبارت اند از:

• $type:این پارامتر از نوع رشته و مشخص کننده نوع پیام ارسالی است.برای ارسال پیام مقدار این پارامتر باید Requestباشد.
• service:این پارامتر از نوع رشته ای و مشخص کننده نوع سرویسی است که یک پیام از آن استفاده می کند.برای ارسال یک پیام مقدار این پارامتر بایدmessaging باشد.
• id: یک شناسه برای هر پیام است.این شناسه باید برای هر پیام یک مقدار یکتا داشته باشد.به همین دلیل با شروع به کار یک بازو پیام ها با شناسه 0 شروع به ارسال شدن کرده و در هر مرحله شناسه 1 واحد افزایش می یابد.
• body:این پارامتر یک جیسون و تشکیل شده از چند پارامتر دیگر است که عبارت اند از:
• peer:این پارامتر مشخص کننده گیرنده یک پیام است.توضیحات بیشتر در باره این پارامتر در بخش USER/GROUP آمده است.
• quotedMessage:در صورتی که پیام ارسالی یک پاسخ به پیام دیگر باشد حاوی اطلاعات پیام اصلی است.
• message: این پارامتر مشخص کننده پیام مورد نظر برای ارسال توسط بازو است.
• $type: این پارامتر مشخص کننده نوع درخواست ارسالی برای بازو است.مقدار این پارامتر برای درخواست ارسال پیام SendMessage است.
• randomId: یک شناسه رندم برای هر پیام است.

تلگرام

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

https://api.telegram.org/bot<token>/METHOD_NAME

بعد از دریافت توکن از bot fatherتلگرام برای ارسال هر درخواست لازم است تا جیسون یا فرم متناسب با آن درخواست به آدرسی در فرمت بالا ارسال شود.
به عنوان مثال گرفتن اطلاعات مربوط به بازو این عمل به شکل زیر انجام می­شود.

https://api.telegram.org/bot123456:ABC-DEF1234ghIklzyx57W2v1u123ew11/getMe

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

• URL query string
• application/x-www-form-urlencoded
• application/json (except for uploading files)
• multipart/form-data (use to upload files)

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

بله:

ثبت کردن webhook  برای بازو:

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

Field

userId

endpoint

• userId: این پارامتر از نوع عددی و شناسه بازویی است که برای آن یک webhook مشخص می شود.
• 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 برای یک بازو  لازم است پارامتر های زیر در قالب یک درخواست مانند نمونه برای سرور ارسال شوند. 

Field

userId

• userId: این پارامتر از نوع عددی و شناسه بازویی است که برای آن یک webhook مشخص می شود.

{
  "$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 مطالعه شود. پارامتر های سازنده این کلاس و شرح مختصری درباره هر پارامتر در زیر آمده است. 

• bot: این پارامتر از نوع کلاس bot و یک پارامتر اختیاری است. در صورتی که توسعه دهنده مایل باشد می تواند ابتدا یک شئ بات با مشخصات دلخواه خود را ساخته و آن را به updater ارسال کند.کلاس updater به صورت خودکار هنگام ساختن شئ dispatcher آن را به سازنده این کلاس می دهد. 
• incoming_queue: این پارامتر یک صف است که بین دو شئ updater و dispatcher به اشتراک گذاشته شده است.updater ، update هارا دریافت میکند و در صف قرار می دهد.dispatcher از روی صف update هارا برداشته و پردازش می کند. 
• workers: این پارامتر از نوع عددی وبرابر تعداد نخ ها (thread) هایی است که dispatcher در حین اجرا از آنها استفاده میکند. این پارامتر اختیاری بوده و در صورتی که توسط توسعه دهنده حین ساختupdater  مقدار دهی نشود مقدار خود را با توجه به فایل Config از متغیرهای محیط سیستم عامل میگیرد و چنان چه چنین متغیری وجود نداشته باشد مقدار آن برابر مقدار پیش فرض موجود در این فایل خواهد شد. مقدار پیش فرض برای این پارامتر برابر 64 است. 
• bot: این پارامتر از نوع کلاس bot و یک پارامتر اختیاری است. در صورتی که توسعه دهنده مایل باشد می تواند ابتدا یک شئ بات با مشخصات دلخواه خود را ساخته و به عنوان ورودی به سازنده کلاسupdater بدهد.در صورتی که این کار را نکند به صورت پیشفرض یک شئ در سازنده کلاس updater ساخته خواهد شد. 
• adapter_kwargs: این پارامتر یک دیکشنری حاوی کلید ها و مقادیر متناظر با آن ها و یک پارامتر اختیاری است. یک بازو برای ایجاد ارتباط http و ارسال درخواست خود ابتدا باید یک session ایجاد کند  ویا از یک session استفاده کند. ایجاد این session و تنظیم کردن آن در این کتابخانه به کمک کتابخانه requests انجام می شود.توسعه دهنده در صورت تمایل میتواند تنظیمات دلخواه خود را برای ایجاد session به سازنده این کلاس ارسال کند.در صورتی که این کار را نکند یک session پیش فرض ساخته خواهد شد. این پارامتر ها عبارت اند از: 

  *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 است. توسعه دهنده با ایجاد یک شئ از این کلاس و به کمک توابع پیاده سازی شده در این کلاس می تواند به سروردرخواست های مختلف ارسال پیام ،آپلود فایل و دانلود فایل را ارسال کند. پارامتر های سازنده این کلاس و شرح مختصری درباره هر پارامتر در زیر آمده است. 

• token: این پارامتر از نوع رشته ای، اجباری بوده ونشانه بازویی است که بازو پدر برای شما ساخته و به شما داده است. 
• user_id: این پارامتر از نوع عدد، اجباری بوده و شناسه بازویی است که بازو پدر برای شما ساخته و به شما داده است. 
• base_url: این پارامتر از نوع رشته ای و آدرس پایه ای است که بازو درخواست های خود را به آن ارسال می کند. این پارامتر اختیاری بوده و در صورتی که توسط توسعه دهنده مقدار دهی نشود مقدار خود را با توجه به فایل Config از متغیرهای محیط سیستم عامل میگیرد و چنان چه چنین متغیری وجود نداشته باشد مقدار آن برابر مقدار پیش فرض موجود در این فایل خواهد شد 
• adapter: یک رابط عمومی برای یک session  به منظور ایجاد درخواست های http است. 
• session: یک بازو برای ایجاد ارتباط http و ارسال درخواست خود ابتدا باید یک session ایجاد کند و یا از یک session استفاده کند. ایجاد این session و تنظیم کردن آن در این کتابخانه به کمک کتابخانه requests انجام می شود.توسعه دهنده در صورت تمایل میتواند یک session ایجاد کرده و به عنوان پارامتر به سازنده کلاس بازو ارسال کند.در صورتی که این کار را نکند یک session پیش فرض ساخته خواهد شد. 

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

http://docs.python-requests.org/en/master/api/#requests.adapters.HTTPAdapter

کلاس dispatcher کلاسی است که آپدیت های دریافت شده توسط شئ updater را از صف ورودی برداشته، handler مربوط به آن را پیدا کرده و آن را پردازش می کند.این پردازش می تواند در همان thread و یا در یک thread دیگر انجام شود. نحوه پردازش یک handler  نیز توسط خود توسعه دهنده مشخص می شود.برای اطلاعات بیشتر بخش Concurrency مطالعه شود. . پارامتر های سازنده این کلاس و شرح مختصری درباره هر پارامتر در زیر آمده است. 

• incoming_queue: این پارامتر یک صف است که بین دو شئ updater و dispatcher به اشتراک گذاشته شده است.updater ، update هارا دریافت میکند و در صف قرار می دهد.dispatcher از روی صف update هارا برداشته و پردازش می کند. 
• bot: این پارامتر از نوع کلاس bot و یک پارامتر اختیاری است. در صورتی که توسعه دهنده مایل باشد می تواند ابتدا یک شئ بات با مشخصات دلخواه خود را ساخته و آن را به updater ارسال کند.کلاس updater به صورت خودکار هنگام ساختن شئ dispatcher آن را به سازنده این کلاس می دهد. 
• workers: این پارامتر از نوع عددی وبرابر تعداد نخ ها (thread) هایی است که dispatcher در حین اجرا از آنها استفاده میکند. این پارامتر اختیاری بوده و در صورتی که توسط توسعه دهنده حین ساختupdater  مقدار دهی نشود مقدار خود را با توجه به فایل Config از متغیرهای محیط سیستم عامل میگیرد و چنان چه چنین متغیری وجود نداشته باشد مقدار آن برابر مقدار پیش فرض موجود در این فایل خواهد شد. مقدار پیش فرض برای این پارامتر برابر 64 است. 

این کتابخانه برای 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)

یکی از انواع پیام ها است که برای ارسال یک محل بر روی نقشه از آن استفاده می شود.
مثال ساده‌ای از ایجاد یک locati‌on 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)

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

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

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 کنید. پارامتر‌های ورودی این متد عبارتند از :

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

@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 عمل می‌کند و فقط کار ارسال پاسخ را آسان‌تر می کند . پارامتر‌های ورودی این متد عبارتند از:

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

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

upload_file :

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

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

توضیحات کامل تر در رابطه با آپلود فایل در قسمت API در دسترس قرار دارد.

download_file:

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

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

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

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

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

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

پارامتر هاي ارسالي در قالب بالا عبارت اند از:

• $type:اين پارامتر از نوع رشته و مشخص کننده نوع پيام ارسالي است.براي ويرايش پيام مقدار اين پارامتر بايد Requestباشد.
• service:اين پارامتر از نوع رشته اي و مشخص کننده نوع سرويسي است که يک پيام از آن استفاده مي کند.براي ارسال يک پيام مقدار اين پارامتر بايدmessaging باشد.
• id: يک شناسه براي هر پيام است.اين شناسه بايد براي هر پيام يک مقدار يکتا داشته باشد.به همين دليل با شروع به کار يک بازو پيام ها با شناسه 0 شروع به ارسال شدن کرده و در هر مرحله شناسه 1 واحد افزايش مي يابد.
• body:اين پارامتر يک جيسون و تشکيل شده از چند پارامتر ديگر است که عبارت اند از:
  • peer: اين پارامتر مشخص کننده گيرنده يک پيام است.توضيحات بيشتر در باره اين پارامتر در بخش USER/GROUP آمده است.
  • randomId: هر پيام در زمان ارسال براي اولين بار حاوي يک شناسه با  عنوان randonId است که فرستنده آن را ايجاد مي کند.براي ويرايش پيام مورد نظر لازم است تا اين شناسه به عنوان پارامتر randomId در درخواست ويرايش پيام ارسال شود.
  • message: اين پارامتر مشخص کننده پيام مورد نظر براي ارسال توسط بازو است.

تلگرام:

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

https://api.telegram.org/bot<token>/METHOD_NAME
برای ویرایش پیام متنی باید پارامتر های زیر به سمت سرور ارسال شود.

• شناسه پیام مورد نظر
• متن مورد نظر

بله:

*توجه: این سرویس در حال حاضر یک سرویس آزمایشی می باشد.

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

<https://apitest.bale.ai/v1/bots/http/<token
برای ارسال درخواست ها از طریق ارتباط Http ابتدا لازم است تا از bot father بله توکن دریافت کنیدو در ادرس بالا در محل مناسب قرار دهید. و درخواست های خود را به این آدرس از طریق درخواست Post ارسال کنید.
براي ويرايش يک پيام ابتدا لازم است يکي از انواع پيام هاي متني، پيام حاوي فايل و يا 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"
}

پارامتر هاي ارسالي در قالب بالا عبارت اند از:

• $type:اين پارامتر از نوع رشته و مشخص کننده نوع پيام ارسالي است.براي ويرايش پيام مقدار اين پارامتر بايد Requestباشد.
• service:اين پارامتر از نوع رشته اي و مشخص کننده نوع سرويسي است که يک پيام از آن استفاده مي کند.براي ارسال يک پيام مقدار اين پارامتر بايدmessaging باشد.
• id: يک شناسه براي هر پيام است.اين شناسه بايد براي هر پيام يک مقدار يکتا داشته باشد.به همين دليل با شروع به کار يک بازو پيام ها با شناسه 0 شروع به ارسال شدن کرده و در هر مرحله شناسه 1 واحد افزايش مي يابد.
• body:اين پارامتر يک جيسون و تشکيل شده از چند پارامتر ديگر است که عبارت اند از:
  • peer: اين پارامتر مشخص کننده گيرنده يک پيام است.توضيحات بيشتر در باره اين پارامتر در بخش USER/GROUP آمده است.
  • randomId: هر پيام در زمان ارسال براي اولين بار حاوي يک شناسه با  عنوان randonId است که فرستنده آن را ايجاد مي کند.براي ويرايش پيام مورد نظر لازم است تا اين شناسه به عنوان پارامتر randomId در درخواست ويرايش پيام ارسال شود.
  • message: اين پارامتر مشخص کننده پيام مورد نظر براي ارسال توسط بازو است.

تلگرام:

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

https://api.telegram.org/bot<token>/METHOD_NAME

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

• شناسه پیام مورد نظر

• متن مورد نظر