telegram_bot_api

Erlang library for Telegram Bot API.
It contains all methods and types available in Telegram Bot API 9.5, released March 1, 2026.

Installation

The package can be installed by adding telegram_bot_api to your list of dependencies in rebar.config:

{deps, [telegram_bot_api]}.

Basic usage

%%Use this token issued @BotFather
Token = <<"1111111111:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx">>,
%%After creating an HTTP pool, you can use any methods available in the Telegram API. 
Pool=mybot_pool,  
{ok, Pid} = telegram_bot_api_sup:start_pool(#{name=>Pool,token=>Token,workers=>1}),

%%Once the pool is created, you can call any methods as they are named in the Telegram documentation: telegram_bot_api:'Method'
%%The names of the methods from the Telegram documentation and the telegram_bot_api module are the same.
%%The first parameter is the pool, the second is the request parameters sent to Telegram, the third indicates asynchrony, and the fourth parameter is the call timeout.
%%See https://hexdocs.pm/telegram_bot_api/telegram_bot_api.html. 

%%Example send message
ChatId=<<"@channelusername">>,% or number
Params=#{chat_id=>ChatId,...},
Async=false,%*if you install Async=true, the query result will be sent to the process mailbox message: {async,Ref,{ok,HttpCode,MapJson}} or {async, Ref, saved_to_file}(use in telegram_bot_api_file:download) or {error, Reason}
Timeout=5000,%*default timeout for gen_server:call

Result=telegram_bot_api:'Method'(Pool,Params,Async,Timeout),
case Result of
    {ok, Ref}->ok;%is Async=true
    {ok, HttpCode, MapJson}->ok; %is Async=false
    {error, Er}->error;
    {Error, Reason}->error
end.

Long polling

{ok, Pid} = telegram_bot_api_sup:start_update(#{
    name=>BotName,
    update_time=>1000,
    offset=>0,
    limit=>100,
    event=>{global,my_event},% or pid. new messages will be sent to this process.
    allowed_updates=>[message]
}).

Webhook

{ok,WebhookPid}=telegram_bot_api_sup:start_webhook(#{
    secret_token=><<"my_secret">>,%this is the secret_token that is set in the Parameter method setWebhook https://core.telegram.org/bots/api#setwebhook
    bots=>#{
    %% add 1 bot
    atom_to_binary(BotName)=>#{
    event=>{global,my_event},% the message will come here
    name=>BotName 
    }
    %%.. other bot
    },
    transport_opts=>#{
        ip=>{0,0,0,0},
        port=>8443,
        %% Optional parameter
        certfile=>"/etc/telegram_bot_api/ssl/YOURPUBLIC.pem",
        keyfile=>"/etc/telegram_bot_api/ssl/YOURPRIVATE.key",
        verify=> verify_none,
        %versions=> ['tlsv1.2'],
        %fail_if_no_peer_cert=>false,
        %log_level=>none,
        %next_protocols_advertised=> [<<"http/1.1">>],
        %alpn_preferred_protocols=> [<<"http/1.1">>]
    },
    %% Optional parameter
    %protocol_opts=>#{
    %    alpn_default_protocol =>http
	%}
    %% see parameter https://hexdocs.pm/telegram_bot_api/telegram_bot_api_sup.html#start_webhook/1
}).

Webhook dynamic add bot

%%add
ok= telegram_bot_api_webhook_server:add_bot(
    {global,WebhookServer},%|| WebhookPid
    <<"mybot_pool">>,
    #{
        event=>{global,BotEvent1},
        name=>mybot_pool
    }
),
%%delete
    telegram_bot_api_webhook_server:delete_bot({global,WebhookServer},mybot_pool).

Set webhook

telegram_bot_api:setWebhook(BotName1,#{
		url=>telegram_bot_api_webhook_server:make_url(<<"8.8.8.8">>, <<"8443">>, <<"mybot_pool">>),% make url: https://8.8.8.8:8443/telegram/mybot_pool/update
		ip_address=><<"8.8.8.8">>,
		certificate=>#{
                 file=><<"/etc/telegram_bot_api/ssl/YOURPUBLIC.pem">>,
                 name=><<"YOURPUBLIC.pem">>
                },
		secret_token=><<"my_secret">>% this token will be checked inside the handler cowboy, must match start_webhook
	}).

