README

Contents

Introducion

Creating you bot

Utils
Mysql features
- Context
- Chats
Inquiry
InputHandle
- Creating a new InputHandle object
- Working with data
Privilege
Examples
License

Introducion

If you want to create your bot, for the first you need to register him.You can do it with @BotFather. Open the dialog with him and write /newbot , like as in this image:

After that you need to set webhook on your bot.Webhook its a system, who sending queries to your server, if telegram gets one.

Before start creating a webhook you need bot api token and server.If you dont have a server, you can use heroku to create one.

You can find your bot api token by writing /mybots, then select your bot, and then select button "API Token".Example:

When you finish all this actions, you can set webhook to your bot.For this you need to use bot api method setWebhook:

Then, if you done all right, you will see this answer:

After that you can start working with your bot.But how I can work?You can ask me.Lets see, how.

Creating you bot

How to create bot?Very easy!Just create a new bot class:

	use \Telbot\Bot as Bot;

	$bot = new Bot('BOT_API_KEY HERE');

So, lets create a script, who will send a text message as test.But how?The Inquiry class will help us with it:

	use \Telbot\Bot as Bot;
	use \Telbot\Inquiry as Inquiry;
	use \Telbot\InputHandle as InputHandle;

	$bot = new Bot('API_TOKEN');
	$InputHandle = new InputHandle();

	Inquiry::send($bot
			,'sendMessage',
		[
			'chat_id' => $InputHandle->getChatId(),
			'text' => 'Testing your bot.'
		]
	);

Utils

Supporting class for ease of work with telegram bot api types.

Creating keyboard

You can create keyboards easy using this way:

	use \Telbot\Utils\ as Utils;
	use \Telbot\Bot as Bot;

	Utils::buildInlineKeyboard([[['one', 'text']], [['two', 'text']], [['three', 'test']]])

	Utils::buildKeyboard([[['third'], ['second'], ['first']]])

Examples:

	use \Telbot\Utils as Utils;
	use \Telbot\Bot as Bot;
	use \Telbot\InputHandle as InputHandle;
	use \Telbot\Inquiry as Inquiry;

	$bot = new Bot('API_TOKEN');
	$InputHandle = new InputHandle();

	Inquiry::send($bot, 'sendMessage', [
		'chat_id' => $InputHandle->getChatId(),
		'text' => 'Simple text.',
		'reply_markup' => Utils::buildInlineKeyboard([[['one', 'callback']], [['two', 'callback']], [['three', 'callback']]])
	]);

Encoding files

If you want to send video or photo to user, you need to encode them to CURl format.For this use this method:

	Utils::encodeFile($filePath) //return encoded CURlfile object.

Parameter $filePath need to indicate path to file you want to send.

Building inline query result

If you want to send an answer to inline query, you need to build answer object.For this use this method:

	Utils::buildInlineQueryResult($resultType ,$data) //returns json encoded array of $data with type of result $resultType

You can check example here

Mysql features

To start work with mysql, first you need to do is enable sql connection in your bot object:

	$bot->enableSql();

You can also disable sql by using similar method:

	$bot->disableSql();

Warning: if your sql connection doesnt exist, you can not use this modules:User, Chat. In this case Context instead of writing context values to the database would be create new file with context(one to user).

Later you need to specify sql credentials:

	$bot->sqlCredentials(
		[
			'database_server' => '',
			'database_name' => '',
			'username' => '',
			'password' => ''
		]
		);

Or you can indicate your external pdo connection as sql credentials:

	$bot->externalPDO($PDO_CONNECTION);

After all this actions, you can start to work with database.

Context

Using class Context you can create context dependence:

	use \Telbot\Context as Context; //We include new class Context
	use \Telbot\Bot as Bot;
	use \Telbot\Inquiry as Inquiry;
	use \Telbot\InputHandle as InputHandle;
	
	$InputHandle = new InputHandle();
	$bot = new Bot('API_TOKEN');
	$DBH = new PDO();
	$bot->externalPDO($DBH);
	$bot->enableSql();

	if(!Context::read($bot, $InputHandle->getChatId(), $InputHandle->getUserId())){ //reading context
		Inquiry::send($bot
				,'sendMessage',
			[
				'chat_id' => $InputHandle->getChatId(),
				'text' => 'Write smth'
			]
		);
		Context::write($bot, $InputHandle->getChatId(), $InputHandle->getUserId(), 'smth'); //creating new context
	}else{
		Inquiry::send($bot
			,'sendMessage',
			[
			'chat_id' => $InputHandle->getChatId(),
			'text' => 'Okay, you writed!'
			]
		);
		Context::delete($bot, $InputHandle->getChatId(), $InputHandle->getUserId()); //delete context
	}

Working with chats in database

All the same, but a bit different:

To add chats to database, you need to use this function:

	Chat::add($bot, $chatId);

