New API calls needed in BotAPIfunctions.php

[simocosimo]

Todo

• Modify existing functions, extending/improving functionalities and usability
• Add new API calls that might be useful in the future

Description

We should be writing new functions (API call wrappers) in BotAPIfunctions.php.
The aim should be writing functions with all possible parameters, paying attention to check for the required ones.
Try to target only useful calls, no need to implement them all.
Telegram Bot API documentation

Before start working on this, please comment with the function(s) you're currently coding, so we don't overlap work.

How to write functions

We should be writing functions in a way that will let us use different numbers of parameters very easily, without writing unreadable (and difficult to use) code.
Bitmasks are a perfect tool for this.
This necessity derives directly from the very high number of boolean parameters that the Telegram Bot API lets us use.
We'll not use every single API method and we'll not use every single parameter that the API offers us, but when we do, we'll have the need to specify only some of the optional parameters in a very readable way.

Every wrapper of an API method, that allows the passing of optional (and, for us, useful) parameters, should take a $flag parameter, which default value should be 0 (zero). This parameter is of type int but the value inside will be considered as a binary number.

Function declaration:

inginf_bot/basefunctions.php

Line 366 in c6a8fa6

function sendMessage($chatId, string $text, int $flags = 0, array $keyboard = [], int $messageId = 0) {

When calling the function from the outside, we will use something like this:
$message = sendMessage($chat_id, $text, ENABLE_PAGE_PREVIEW | DISABLE_NOTIFICATION);

As you can see, the first 2 parameters are the required ones, while the third is optional, with a default value of zero.
When specifying the $flags you can see we are making use of the bitwise OR operator applied to some constants defined in constants.php.

These constants are binary values, each of them representing a boolean feature that we want our function to use.
In the example, we see we want to send the message enabling the link preview while not sending the user a notification. To combine features, it's necessary to use the | operator.
Features constants look like this:

inginf_bot/constants.php

Lines 23 to 26 in c6a8fa6

	const MARKDOWN = 1 << 0;
	const ENABLE_PAGE_PREVIEW = 1 << 1;
	const DISABLE_NOTIFICATION = 1 << 2;
	const SHOW_ALERT = 1 << 3;

Adding a constant is really easy:

• declare it as you see in the example above
• add one to the last constant value after the << operator
• check that what you're writing is not an already existing constant (both logically and numerically).
  A fifth one could look like this:
  const SUPPORTS_STREAMING = 1 << 4;

Writing the functions, we have to handle the value generated by the bitmask passed as a parameter while also defining the constants allowed to be passed in the function itself.
Take a look at this snippet of code:

inginf_bot/basefunctions.php

Lines 386 to 399 in c6a8fa6

	// Check if the parse mode must be setted to 'MarkdownV2'
	if ($flags & MARKDOWN) {
	$parseMode = 'MarkdownV2';
	}
	// Check if the preview for links must be enabled
	if ($flags & ENABLE_PAGE_PREVIEW) {
	$disablePreview = FALSE;
	}
	// Check if the message must be muted
	if ($flags & DISABLE_NOTIFICATION) {
	$mute = TRUE;
	}

Using the & operator (bitwise AND) we check the presence of the feature in the $flag parameter, this will let us be able to set internal variables correctly and make the right API call.

Main API calls to implement (constantly updating)

The following list is just for reference.
If you find it useful to write different functions for the same API call, please tell us in the comment so we can discuss it.

• answerCallbackQuery()
• answerInlineQuery()
• deleteMessage()
• editMessageCaption()
• editMessageMedia()
• editMessageReplyMarkup()
• editMessageText()
• exportChatInviteLink()
• forwardMessage()
• getChat()
• getChatAdministrators()
• getChatMember()
• getFile()
• getMe()
• kickChatMember()
• leaveChat()
• pinChatMessage()
• promoteChatMember()
• restrictChatMember()
• setChatPermissions()
• sendAnimation()
• sendAudio()
• sendDocument()
• sendMediaGroup()
• sendMessage()
• sendPhoto()
• sendVideo()
• sendVoice()
• setMyCommands()
• unbanChatMember()
• unpinChatMessage()

[simocosimo]

I'm now working on the following functions:

• answerCallbackQuery()
• answerInlineQuery()
• deleteMessage()
• editMessageCaption()

These functions are already present in basefunctions.php but some modifications are needed. I'm on it!

[Binco97]

I'm working on the following functions:

• forwardMessage()
• getChat()
• pinChatMessage()
• sendPhoto()

[giulio-coa]

I have completed the list of the API calls

[giulio-coa]

@atlas-ark have improved the sendMessage() API calls

[simocosimo]

Working on replyToMessage() method. This is not listed in the API calls to implement, but I think it's going to be useful.
It'll be a sendMessage() wrapper with the required parameter of the $messageId to respond to.

[giulio-coa]

Working on replyToMessage() method. This is not listed in the API calls to implement, but I think it's going to be useful.
It'll be a sendMessage() wrapper with the required parameter of the $messageId to respond to.

Maybe it can be a wrapper for the sendMessage()

Implement the changes into the sendMessage()
The sendMessage() will have the $messageId parameter set to the default value (0), while the replyToMessage() will have it set to a specific value

[simocosimo]

Maybe it can be a wrapper for the sendMessage()

Implement the changes into the sendMessage()
The sendMessage() will have the $messageId parameter set to the default value (0), while the replyToMessage() will have it set to a specific value

Took care of this in #24 with the last commit

[giulio-coa]

I'll work on the following functions:

• sendAudio()
• sendAnimation()
• sendMediaGroup()
• sendVideo()
• sendVoice()
• setMyCommands()
• unbanChatMember()
• unpinChatMessage()

[Binco97]

I'll work on the following functions:

• editMessageMedia()
• exportChatInviteLink()
• getChatAdministrators()
• getChatMember()
• getFile()
• getMe()

[simocosimo]

I'll work on the following functions:

• kickChatMember()
• leaveChat()
• promoteChatMember()
• restrictChatMember()
• setChatPermission()
• sendDocument()