docs optimization

docs/13.api/1.bots.md

@@ -0,0 +1,135 @@
+---
+title: 'Bots API calls'
+navigation.title: 'Bot Management'
+---
+
+## `botInfo()`
+
+retrieves Bot data from Telegram APIs
+
+```php
+Telegraph::botInfo()->send();
+
+/*
+id: xxxxx
+is_bot: true
+first_name: telegraph-test
+username: my_test_bot
+can_join_groups: true
+can_read_all_group_messages: false
+supports_inline_queries: false
+*/
+```
+
+
+## `botUpdates()`
+
+retrieves the bot updates from Telegram APIs
+
+```php
+Telegraph::bot($telegraphBot)->botUpdates()->send();
+```
+
+> [!WARNING]
+> Manual updates polling is not available if a webhook is set up for the bot. Webhook should be remove first using its [unregisterWebhook](webhooks/deleting-webhooks) method
+
+
+### `Long Polling`
+
+In production environment, a timeout (in seconds) should be declared, in order to allow long polling:
+
+```php
+Telegraph::bot($telegraphBot)->botUpdates(timeout: 60)->send();
+```
+
+
+
+## `registerBotCommands()`
+
+register commands in Telegram Bot in order to display them to the user when the "/" key is pressed
+
+```php
+Telegraph::registerBotCommands([
+    'command1' => 'command 1 description',
+    'command2' => 'command 2 description'
+])->send();
+```
+
+## `unregisterBotCommands()`
+
+resets Telegram Bot registered commands
+
+```php
+Telegraph::unregisterBotCommands()->send();
+```
+
+## `getRegisteredCommands()`
+
+retrieve bot's registered commands.
+
+```php
+$response = Telegraph::getRegisteredCommands()->send();
+$response->json('result');
+```
+
+
+
+## `registerWebhook()`
+
+register a webhook for the active bot
+
+```php
+Telegraph::registerWebhook()->send();
+```
+
+## `unregisterWebhook()`
+
+unregister a webhook for the active bot
+
+```php
+Telegraph::registerWebhook()->send();
+```
+
+
+## `getWebhookDebugInfo()`
+
+retrieves webhook debug data for the active bot
+
+```php
+$response = Telegraph::getWebhookDebugInfo()->send();
+```
+
+
+## `getFileInfo`
+
+Retrieve file info from ID
+
+```php
+Telegraph::getFileInfo($fileId)->send();
+```
+
+
+
+
+## `store()`
+
+Downloads a media file and stores it in the given path
+
+```php
+/** @var DefStudio\Telegraph\DTO\Photo $photo */
+
+Telegraph::store($photo, Storage::path('bot/images'), 'The Photo.jpg');
+```
+
+> [!WARNING]
+> There is an hard limit of 20BM for downloaded files sizes. This is a Telegram limitation for bots, sadly, there is no workaround available.
+> refer the [docs](https://core.telegram.org/bots/api#getfile) for more info.
+
+
+## `setBaseUrl()`
+
+allows to override Telegram API url on a per-message basis:
+
+```php
+Telegraph::setBaseUrl('https://my-secret-server.dev')->message('secret message')->send();
+```