# telegram_bot_api
[](https://hex.pm/packages/telegram_bot_api)
[](https://core.telegram.org/bots/api#march-1-2026)
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`:
```erlang
{deps, [telegram_bot_api]}.
```
## Basic usage
``` erlang
%%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
``` erlang
{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
``` erlang
{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
``` erlang
%%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
``` erlang
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
``` erlang
{ok,200,Result} = telegram_bot_api:sendMessage(Pool,#{
chat_id=>ChatId,
text=><<"Text">>
}
).
```
## Async send message
``` erlang
{ok,Ref} = telegram_bot_api:sendMessage(Pool,#{
chat_id=>ChatId,
text=><<"Text">>
},
true).
```
## Get me
``` erlang
{ok,200,Result} = telegram_bot_api:getMe(BotName,#{}).
```
## Log out
``` erlang
{ok,200,#{ok := true,result := true}} = telegram_bot_api:logOut(BotName,#{}).
```
## Set bot name
``` erlang
telegram_bot_api:setMyName(BotName,#{name=><<"Бот">>,language_code=>ru}).
```
## Set bot photo
``` erlang
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
``` erlang
telegram_bot_api:setMyCommands(BotName,#{
commands=>[
#{
command=><<"/test">>,
description=><<"Test>>
}]
}).
```
## Send contact
``` erlang
telegram_bot_api:sendContact(BotName,#{
chat_id=>ChatId,
phone_number=><<"+79281111111">>,
first_name=><<"CONTACT">>
})
```
## Send photo
``` erlang
telegram_bot_api:sendPhoto(Pool,#{
chat_id=><<"@channelusername">>,
photo=>#{file=><<"/dir/file.jpg">>,name=><<"file.jpg">>}
}).
```
## Send audio
``` erlang
telegram_bot_api:sendAudio(BotName,#{
chat_id=>ChatId,
audio =>#{file=><<"/dir/file.mp3">>,name=><<"file.mp3">>}
}).
```
## Set message reaction
``` erlang
-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
``` erlang
-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
``` erlang
telegram_bot_api:editMessageText(BotName,#{
chat_id=>ChatId,
text=><<"text">>,
message_id=>MessageId
}).
```
## Edit message caption
``` erlang
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
``` erlang
telegram_bot_api:deleteMessage(BotName,#{
chat_id=>ChatId,
message_id=>MessageId
}).
```
## Inline keyboard
``` erlang
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
``` erlang
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
``` erlang
telegram_bot_api:answerCallbackQuery(BotName,#{
callback_query_id=>Id
}).
```
## Edit message reply markup
``` erlang
telegram_bot_api:editMessageReplyMarkup(BotName,#{
message_id=>MessageId,
chat_id=>ChatId,
reply_markup=>
#{
inline_keyboard=>
[
[
#{
text=><<"ok">>,
callback_data=><<"callback_ok">>
}
]
]
}
}).
```
## Send chat action
``` erlang
-include_lib("telegram_bot_api/include/chat_action.hrl").
telegram_bot_api:sendChatAction(BotName,#{
chat_id=>ChatId,
action=>?CHAT_ACTION_UPLOAD_PHOTO
}).
```
## Send dice
``` erlang
-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
``` erlang
telegram_bot_api:sendMessageDraft(BotName,#{
chat_id=>ChatId,
draft_id=>DrafId,
text=>Text,
message_thread_id=>ThreadId
})
```
## Create forum topic
``` erlang
-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
``` erlang
telegram_bot_api:editForumTopic(BotName,#{
chat_id=>ChatId,
message_thread_id=>ThreadId,
name=>Text
}).
```
## Restrict chat member
``` erlang
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
``` erlang
%%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
``` erlang
telegram_bot_api:getUserProfileAudios(BotName,#{user_id=>1234}).
```
## Set chat member tag
``` erlang
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](https://hexdocs.pm/telegram_bot_api/telegram_bot_api.html#bot-settings)
* [emoji](https://hexdocs.pm/telegram_bot_api/telegram_bot_api_emoji.html)
* [example](https://github.com/krot3232/telegram_bot_api/tree/main/example)