Send message

{ok,200,Result} = telegram_bot_api:sendMessage(Pool,#{
        chat_id=>ChatId,
        text=><<"Text">>
        }
        ).

Async send message

{ok,Ref} = telegram_bot_api:sendMessage(Pool,#{
        chat_id=>ChatId,
        text=><<"Text">>
        },
        true).

Get me

 {ok,200,Result} = telegram_bot_api:getMe(BotName,#{}).

Log out

{ok,200,#{ok := true,result := true}} = telegram_bot_api:logOut(BotName,#{}).

Set bot name

telegram_bot_api:setMyName(BotName,#{name=><<"Бот">>,language_code=>ru}).

Set bot photo

telegram_bot_api:setMyProfilePhoto(BotName,#{
                                    photo=>
                                            #{
                                            type=><<"static">>,
                                            photo=><<"attach://myfile">>
                                        },
                                        myfile=>#{
                                            file=><<"/etc/telegram_bot_api/file.jpg">>,
                                             name=><<"file.jpg">>
                                           }
                                        }).

Set bot commands

telegram_bot_api:setMyCommands(BotName,#{
    commands=>[
        #{
        command=><<"/test">>,
        description=><<"Test>>
        }]
    }).

Send contact

telegram_bot_api:sendContact(BotName,#{
         chat_id=>ChatId,
         phone_number=><<"+79281111111">>,
         first_name=><<"CONTACT">>
        })

Send photo

telegram_bot_api:sendPhoto(Pool,#{
        chat_id=><<"@channelusername">>,
        photo=>#{file=><<"/dir/file.jpg">>,name=><<"file.jpg">>}
        }).

Send audio

telegram_bot_api:sendAudio(BotName,#{
        chat_id=>ChatId,
        audio =>#{file=><<"/dir/file.mp3">>,name=><<"file.mp3">>}
        }).

Set message reaction

-include_lib("telegram_bot_api/include/message_reaction.hrl"). 
telegram_bot_api:setMessageReaction(BotName,#{
        chat_id=>ChatId,
        message_id=>MessageId,
        reaction=>[
        #{
            type=>?REACTION_TYPE_EMOJI,% or telegram_bot_api_emoji:random_reaction()
            emoji=>Reaction1
        }
    ]},Async),

Send message effect

-include_lib("telegram_bot_api/include/message_effect.hrl").
   telegram_bot_api:sendMessage(BotName,#{
        chat_id=>ChatId,
        text=><<"text">>,
        message_effect_id=>?MESSAGE_EFFECT_FIRE
    }).

Edit message text

telegram_bot_api:editMessageText(BotName,#{
        chat_id=>ChatId,
        text=><<"text">>,
        message_id=>MessageId
}).

Edit message caption

telegram_bot_api:editMessageText(BotName,#{
        chat_id=>ChatId,
        message_id=>MessageId,
        parse_mode =><<"HTML">>,
        caption=><<"<a href=\"tg://user?id=123\">User</a><code>123</code>">>
}).

Delete message

telegram_bot_api:deleteMessage(BotName,#{
        chat_id=>ChatId,
        message_id=>MessageId
}).

Inline keyboard

telegram_bot_api:sendMessage(BotName,#{
         chat_id=>ChatId,
         text=><<"inline_keyboard">>,
         reply_markup=>
                 #{
                 inline_keyboard=>
                 [
                         [
                         #{
                             text=><<"yes">>,
                             callback_data=><<"callback_yes">>
                         },
                         #{
                             text=><<"no">>,
                             callback_data=><<"callback_no">>
                         }
                         ]
                 ]
             }
    }).

Inline keyboard style button

