NAME

Bot::ChatBots::Telegram::Sender - Convenience class for sending Telegram calls

SYNOPSIS

   use Bot::ChatBots::Telegram::Sender;
   my $sender = Bot::ChatBots::Telegram::Sender->new(token => $ENV{TOKEN});

   $sender->send_message({text => 'hey', chat_id => $chat_id});

DESCRIPTION

This is a class wrapping WWW::Telegram::BotAPI for convenient usage within the Bot::ChatBots system.

The "send" method allows you to send a message. It provides a few DWIM features but it's basically a thin wrapper around "api_request" in WWW::Telegram::BotAPI, which you are encouraged to see.

ATTRIBUTES

This class composes Bot::ChatBots::Role::Sender and inherits all of its accessors.

start_loop

   say 'loop starts automatically' if $obj->start_loop;
   $obj->start_loop(0); # don't start automatically
   $obj->start_loop(1); # start loop automatically

Accessor for boolean attribute that instructs "send_message" to start the Mojo::IOLoop automatically. This can still be overridden by anything passed with key start_loop in "send_message".

Defaults to 0 (false).

telegram

   my $telegram = $obj->telegram;
   $obj->token(WWW::Telegram::BotAPI->new(...));

Accessor for the WWW::Telegram::BotAPI object, if you want to use it or set a new one.

By default, when needed one is instantiated lazily based on the available token (/async set to 1). This lazy initialization also takes care to start Mojo::IOLoop if it's not already running and subject to "start_loop".

token

   my $token = $obj->token;
   $obj->token($new_token);

Accessor for the Telegram token.

METHODS

This class composes Bot::ChatBots::Role::Sender and inherits all of its methods.

may_start_loop

   $self->may_start_loop(%args);
   $self->may_start_loop(\%args);

Evaluates conditions for starting Mojo::IOLoop. These conditions are:

• if the provided %args contains a key start_loop, it is used to establish whether to start the loop or not, OTHERWISE

• if "start_loop" is false, the loop is not started, OTHERWISE

• the loop is started if it's not already running.

This method is used by "send_message".

send_message

   $obj->send_message($message); # OR
   $obj->send_message($message, %args);
   $obj->send_message($message, \%args);

Do actual sending of a message. This method leverages on "telegram" to do the actual network traffic.

A Telegram message is required to have the following structure:

   {
      chat_id => $id_of_recipient_chat,
      text => $your_message,
   }

If the input $message is a hash reference, the text part is supposed to be OK, otherwise the input $message is considered to be the text of the message.

As an extension, you can also pass the method to be called on the "telegram" object, in two ways:

• via option telegram_method, which assumes you will use the right method name;

• via option method, which supports some aliases. To date the only alias supported is send in lieu of sendMessage.

The argument %args supports the following keys:

callback

A sub reference to be used as a callback for a non-blocking call to the "telegram" client.

record

The input record, e.g. coming from a webhook, useful for getting the recipient of the message.

If the chat_id key in the incoming $message is missing, it is possibly auto-filled based on the following algorithm:

• if a $args{record} is provided, then the $args{record}{channel}{id} is taken from it;

• otherwise, if the "has_recipient" in Bot::ChatBots::Role::Sender method returns a true value, then "recipient" in Bot::ChatBots::Role::Sender is used;

• otherwise an exception is thrown (Ouch with code 500).

start_loop

Boolean value to signal if you want the Mojo::IOLoop to be started automatically (otherwise "start_loop" in Bot::ChatBots::Role::Sender is used).

SEE ALSO

Bot::ChatBots, Bot::ChatBots::Telegram::LongPoll. 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