httd1 / telegramphp
This is a PHP package for using Telegram Bot API
Requires
- php: >=7.0
- ext-curl: *
Requires (Dev)
- phpunit/phpunit: ^9.5
README
Esse é um pacote em PHP para uso da API de bots do Telegram.
Esse pacote foi pensado para uso exclusivamente por Webhook,
antes do uso leia a documentação completa do Telegram aqui https://core.telegram.org/bots/api
Requisitos
- PHP>=7.0
- cURL
- JSON
Instalação
composer require httd1/TelegramPhp
Uso:
<?php include __DIR__.'/vendor/autoload.php'; use \TelegramPhp\TelegramPhp; use \TelegramPhp\Methods; use \TelegramPhp\Buttons; // set bot token \TelegramPhp\Config\Token::setToken ('110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw'); $tlg = new TelegramPhp; $tlg->command ('/start', function ($bot){ // send message Methods::sendMessage ([ 'chat_id' => $bot->getChatId (), 'text' => 'Hello 👋' ]); }); // Passing parameters to a command with {{info}} $tlg->command ('/get {{info}}', function ($bot, $data){ switch ($data ['info']){ case 'id': $user_info = $bot->getUserId (); break; case 'username': $user_info = $bot->getUsername (); break; case 'name': $user_info = $bot->getFullName (); break; default: $user_info = "Use <code>/get id or username or name</code>"; } Methods::sendMessage ([ 'chat_id' => $bot->getChatId (), 'text' => "User Info: <b>{$user_info}</b>", 'parse_mode' => 'html', 'reply_markup' => Buttons::inlineKeyBoard ([ [Buttons::inlineKeyBoardUrl ("Link My Profile", "tg://user?id=".$bot->getUserId ())], [Buttons::inlineKeyBoardCallbackData ("Ok, Thanks 👍", "/ok")] ]) ]); }); // match pattern $tlg->commandMatch ('/^\/ok$/', function ($bot){ Methods::answerCallbackQuery ([ 'callback_query_id' => $bot->getCallbackQueryId (), 'text' => '💪 Bro' ]); }); // commandDefault aways in the end of code! $tlg->commandDefault (function ($bot){ Methods::sendMessage ([ 'chat_id' => $bot->getChatId (), 'text' => 'Chose a command /start, /info with id, name or username' ]); });
🔒 Segurança
O Telegram oferece algumas formas de validar se o request recebido veio realmente de seus servidores (mais aqui), você pode definir um secret_token
no seu Webhook, todas as requisições terá seu token secreto no header X-Telegram-Bot-Api-Secret-Token, usando esse pacote você também pode validar o seu secret_token
.
$secret_token = 'wubbalubbadub_dub'; // set secret_token in webhook // Methods::setWebhook ([ // 'url' => 'https://url.com/mybot/', // 'secret_token' => $secret_token // ]); // my secret token $tlg->setSecretToken ($secret_token); if ($tlg->checkSecretToken () == false){ http_response_code (401); }
Respondendo comandos
Use os métodos command ()
, commandMatch ()
ou commandDefault
para capturar comandos enviados ao bot, uma funcão de callback ou um método de uma classe será executado para esse comando.
command ()
- Para comandos padrão /comando ou qualquer string simples que você considera um comando, um '👍' por exemplo! Usando{{param}}
você pode nomear parâmetros que espera receber no comando.
$tlg->command ('👍', function ($bot){ // process command... }); $tlg->command ('/colors {{color_1}} {{color_2}} {{color_3}}', function ($bot, $data){ // $data ['color_1']... // process command... }); // run the colors method of ClassBot class // $tlg->command ('/colors {{color_1}} {{color_2}} {{color_3}}', 'ClassBot:methodColors'); // for namespace use '\MyNamespace\ClassBot:colors' // $tlg->command ('/colors {{color_1}} {{color_2}} {{color_3}}', '\MyNamespace\ClassBot:colors');
commandMatch ()
- Para comandos que seguem um padrão diferente, comandos que casam com uma expresão regular expecifica, urls do telegram por exemplo!
// telegram urls https://t.me/botfather, https://t.me/TelegramBR $tlg->commandMatch ('/^https?:\/\/t\.me\/\w{5,}$/', function ($bot, $data){ // $data [0] // process command... }); // run the executeLinks method of TelegramBot class // $tlg->commandMatch ('/^https?:\/\/t\.me\/\w{5,}$/', 'TelegramBot:executeLinks'); // for namespace use '\MyNamespace\ClassBot:colors' // $tlg->commandMatch ('/^https?:\/\/t\.me\/\w{5,}$/', '\MyNamespace\TelegramBot:executeLinks');
commandDefault ()
- Comando executado por padrão quando não existe nehuma correspondência com command ou commandMatch.
// ...command // ...commandMatch // in the end of code! $tlg->commandDefault (function ($bot){ // send default message }); // $tlg->commandDefault ('ControllerBot:default');
Alguns dos métodos disponíveis:
getText ()
, getUpdateType ()
, getContent ()
, getUserId ()
, getUsername ()
, getFirstName ()
, getLastName ()
, getFullName ()
- Nome completo do usuário; getLanguageCode ()
- ID de idioma do usuário; getMessageId ()
, getChatId ()
, getMediaType ()
- Tipo de mídia, photo, animation, audio, document, sticker, story, video, video_note, voice, contact, dice, game, poll, venue, location, invoice; getCallbackQueryId ()
, getChatType ()
- Tipo de chat, private, group, supergroup, channel; saveFile ()
- Download de um arquivo, recebe como parâmetro o retorno do método getFile ()
e o destino do arquivo; setSecretToken ()
- Define um token de segurança usado em requisições Webhook(secret_token); checkSecretToken ()
- Verifica secret_token definido com secret token da requisição.
Métodos e Botões:
Como já viu em exemplos acima ☝ na classe estática Methods
estão disponíveis todos os métodos da api do Telegram, lista completa aqui, temos outra classe estática Buttons
para criação de botões inline(embutido na mensagem) e botões de teclado.
Methods::sendMessage ([ 'chat_id' => $bot->getUserId (), 'text' => '(☞゚ヮ゚)☞', 'reply_markup' => Buttons::inlineKeyBoard ([ [Buttons::inlineKeyBoardCallbackData ('Hello', '/hello')], // [Buttons::inlineKeyBoardUrl ('Open Link', 'https://google.com')] ]) ]);
inlineKeyBoardUrl ()
, inlineKeyBoardCallbackData ()
, inlineKeyBoardWebApp ()
, inlineKeyBoardLoginUrl ()
, inlineKeyBoardSwitchInlineQuery ()
,inlineKeyBoardSwitchInlineQueryCurrentChat ()
, inlineKeyBoardPay ()
Methods::sendMessage ([ 'chat_id' => $bot->getUserId (), 'text' => 'Hello 👋', 'reply_markup' => Buttons::replyKeyBoardMarkup ([ [Buttons::keyBoardButtonText ('Hello')], // [Buttons::keyBoardButtonRequestContact ('share your contact')] ]) ]);
keyBoardButtonText ()
, keyBoardButtonRequestContact ()
, keyBoardButtonRequestLocation ()
, keyBoardButtonRequestPoll ()
, keyBoardButtonWebApp ()
Methods::sendMessage ([ 'chat_id' => $bot->getChatId (), 'text' => '😍🤔👌🔥🤦', 'reply_markup' => Buttons::forceReply () ]);
-
forceReply ()
- Força uma resposta da mensagem, documentação -
replyKeyboardRemove ()
- Remove o teclado personalizado e mostra o teclado padrão do dispositivo, documentação
Reação a mensagens
Bots podem reagir às mensagens por emojis personalizados ou emojis simples como 👍, 👌, 🔥, 😍...
Você pode ver lista completa de reações disponíveis aqui
Temos uma classe estática Reaction
para reagir a mensagens.
Methods::setMessageReaction ([ 'chat_id' => $bot->getChatId (), 'message_id' => $bot->getMessageId (), 'reaction' => Reaction::reactionType ([ Reaction::reactionTypeEmoji ('❤'), ]) ]);
Methods::setMessageReaction ([ 'chat_id' => $bot->getChatId (), 'message_id' => $bot->getMessageId (), 'reaction' => Reaction::reactionType ([ Reaction::reactionTypeCustomEmoji ('5445284980978621387'), ]) ]);
Enviando arquivos:
- Enviando audio
Methods::sendAudio ([ 'chat_id' => $bot->getChatId (), 'audio' => curl_file_create (__DIR__.'/music.mp3'), 'caption' => 'Description music' ]);
- Enviando foto
Methods::sendPhoto ([ 'chat_id' => $bot->getChatId (), 'photo' => curl_file_create (__DIR__.'/photo.jpg'), 'caption' => 'Description photo' ]);
- Enviando vídeo
Methods::sendVideo ([ 'chat_id' => $bot->getChatId (), 'video' => curl_file_create (__DIR__.'/video.mp4'), 'caption' => 'Description video' ]);
- Enviando arquivo
Methods::sendDocument ([ 'chat_id' => $bot->getChatId (), 'document' => curl_file_create (__DIR__.'/application.apk'), 'caption' => 'Description file' ]);
Download de arquivos
$file = Methods::getFile ([ 'file_id' => 'CQACAgEAAxkBAAIBRGMFiJ_7zH2y9lJZxnn-XesvrBIhAALrAgACBcf5R68w-Z9ZMsgUKQQ' ]); var_dump ($bot->saveFile ($file, __DIR__.'/music.mp3'));
Logs
Você pode obter logs de interação com o bot, basta usar a classe estática \TelegramPhp\Config\Logs
, por ela você pode definir uma ou mais classes que irão receber e processar os dados de interação do usuário.
- Classe responsável por processar os logs.
class LogCommands { // method log is required public function log ($telegramPhp, $action, $route, $data){ // process data } }
- Definindo a classe que irá processar os logs.
\TelegramPhp\Config\Logs::catchLogs ([ LogCommands::class, // LogStatistics::class ]);
Tipo de Update
É possível executar uma função/método para um tipo de Update expecífico enviado pelo Telegram, por exemplo você pode executar uma função que responda a updates do tipo 'my_chat_member' ou 'chat_member'.
- Processando updates 'my_chat_member'
$tlg->on ('my_chat_member', function ($bot){ // code here }); // $tlg->on (['message_reaction', 'message'], function ($bot){ // code here // });
- Processando updates 'chat_member'
$tlg->on ('chat_member', 'TelegramBot:myChatMember');
🔥 Envie os bots feitos com esse pacote, ele pode ser listado aqui!
• J.M
- @scdownbot (+18K Usuários)
- @twitterdlrobot (+11K Usuários)
- @rastreiorobot (+14K Usuários)
- @btn_bot (+200 Usuários)