telegram_bot_api:sendMessage(BotName,#{
        chat_id=>ChatId,
        text=><<"inline_keyboard_style">>,
        reply_markup=>
                #{
                inline_keyboard=>
                [
                [
                #{
                    text=><<"red">>,
                    style=><<"danger">>,
                    callback_data=><<"callback_red">>
                },
                #{
                    text=><<"green">>,
                    style=><<"success">>,
                    callback_data=><<"callback_green">>
                },
                #{
                    text=><<"blue">>,
                    style=><<"primary">>,
                    callback_data=><<"callback_blue">>
                },
                #{
                text=><<"default">>,
                callback_data=><<"callback_default">>
                }
                ]
                ]
            }
        }).

Answer callback query

telegram_bot_api:answerCallbackQuery(BotName,#{
    callback_query_id=>Id
    }).

Edit message reply markup

telegram_bot_api:editMessageReplyMarkup(BotName,#{
                message_id=>MessageId,
                chat_id=>ChatId,
                reply_markup=>
                    #{
                    inline_keyboard=>
                    [
                            [
                            #{
                                text=><<"ok">>,
                                callback_data=><<"callback_ok">>
                            }
                            ]
                    ]
                }
                }).

Send chat action

-include_lib("telegram_bot_api/include/chat_action.hrl").
    telegram_bot_api:sendChatAction(BotName,#{
        chat_id=>ChatId,
        action=>?CHAT_ACTION_UPLOAD_PHOTO
    }).

Send dice

-include_lib("telegram_bot_api/include/message_dice.hrl").
    Result=telegram_bot_api:sendDice(BotName,#{
             chat_id=>ChatId,
             emoji=>?DICE_BOWLING,% or telegram_bot_api_emoji:random_dice()
             protect_content=>true
     }).
     %%
     %%{ok,200,#{ok := true,result :=#{ message_id := MessageId,  chat:=#{id:=ChatId}, dice :=#{value :=Value emoji:= Emoji}  } }}=Result,
     %%IsWin=telegram_bot_api_emoji:is_win_dice(Emoji,Value). % true or false

Send message draft

telegram_bot_api:sendMessageDraft(BotName,#{
         chat_id=>ChatId, 
         draft_id=>DrafId,
         text=>Text,
         message_thread_id=>ThreadId
     })

Create forum topic

-include_lib("telegram_bot_api/include/message_topic.hrl").
   telegram_bot_api:createForumTopic(BotName,#{
        chat_id=>ChatId,
        name=><<"name topic">>,
        icon_color=>?TOPIC_ICON_COLOR_CREAMY
        icon_custom_emoji_id=>?TOPIC_EMOJI_NEWSPAPER_ID % or telegram_bot_api_emoji:random_topic()
    }).

Edit forum topic

telegram_bot_api:editForumTopic(BotName,#{
    chat_id=>ChatId,
    message_thread_id=>ThreadId,
    name=>Text
    }).

Restrict chat member

telegram_bot_api:getUserProfileAudios(BotName,#{
        chat_id=>ChatId,
        user_id =>UserId,
        until_date =>erlang:system_time(seconds)+(60*5), %mute the user for 5 minutes
        permissions=>#{
            can_send_messages => false,
            can_send_audios => false,
            can_send_documents => false,
            can_send_photos => false,
            can_send_videos => false,
            can_send_video_notes => false,
            can_send_voice_notes => false,
            can_send_polls => false,
            can_send_other_messages => false
    }
    }).

Get chat member

%%Get a user role in a group
case telegram_bot_api:getChatMember(BotName, #{
        chat_id=>ChatId,
        user_id=>UserId
        }) of
        {ok,200, #{ok := true, result := #{status := Status} } }->
          Status;%creator or administrator or member or restricted or left or kicked; see type ChatMember 
        _->false
        end.
        

Get user profile audios

telegram_bot_api:getUserProfileAudios(BotName,#{user_id=>1234}).

Set chat member tag

case telegram_bot_api:setChatMemberTag(BotName, #{
        chat_id=>ChatId,
        user_id=>UserId,
        tag=><<"tag">>
        }) of
        {ok,200,#{ok := true,result := true}}->ok;
        %If you can't install the tag, you'll get an error example {ok,400,#{ok => false,description => <<"Bad Request: CHAT_CREATOR_REQUIRED">>,error_code => 400}} ->error;
        _->error
        end.

Other

• all methods
• emoji
• example