Bot::ChatBots::Telegram::WebHook - Telegram updates receiver, web hook
use Log::Any qw< $log >; use Log::Any::Adapter; use Mojolicious::Lite; Log::Any::Adapter->set('Stderr'); plugin 'Bot::ChatBots::Telegram' => instances => [ [ 'WebHook', processor => \&processor, register => 1, token => $ENV{TOKEN}, unregister => 0, url => 'https://example.com:8443/mybot', ], # more can follow here... ]; app->start; sub processor { my $record = shift; # do whatever you want with $record, e.g. set a quick response $record->{response} = 'your thoughs are important for us!'; return $record; }
This is an updates receiver and dispatcher for the Telegram infrastructure. It connects to Telegram's API for webhooks style (i.e. waiting for push messages to arrive), so you need a routable address/port to get the ball rolling.
Strictly speaking, you MUST only provide a "processor" and either "url" or "path". The latter is used to set a POST route, while the former is what is called whenever a new message arrives through that route.
Most probably you will also want to automatically register your webhook at Telegram. In this case, you MUST also provide a "token". You can also set automatic registration (and unregistration) when creating the object.
When invoked, the "processor" tube can return a record with the response field set. In this case, this response is passed back as the answer to the call from the Telegram server (although Telegram documents correctly point out that you don't get any feedback about how successful this can be).
response
This class consumes the following roles, inheriting their accessors:
Bot::ChatBots::Telegram::Role::Source
Bot::ChatBots::Role::WebHook
Additionally, it provides the following ones:
my $boolean = $obj->auto_register;
get the value of the automatic registration flag, which can be set upon construction via option register. When set, the "register" method will be called automatically upon construction.
register
NOTE: this parameters is initialized via the register option in the constructor "new".
my $boolean = $obj->auto_unregister;
get the value of the automatic unregistration flag, which can be set upon construction via option unregister. When set, the "unregister" method will be called automatically upon destruction.
unregister
Note that some PaaS environment (notably Dokku) might keep the "old" instance around while the new one is already up and running. In this case, it is suggested to keep this boolean value to its default false value and avoid unwanted unregistrations.
NOTE: this parameters is initialized via the unregister option in the constructor "new".
$obj->certificate($certificate); my $current = $obj->certificate;
Set/get the currently installed certificate.
It can be either a string or a hash with the key certificate pointing to that string, see WWW::Telegram::BotAPI for additional details, or Telegram's documentation. Arguably, as of release 0.09 of WWW::Telegram::BotAPI you will need to either upload your certificate beforehand and use an identifier here, or provide an URL for letting Telegram download it.
certificate
This class consumes the following roles, inheriting their methods:
The following sections describe the addiitonal ones.
This method is called upon object construction. It takes care to call "install_route" from Bot::ChatBots::Role::WebHook so that you don't have to. Additionally, if "auto_register" is true, "register" is called automatically.
This method is called upon object destruction. It takes care to call "unregister" if "auto_unregister" is set to a true value.
my $obj = Bot::ChatBots::Telegram::WebHook->new(%args); # mostly used in Mojolicious applications plugin 'Bot::ChatBots::Telegram' => instances => [ [ 'WebHook', %args ] ];
Create a new instance. Mostly used behind the scenes by Bot::ChatBots::MojoPlugin as in the second example above.
The arguments hash %hash supports the following keys:
%hash
***
all keys from Bot::ChatBots::Telegram::Role::Source and Bot::ChatBots::Role::WebHook
in case a privately generated certificate has to be used, it can be set here or passed to the "register" method. You don't need to set this if your certificate is publicly available and trusted (i.e. released by a recognised Certification Authority).
if true, "register" is called upon construction, without parameters.
if true, "unregister" is called upon destruction. Beware of setting this automation though, especially if your bot is installed through a platform as a service like Dokku, because this might interphere with your upgrade process.
my @updates = $obj->parse_request($req);
Parse the request and extract updates from it. The current Telegram WebHook API sends one single update per message. Returns the update.
my $outcome = $obj->process($record);
Process a record. The main workhorse is inherited from Bot::ChatBots::Role::WebHook, although this wraps around it to add automatic sending of a response in case:
$outcome is a hash reference with a response key inside, AND
$outcome
$record->{source}{flags}{rendered} is false (i.e. the response hasn't been rendered yet).
$record->{source}{flags}{rendered}
When a response is rendered, $record->{source}{flags}{rendered} is set to 1 (a true value) to signal that rendering already happened (this should prevent the calling function from doing the rendering again).
1
$obj->register(%args); $obj->register(\%args);
Register the url (possibly derived from path if needed) as the webhook in Telegram. Note that both url and path are inherited methods; you can override them in %args. Same goes for token.
url
path
%args
token
If you plan to use an auto-generated certificate, you will need to provide it either setting "certificate" (possibly upon construction in "new") or via a parameter in %args.
Supported keys in %args, all overriding values in the object when applicable:
app
application object (defaults to value from inherited method app)
certificate in case it is auto-generated, defaults to value from object (see "certificate" and "new").
controller
controller object (defaults to value from inherited method app)
path value or object (defaults to value from inherited method app). Used in case parameter url below is not present or possibly derived from the object's url method;
token value (defaults to value from inherited method app)
webhook target URL value or object (defaults to value from inherited method app)
See "token" in Bot::ChatBots::Telegram::Base.
$obj->unregister;
De-register webhook from Telegram (after which you can restart using long-polling, for example).
Bot::ChatBots, Bot::ChatBots::Role::WebHook.
Flavio Poletti <polettix@cpan.org>
Copyright (C) 2016, 2018 by Flavio Poletti <polettix@cpan.org>
This module is free software. You can redistribute it and/or modify it under the terms of the Artistic License 2.0.
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.
To install Bot::ChatBots::Telegram, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Bot::ChatBots::Telegram
CPAN shell
perl -MCPAN -e shell install Bot::ChatBots::Telegram
For more information on module installation, please visit the detailed CPAN module installation guide.