To delete chats:

	Chat::delete($bot, $chatId);

To get chats:

	Chat::get($bot, $chatId);

This function returns array with row information of this chat(row id, chat id, bot token)

To get all chats:

	Chat::getAll($bot);

Inquiry

Its the main class in this library.This paragraph shows all capabilities of this class.

This class has only one method - Inquiry::send().With this class you can send both simple text messages and complex answers.

	Inquiry::send($bot, $method, $data);

Supported methods

All method supported during version of API 4.7

Sending simple answer

	Inquiry::send($bot, 'sendMessage', [
		'chat_id' => $InputHandle->getChatId(),
		'text' => 'This is a testing message'
	
	]);

Sending callback query answer

	Inquiry::send($bot, 'answerCallbackQuery', [
		'callback_query_id' => $InputHandle->getCallbackQueryId(),
		'text' => 'This is a callback answer, who lool like common notification'
	]);

Sending Inline query answer

	Inquiry::answerInlineQuery($bot, [
		'inline_query_id' => $InputHandle->getInlineQueryId(),
		'results' => Utils::buildInlineQueryResult('article', [
		'title' => 'test',
		'input_message_content' => [
			'message_text' => 'Yes, its just test'
		]])
	]);

You can send any of telegram methods with this method send.All of this supported.

Sending files

	//sending photo
	use \Telbot\Bot as Bot;
	use \Telbot\InputHandle as InputHandle;
	use \Telbot\Inquiry as Inquiry;

	$bot = new Bot('927942575:AAHZpZoG2pBRw25Lw-pPaw8FU15t00Lsf3A');
	$InputHandle = new InputHandle();

	Inquiry::send($bot ,'sendPhoto', [
		'chat_id' => $InputHandle->getChatId(),
		'photo' => 'https://upload.wikimedia.org/wikipedia/commons/thumb/8/83/Telegram_2019_Logo.svg/1200px-Telegram_2019_Logo.svg.png',
		'caption' => 'This is an image!So beautiful'
	]);

To send files from your server, you need to encode file to CURl format.For this, you need to use method Utils::encodeFile.

	use \Telbot\Utils as Utils;
	use \Telbot\Bot as Bot;
	use \Telbot\InputHandle as InputHandle;
	use \Telbot\Inquiry as Inquiry;

	$bot = new Bot('927942575:AAHZpZoG2pBRw25Lw-pPaw8FU15t00Lsf3A');
	$InputHandle = new InputHandle();

	Inquiry::send($bot ,'sendPhoto', [
		'chat_id' => $InputHandle->getChatId(),
		'photo' => Utils::encodeFile('app/something/telegram.png'),
		'caption' => 'This is an image!So beautiful'
	]);

Input Handle

This class needs for comfortable work with telegram answer query.

Creating a new InputHandle object

	$InputHanle = new InputHandle();

Working with data

	$InputHandle->getUpdateId() // returns an update id of telegram answer query.

	$InputHandle->getQueryType() // returns a query type of telegram answer query(callback_query,inline_query,message).

	$InputHandle->getInstance() // returns an array of telegram answer.

	$InputHandle->getCallbackData() //  returns a callback data from telegram answer query.

	$InputHandle->getCallBackQueryId() // returns a callback query id from telegram answer query.

	$InputHandle->getUserId() // returns user id.

	$InputHandle->userIsBot() // return true if user who send quiry is bot.

	$InputHandle->getUserName() // returns name of user, who sends query.

	$InputHandle->getMessageId() // returns user's message id.

	$InputHandle->getUserFirstName() // returns user's first name.

	$InputHandle->getLanguageCode() // returns user's language code.

	$InputHandle->getChatType() // returns chat type.

	$InputHandle->getChat() // returns chat array from telegram answer query.

	$InputHandle->newChatMember() // returns true when new member comes to telegram chat.

	$InputHandle->getChatId() // returns a chat id, where the message come.

	$InputHandle->getDate() // returns date when telegram answer query was send.

	$InputHandle->getEntities() // returns message entities from telegram answer query.

	$InputHandle->getChatTitle() // returns title of chat where bot gets query.

	$InputHandle->getInlineQueryText() // returns query data from inline query.

	$InputHandle->getInlineQueryOffset() // returns query offset from inline query.

	$InputHandle->getInlineQueryId() // returns an inline query in from telegram answer query.

Privelege

You can give a user a specific privilege in the chat(or all chats). This can be used to give access to certain commands to that particular user.

	Privilege::setToChat($bot, $value, $userId, $chatId); //for one chat

	Privilege::setToAllChats($bot, $value, $userId); //for all chats

	Privilege::get($bot, $userId); //getting a privelege

Examples

See examples at 'examples' folder.

License

Please see the LICENSE included in this repository for a full copy of the MIT license, which this project is licensed under.

shamanhead / telbot

Maintainers

Details