====== API UbillingTelegram ======

Ubilling надає зручну модель абстракції, для роботи з повідомленнями [[https://core.telegram.org/api|бота Telegram]]. Починаючи зі стабільного релізу Ubilling 0.8.0 ви можете використовувати базовий клас UbillingTelegram для надсилання, приймання та читання повідомлень, прийнятих ботом. Для надсилання повідомлень потрібен токен заздалегідь [[https://tlgrm.ru/docs/bots|створеного бота]] і ввімкнена та налаштована підсистема [[senddog|собаки-посилаки]]. Так, ви можете запросити бота у свою закриту групку або куди забажаєте.

API базового класу UbillingTelegram намагається повторювати роботу [[ubillingsms|UbillingSMS]] і бути максимально простим для розуміння. Також ви можете одночасно працювати з кількома ботами, створивши для кожного з них по екземпляру класу, або на-ходу перемикаючи їхні токени. Розглянемо роботу з ботом на простому прикладі:

<code php>
$botToken = '123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11';
// ми можемо передавати токен нашого бота або в конструкторі класу
$telegram = new UbillingTelegram($botToken);
// або примусово виставити за допомогою публічного методу setToken, наприклад так:
$telegram->setToken($botToken);
// ми можемо отримати список контактів, які раніше писали боту або в чати, в які він запрошений
$botContacts = $telegram->getBotContacts();
debarr($botContacts);

// Також ми можемо помістити повідомлення в чергу для подальшого надсилання собакою-посилакой для одного з цих chatid.
// Рекомендується використовувати цей метод у ваших модулях.
$chatId = '-1001070840004';
$telegram->sendMessage($chatId, 'це тестове повідомлення', false, 'SAMPLEMODULE');

// Далі, якщо буде потрібно, ми можемо працювати з чергою повідомлень.
// наприклад отримати кількість повідомлень, які очікують на відправлення
$queueCount=$telegram->getQueueCount();
deb($queueCount);

//або вміст цієї черги у вигляді масиву
$queueData=$telegram->getQueueData();
debarr($queueData);

//Також нам ніхто не забороняє почитати, які ж приватні або повідомлення каналу отримував бот:
$botChats=$telegram->getBotChats();
debarr($botChats);

// Якщо нам потрібне надсилання повідомлення від імені бота, відмінного від налаштованого в собаці-посилаці,
// ми можемо примусово ініціалізувати надсилання повідомлення в обхід черги за допомогою публічного методу "прямо зараз"
$telegram->directPushMessage($chatId, 'это тоже тестовое сообщение посланное напрямую');
</code>


Також є можливість увімкнути режим налагодження, щоб бачити запити і відповіді на них від сервера API:
<code php>
$telegram->setDebug(true);
</code>


А також відсилати дані про місцезнаходження контактам вашого бота. Приклад:
<code php>
$testText = 'sendLocation:50.45093260638449, 30.52267174950622'; // так, формат повідомлення "sendLocation:координати"
$telegram->sendMessage($chatid, $testText);
</code>

А можна не просто дані про місцезнаходження, а також із заголовком і адресою:
<code php>
$message='title:{Налаштувати роутер}address:(Де бабайко каже надобраніч)sendVenue:[50.45093260638449, 30.52267174950622]';
$telegram->directPushMessage($chatid, $message);
</code>

Так, усі поля і формат дужок суворо обов'язкові.

А ще можна встановлювати кастомну розмітку для ваших повідомлень. Наприклад використовувати HTML. Наприклад так:
<code php>
 $message='Просто текст <b>жирний текст</b> <a href="http://ubilling.net.ua">Посилання на сайт</a> parseMode:{html}';
 $telegram->directPushMessage($chatid, $message);
</code>

Формат надсилання фоточок наступний:
<code php>
$message = 'sendPhoto:[https://piclod.com/i/1737542661/kitty.jpg]{Це опціональний заголовок}';

$telegram->sendMessage($chatId, $message);
</code>

Також ви можете використовувати для ваших ботів кастомні клавіатури. Для цього клавіатуру, зібрану з масиву за допомогою **makeKeyboard**, тупо відсилають за допомогою **directPushMessage**. Якось так:
<code php>
        $buttonsArray[] = array('кнопка раз', 'кнопка поруч');
        $buttonsArray[] = array('кнопка внизу');
        
        $keyboard = $telegram->makeKeyboard($buttonsArray, false, true, true);
        $telegram->directPushMessage($chatid, 'Тут клавіатура вилізла!', $keyboard);
</code> 

Примусово її вбити можна зі свого боку, використовуючи повідомлення, що містить текст вигляду "removeKeyboard:тут текст повідомлення"

<code php>
 $telegram->directPushMessage($chatid, 'removeKeyboard:ой ну і добре');
</code> 


Також можна банити та розбанювати користувачів в групових чатах:

<code php>
 $telegram->directPushMessage($groupId, 'banChatMember:[' . $memberId . '@' . $groupId . ']');
</code> 


<code php>
 $telegram->directPushMessage($groupId, 'unbanChatMember:[' . $memberId . '@' . $groupId . ']');
</code>