NAME

WWW::Telegram::BotAPI - Perl implementation of the Telegram Bot API

SYNOPSIS

    use WWW::Telegram::BotAPI;
    my $api = WWW::Telegram::BotAPI->new (
        token => 'my_token'
    );
    # The API methods die when an error occurs.
    say $api->getMe->{result}{username};
    # Uploading files is easier than ever.
    $api->sendPhoto ({
        chat_id => 123456,
        photo   => {
            file => "/home/me/cool_pic.png"
        },
        caption => "Look at my cool photo!"
    });
    # Asynchronous request support with Mojo::UserAgent.
    $api = WWW::Telegram::BotAPI->new (
        token => 'my_token',
        async => 1
    );
    $api->sendMessage ({
        chat_id => 123456,
        text    => 'Hello world!'
    }, sub {
        my ($ua, $tx) = @_;
        die "Something bad happened!" unless $tx->success;
        say $tx->res->json->{ok} ? "YAY!" : ":(";
    });
    Mojo::IOLoop->start;

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.

METHODS

WWW::Telegram::BotAPI implements the following methods.

new

    my $api = WWW::Telegram::BotAPI->new (%options);

Creates a new WWW::Telegram::BotAPI instance.

%options may contain the following:

• token => 'my_token'

  The token that will be used to authenticate the bot.

  This is required! The method will croak if this option is not specified.

• api_url => 'https://api.example.com/token/%s/method/%s'

  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.

  Defaults to https://api.telegram.org/bot%s/%s.

• async => 1

  Enables asynchronous requests.

  This requires Mojo::UserAgent, and the method will croak if it isn't found.

  NOTE: all requests will be asynchronous when this option is enabled, and if a method is called without a callback then it will croak.

• force_lwp => 1

  Forces the usage of LWP::UserAgent instead of Mojo::UserAgent, even if the latter is available.

  By default, the module tries to load Mojo::UserAgent, and on failure it uses LWP::UserAgent.

AUTOLOAD

    $api->getMe;
    $api->whatever;

This module makes use of "Autoloading" in perlsub. This means that every current and future method of the Telegram Bot API can be used by calling its Perl equivalent, without requiring an update of the module.

If you'd like to avoid using AUTOLOAD, then you may simply call the "api_request" method specifying the method name as the first argument.

    $api->api_request ('getMe');

This is, by the way, the exact thing the AUTOLOAD method of this module does.

api_request

    $api->api_request ('getMe');
    $api->api_request ('sendMessage', {
        chat_id => 123456,
        text    => 'Oh, hai'
    });
    # file upload
    $api->api_request ('sendDocument', {
        chat_id  => 123456,
        document => {
            filename => 'dump.txt',
            content  => 'secret stuff'
        }
    });
    # with async => 1, and the IOLoop already started
    $api->api_request ('getMe', sub {
        my ($ua, $tx) = @_;
        die unless $tx->success;
        # ...
    });

This method performs an API request. The first argument must be the method name (here's a list).

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.

Parameters can be specified using an hash reference.

File uploads are specified using an hash reference containing the following mappings:

• file => '/path/to/file.ext'

  Path to the file you want to upload.

  Required only if content is not specified.

• filename => 'file_name.ext'

  An optional filename that will be used instead of the real name of the file.

  Particularly recommended when content is specified.

• content => 'Being a file is cool :-)'

  The content of the file to send. When this is used, file must not be specified.

• AnyCustom => 'Header'

  Custom headers can be specified as hash mappings.

Upload of multiple files is not supported. See "tx" in Mojo::UserAgent::Transactor for more information about file uploads.

When asynchronous requests are enabled, a callback has to 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.

NOTE: 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.

The order of the arguments, except of the first one, does not matter:

    $api->api_request ('sendMessage', $parameters, $callback);
    $api->api_request ('sendMessage', $callback, $parameters); # same thing!

agent

    my $user_agent = $api->agent;

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 isa:

    my $is_lwp = $user_agent->isa ('LWP::UserAgent');

CAVEATS

No error handling is performed when using asynchronous requests.

If the response is not a valid JSON string, undef is returned.

SEE ALSO

LWP::UserAgent, Mojo::UserAgent, https://core.telegram.org/bots/api, https://core.telegram.org/bots

AUTHOR

Roberto Frenna (robertof AT cpan DOT org)

BUGS

Please report any bugs or feature requests to https://github.com/Robertof/perl-www-telegram-botapi.

THANKS

Thanks to the authors of Mojolicious for inspiration about the license and the documentation.

LICENSE

Copyright (C) 2015, Roberto Frenna.

This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.

cpanm WWW::Telegram::BotAPI

perl -MCPAN -e shell
install WWW::Telegram::BotAPI