NAME

Bot::ChatBots::Telegram::LongPoll - Telegram updates receiver, long-poll

SYNOPSIS

   use Bot::ChatBots::Telegram::LongPoll;
   my $lp = Bot::ChatBots::Telegram::LongPoll->new(
      token     => $ENV{TOKEN},
      processor => \&processor,
      start     => 1,
   );
   sub processor { # tube-compliant
      my $record = shift;
      # ... $record is normalized, by default
      # quick response:
      $record->{send_response} = 'Hello, world!';
      return $record; # follow on..
   }

DESCRIPTION

This is an updates receiver and dispatcher for the Telegram infrastructure. It connects to Telegram's API for long-poll style (i.e. pulling updates continuously), so it's somehow inefficient but should let you get started in all conditions in which you can at least browse the Internet (webhook require that your endpoint lives in a routable place).

At the base, you have to provide at least the "token" and the "processor". The former is needed to connect to Telegram and get updates, the latter is what will be invoked for each update that is received.

When you have an object, you have to "start" to get the ball rolling. You can also pass start in the constructor, this will start the Mojo::IOLoop directly (so you can use it in case you don't have other stuff to do).

When invoked, the "processor" tube can return a record with the response field set. In this case, this update receiver can act also on the other way around, and send the response towards Telegram using a Bot::ChatBots::Telegram::Sender.

ACCESSORS

This class consumes roles Bot::ChatBots::Telegram::Role::Source and Bot::ChatBots::Role::Source and all its accessors.

connect_timeout

   my $to = $obj->connect_timeout;
   $obj->connect_timeout(10);

Acccessor for the connection timeout for Bot::ChatBots::Telegram::Sender's user agent (this is Mojo::UserAgent).

interval

   $secs = $obj->interval;
   $obj->interval(0.2); # secs

Accessor for the interval of scheduling calls to getUpdates. You can set this to a pretty low value (default is 0.1 seconds) because there is a flag that prevents calls from being sent if another one is ongoing.

max_redirects

   my $n = $obj->max_redirects;
   $obj->max_redirects(7); # default is 5

Accessors for maximum number of redirects acceptable for the underlying Mojo::UserAgent. Defaults to 5.

sender

   my $sender = $obj->sender;
   $obj->sender(Bot::ChatBots::Telegram::Sender->new(token => $token));

Accessor for the Bot::ChatBots::Telegram::Sender object used for managing communications from/to Telegram.

update_timeout

   my $to = $obj->update_timeout;
   $obj->update_timeout(30);

Accessor to set/get the update_timeout set in the getUpdates call to the Telegram API. Defaults to 300 seconds, i.e. you should get at least one update every 5 minutes.

METHODS

This class consumes roles Bot::ChatBots::Telegram::Role::Source and Bot::ChatBots::Role::Source and all its methods.

BUILD

Method called upon construction. It checks for the presence of a start parameter set to true and in case calls "start".

class_custom_pairs

   my @pairs = $obj->class_custom_pairs;

Returns custom pairs, used by role Bot::ChatBots::Role::Source. It adds a token to the parameters put in the source key inside the record passed to the process method, when invoked.

parse_response

   my @updates = $obj->parse_response($res, $threshold_id);

Parse the response to the polling request ($res is a Mojo::Message::Result object) and filters all updates whose identifier (according to field update_id) are greater than, or equal to, the $threshold_id. It takes care to check the return values and the rest.

poller

   my $subref = $obj->poller(%args);
      $subref = $obj->poller(\%args);

Build a polling sub reference suitable for being installed as a repetitive task in "start". This poller sends one single request to the Telegram endpoint for the longpoll and processes one single response.

In particular, it extracts the list of updates from the response and calls "process_updates" in Bot::ChatBots::Role::Source on them.

The source key in the record that is eventually generated contains:

• refs with sender, tx and ua

• an additional item in source that is a hash reference associated to the key query. Inside this you can find a key offset that you can use to increase the offset to be used in following calls. This is done automatically in "process".

process

   my $retval = $self->process($record);

Wrapper around "process" in Bot::ChatBots::Role::Source to cope with the need to increase the offset for each incoming update (see "poller" for additional details).

start

   $obj->start(%args); # OR
   $obj->start(\%args);

Start polling Telegram for new updates. "poller" is called to retrieve a sub reference that is then installed as a recurring job according to "interval".

This method is called automatically upon object construction if option start is present and set to a true value.

SEE ALSO

Bot::ChatBots, Bot::ChatBots::Telegram::WebHooks.

AUTHOR

Flavio Poletti <polettix@cpan.org>

COPYRIGHT AND LICENSE

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.

cpanm Bot::ChatBots::Telegram

perl -MCPAN -e shell
install Bot::ChatBots::Telegram