The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Bot-ChatBots-Telegram-0.008
River stage zero No dependents
3 ++
/ Bot::ChatBots::Telegram::WebHook

NAME

Bot::ChatBots::Telegram::WebHook - Telegram updates receiver, web hook

SYNOPSIS

   use Log::Any qw< $log >;
   use Log::Any::Adapter;
   use Mojolicious::Lite;
   Log::Any::Adapter->set('Stderr');
   plugin 'Bot::ChatBots::Telegram' => sources => [
      [
         '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;
   }

DESCRIPTION

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).

ACCESSORS

This class consumes the following roles, inheriting their accessors:

Additionally, it provides the following ones:

auto_register

   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.

auto_unregister

   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.

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.

METHODS

This class consumes the following roles, inheriting their methods:

The following sections describe the addiitonal ones.

BUILD

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.

DEMOLISH

This method is called upon object destruction. It takes care to call "unregister" if "auto_unregister" is set to a true value.

parse_request

   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.

process

   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

  • $record->{source}{flags}{rendered} is false (i.e. the response hasn't been rendered yet).

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).

register

   $obj->register(%args);
   $obj->register(\%args);

Register the "url" (possibly derived from "path" if needed) as the webhook in Telegram.

This operation requires a valid token, which can be either passed as one of the %args or taken from the object ("token" in particular).

token

See "token" in Bot::ChatBots::Telegram::Base.

unregister

   $obj->unregister;

De-register webhook from Telegram (after which you can restart using long-polling, for example).

SEE ALSO

Bot::ChatBots, Bot::ChatBots::Role::WebHook.

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.