.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "WWW::Telegram::BotAPI 3pm" .TH WWW::Telegram::BotAPI 3pm 2024-02-29 "perl v5.38.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME WWW::Telegram::BotAPI \- Perl implementation of the Telegram Bot API .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 10 \& use WWW::Telegram::BotAPI; \& my $api = WWW::Telegram::BotAPI\->new ( \& token => \*(Aqmy_token\*(Aq \& ); \& # The API methods die when an error occurs. \& say $api\->getMe\->{result}{username}; \& # ... but error handling is available as well. \& my $result = eval { $api\->getMe } \& or die \*(AqGot error message: \*(Aq, $api\->parse_error\->{msg}; \& # Uploading files is easier than ever. \& $api\->sendPhoto ({ \& chat_id => 123456, \& photo => { \& file => \*(Aq/home/me/cool_pic.png\*(Aq \& }, \& caption => \*(AqLook at my cool photo!\*(Aq \& }); \& # Complex objects are as easy as writing a Perl object. \& $api\->sendMessage ({ \& chat_id => 123456, \& # Object: ReplyKeyboardMarkup \& reply_markup => { \& resize_keyboard => \e1, # \e1 = true when JSONified, \e0 = false \& keyboard => [ \& # Keyboard: row 1 \& [ \& # Keyboard: button 1 \& \*(AqHello world!\*(Aq, \& # Keyboard: button 2 \& { \& text => \*(AqGive me your phone number!\*(Aq, \& request_contact => \e1 \& } \& ] \& ] \& } \& }); \& # Asynchronous request are supported with Mojo::UserAgent. \& $api = WWW::Telegram::BotAPI\->new ( \& token => \*(Aqmy_token\*(Aq, \& async => 1 # WARNING: may fail if Mojo::UserAgent is not available! \& ); \& $api\->sendMessage ({ \& chat_id => 123456, \& text => \*(AqHello world!\*(Aq \& }, sub { \& my ($ua, $tx) = @_; \& die \*(AqSomething bad happened!\*(Aq if $tx\->error; \& say $tx\->res\->json\->{ok} ? \*(AqYAY!\*(Aq : \*(Aq:(\*(Aq; # Not production ready! \& }); \& Mojo::IOLoop\->start; .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" This module provides an easy to use interface for the Telegram Bot API . It also supports async requests out of the box using Mojo::UserAgent, which makes this module easy to integrate with an existing Mojolicious application. .SH METHODS .IX Header "METHODS" WWW::Telegram::BotAPI implements the following methods. .SS new .IX Subsection "new" .Vb 1 \& my $api = WWW::Telegram::BotAPI\->new (%options); .Ve .PP Creates a new WWW::Telegram::BotAPI instance. .PP \&\fBWARNING:\fR you should only create one instance of this module and reuse it when needed. Calling \&\f(CW\*(C`new\*(C'\fR each time you run an async request causes unexpected behavior with Mojo::UserAgent and won't work correctly. See also issue #13 on GitHub . .PP \&\f(CW%options\fR may contain the following: .IP \(bu 4 \&\f(CW\*(C`token => \*(Aqmy_token\*(Aq\*(C'\fR .Sp The token that will be used to authenticate the bot. .Sp \&\fBThis is required! The method will croak if this option is not specified.\fR .IP \(bu 4 \&\f(CW\*(C`api_url => \*(Aqhttps://api.example.com/token/%s/method/%s\*(Aq\*(C'\fR .Sp A format string that will be used to create the final API URL. The first parameter specifies the token, the second one specifies the method. .Sp Defaults to \f(CW\*(C`https://api.telegram.org/bot%s/%s\*(C'\fR. .IP \(bu 4 \&\f(CW\*(C`async => 1\*(C'\fR .Sp Enables asynchronous requests. .Sp \&\fBThis requires Mojo::UserAgent, and the method will croak if it isn't found.\fR .Sp Defaults to \f(CW0\fR. .IP \(bu 4 \&\f(CW\*(C`force_lwp => 1\*(C'\fR .Sp Forces the usage of LWP::UserAgent instead of Mojo::UserAgent, even if the latter is available. .Sp By default, the module tries to load Mojo::UserAgent, and on failure it uses LWP::UserAgent. .SS AUTOLOAD .IX Subsection "AUTOLOAD" .Vb 11 \& $api\->getMe; \& $api\->sendMessage ({ \& chat_id => 123456, \& text => \*(AqHello world!\*(Aq \& }); \& # with async => 1 and the IOLoop already started \& $api\->setWebhook ({ url => \*(Aqhttps://example.com/webhook\*(Aq }, sub { \& my ($ua, $tx) = @_; \& die if $tx\->error; \& say \*(AqWebhook set!\*(Aq \& }); .Ve .PP This module makes use of "Autoloading" in perlsub. This means that \fBevery current and future method of the Telegram Bot API can be used by calling its Perl equivalent\fR, without requiring an update of the module. .PP If you'd like to avoid using \f(CW\*(C`AUTOLOAD\*(C'\fR, then you may simply call the "api_request" method specifying the method name as the first argument. .PP .Vb 1 \& $api\->api_request (\*(AqgetMe\*(Aq); .Ve .PP This is, by the way, the exact thing the \f(CW\*(C`AUTOLOAD\*(C'\fR method of this module does. .SS api_request .IX Subsection "api_request" .Vb 10 \& # Remember: each of these samples can be aliased with \& # $api\->methodName ($params). \& $api\->api_request (\*(AqgetMe\*(Aq); \& $api\->api_request (\*(AqsendMessage\*(Aq, { \& chat_id => 123456, \& text => \*(AqOh, hai\*(Aq \& }); \& # file upload \& $api\->api_request (\*(AqsendDocument\*(Aq, { \& chat_id => 123456, \& document => { \& filename => \*(Aqdump.txt\*(Aq, \& content => \*(Aqsecret stuff\*(Aq \& } \& }); \& # complex objects are supported natively since v0.04 \& $api\->api_request (\*(AqsendMessage\*(Aq, { \& chat_id => 123456, \& reply_markup => { \& keyboard => [ [ \*(AqButton 1\*(Aq, \*(AqButton 2\*(Aq ] ] \& } \& }); \& # with async => 1 and the IOLoop already started \& $api\->api_request (\*(AqgetMe\*(Aq, sub { \& my ($ua, $tx) = @_; \& die if $tx\->error; \& # ... \& }); .Ve .PP This method performs an API request. The first argument must be the method name (here's a list ). .PP Once the request is completed, the response is decoded using JSON::MaybeXS and then returned. If Mojo::UserAgent is used as the user-agent, then the response is decoded automatically using Mojo::JSON. .PP If the request is not successful or the server tells us something isn't \f(CW\*(C`ok\*(C'\fR, then this method dies with the first available error message (either the error description or the status line). You can make this method non-fatal using \f(CW\*(C`eval\*(C'\fR: .PP .Vb 2 \& my $response = eval { $api\->api_request ($method, $args) } \& or warn "Request failed with error \*(Aq$@\*(Aq, but I\*(Aqm still alive!"; .Ve .PP Further processing of error messages can be obtained using "parse_error". .PP Request parameters can be specified using an hash reference. Additionally, complex objects can be specified like you do in JSON. See the previous examples or the example bot provided in "SEE ALSO". .PP File uploads can be specified using an hash reference containing the following mappings: .IP \(bu 4 \&\f(CW\*(C`file => \*(Aq/path/to/file.ext\*(Aq\*(C'\fR .Sp Path to the file you want to upload. .Sp Required only if \f(CW\*(C`content\*(C'\fR is not specified. .IP \(bu 4 \&\f(CW\*(C`filename => \*(Aqfile_name.ext\*(Aq\*(C'\fR .Sp An optional filename that will be used instead of the real name of the file. .Sp Particularly recommended when \f(CW\*(C`content\*(C'\fR is specified. .IP \(bu 4 \&\f(CW\*(C`content => \*(AqBeing a file is cool :\-)\*(Aq\*(C'\fR .Sp The content of the file to send. When using this, \f(CW\*(C`file\*(C'\fR must not be specified. .IP \(bu 4 \&\f(CW\*(C`AnyCustom => \*(AqHeader\*(Aq\*(C'\fR .Sp Custom headers can be specified as hash mappings. .PP Upload of multiple files is not supported. See "tx" in Mojo::UserAgent::Transactor for more information about file uploads. .PP To resend files, you don't need to perform a file upload at all. Just pass the ID as a normal parameter. .PP .Vb 4 \& $api\->sendPhoto ({ \& chat_id => 123456, \& photo => $photo_id \& }); .Ve .PP When asynchronous requests are enabled, a callback can be specified as an argument. The arguments passed to the callback are, in order, the user-agent (a Mojo::UserAgent object) and the response (a Mojo::Transaction::HTTP object). More information can be found in the documentation of Mojo::UserAgent and Mojo::Transaction::HTTP. .PP \&\fBNOTE:\fR ensure that the event loop Mojo::IOLoop is started when using asynchronous requests. This is not needed when using this module inside a Mojolicious app. .PP The order of the arguments, except of the first one, does not matter: .PP .Vb 2 \& $api\->api_request (\*(AqsendMessage\*(Aq, $parameters, $callback); \& $api\->api_request (\*(AqsendMessage\*(Aq, $callback, $parameters); # same thing! .Ve .SS parse_error .IX Subsection "parse_error" .Vb 7 \& unless (eval { $api\->doSomething(...) }) { \& my $error = $api\->parse_error; \& die "Unknown error: $error\->{msg}" if $error\->{type} eq \*(Aqunknown\*(Aq; \& # Handle error gracefully using "type", "msg" and "code" (optional) \& } \& # Or, use it with a custom error message. \& my $error = $api\->parse_error ($message); .Ve .PP When sandboxing calls to WWW::Telegram::BotAPI methods using \f(CW\*(C`eval\*(C'\fR, it is useful to parse error messages using this method. .PP \&\fBWARNING:\fR up until version 0.09, this method incorrectly stopped at the first occurence of \f(CW\*(C`at\*(C'\fR in error messages, producing results such as \f(CW\*(C`missing ch\*(C'\fR instead of \f(CW\*(C`missing chat\*(C'\fR. .PP This method accepts an error message as its first argument, otherwise \f(CW$@\fR is used. .PP An hash reference containing the following elements is returned: .IP \(bu 4 \&\f(CW\*(C`type => unknown|agent|api\*(C'\fR .Sp The source of the error. .Sp \&\f(CW\*(C`api\*(C'\fR specifies an error originating from Telegram's BotAPI. When \f(CW\*(C`type\*(C'\fR is \f(CW\*(C`api\*(C'\fR, the key \&\f(CW\*(C`code\*(C'\fR is guaranteed to exist. .Sp \&\f(CW\*(C`agent\*(C'\fR specifies an error originating from this module's user-agent. This may indicate a network issue, a non\-200 HTTP response code or any error not related to the API. .Sp \&\f(CW\*(C`unknown\*(C'\fR specifies an error with no known source. .IP \(bu 4 \&\f(CW\*(C`msg => ...\*(C'\fR .Sp The error message. .IP \(bu 4 \&\f(CW\*(C`code => ...\*(C'\fR .Sp The error code. \fBThis key only exists when \fR\f(CB\*(C`type\*(C'\fR\fB is \fR\f(CB\*(C`api\*(C'\fR. .SS agent .IX Subsection "agent" .Vb 1 \& my $user_agent = $api\->agent; .Ve .PP Returns the instance of the user-agent used by the module. You can determine if the module is using LWP::UserAgent or Mojo::UserAgent by using \f(CW\*(C`isa\*(C'\fR: .PP .Vb 1 \& my $is_lwp = $user_agent\->isa (\*(AqLWP::UserAgent\*(Aq); .Ve .PP \fIUSING A PROXY\fR .IX Subsection "USING A PROXY" .PP Since all the painful networking stuff is delegated to one of the two supported user agents (either LWP::UserAgent or Mojo::UserAgent), you can use their built-in support for proxies by accessing the user agent object. An example of how this may look like is the following: .PP .Vb 12 \& my $user_agent = $api\->agent; \& if ($user_agent\->isa (\*(AqLWP::UserAgent\*(Aq)) { \& # Use LWP::Protocol::connect (for https) \& $user_agent\->proxy (\*(Aqhttps\*(Aq, \*(Aq...\*(Aq); \& # Or if you prefer, load proxy settings from the environment. \& # $user_agent\->env_proxy; \& } else { \& # Mojo::UserAgent (builtin) \& $user_agent\->proxy\->https (\*(Aq...\*(Aq); \& # Or if you prefer, load proxy settings from the environment. \& # $user_agent\->detect; \& } .Ve .PP \&\fBNOTE:\fR Unfortunately, Mojo::UserAgent returns an opaque \f(CW\*(C`Proxy connection failed\*(C'\fR when something goes wrong with the \f(CW\*(C`CONNECT\*(C'\fR request made to the proxy. To alleviate this, since version 0.12, this module prints the real reason of failure in debug mode. See "DEBUGGING". If you need to access the real error reason in your code, please see issue #29 on GitHub . .SH DEBUGGING .IX Header "DEBUGGING" To perform some cool troubleshooting, you can set the environment variable \f(CW\*(C`TELEGRAM_BOTAPI_DEBUG\*(C'\fR to a true value: .PP .Vb 1 \& TELEGRAM_BOTAPI_DEBUG=1 perl script.pl .Ve .PP This dumps the content of each request and response in a friendly, human-readable way. It also prints the version and the configuration of the module. As a security measure, the bot's token is automatically removed from the output of the dump. .PP Since version 0.12, enabling this flag also gives more details when a proxy connection fails. .PP \&\fBWARNING:\fR using this option along with an old Mojolicious version (< 6.22) leads to a warning, and forces LWP::UserAgent instead of Mojo::UserAgent. This is because Mojo::JSON used incompatible boolean values up to version 6.21, which led to an horrible death of JSON::MaybeXS when serializing the data. .SH CAVEATS .IX Header "CAVEATS" When asynchronous mode is enabled, no error handling is performed. You have to do it by yourself as shown in the "SYNOPSIS". .SH "SEE ALSO" .IX Header "SEE ALSO" LWP::UserAgent, Mojo::UserAgent, , , example implementation of a Telegram bot , example implementation of an async Telegram bot .SH AUTHOR .IX Header "AUTHOR" Roberto Frenna (robertof AT cpan DOT org) .SH BUGS .IX Header "BUGS" Please report any bugs or feature requests to . .SH THANKS .IX Header "THANKS" Thanks to the authors of Mojolicious for inspiration about the license and the documentation. .SH LICENSE .IX Header "LICENSE" Copyright (C) 2015, Roberto Frenna. .PP This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.