Framebot - Documentação¶
Framebot é um framework escrito C com o objetivo de ajudar programadores a criarem chat bots para o Telegram.
Começando¶
Framebot é uma biblioteca feita em C para facilitar o uso da BOT API do telegram.
Instalação¶
Para instalar a biblioteca você deve primeiro clonar o nosso repositório:
git clone https://github.com/giancarlopro/framebot
Agora você vai precisar ter o cmake instalado, e algumas libs:
sudo apt install cmake openssl curl jansson
Após isso entre na pasta onde a biblioteca foi clonada, por padrão vai ser framebot:
cd framebot
Agora crie uma pasta para compilar a biblioteca e rode o cmake para criar o makefile:
mkdir build
cd build
cmake ..``
Agora utilize o makefile para compilar e instalar a biblioteca:
make
make install
Configuração¶
Para utilizar a biblioteca em seus projetos, você deve informar ao compilador explicitamente as bibliotecas que serão compiladas juntas.
- Se estiver compilando pelo terminal:
gcc projeto.c -o out -lcurl -ljansson -lframebot
- Se estiver utilizando o cmake basta informar no seu CMakeLists.txt, em target_link_libraries:
target_link_libraries(seuexecutavel framebot)
Utilização¶
Para utilizar a biblioteca em seus projetos, você deve incluir o arquivo framebot.h.
#include <framebot/framebot.h>
Tutorial¶
Neste pequeno tutorial, vamos criar um echo bot. Ele basicamente vai reenviar as mensagens que são recebidas como resposta.
O código está disponível em GitHub: Echo Bot.
Estrutura básica¶
Para este projeto, nós vamos receber o token do bot na chama do binário, ficando assim:
./bot TOKEN
Para isso vamos criar nossa estrutura em c da seguinte forma:
#include <stdio.h>
#include <framebot/framebot.h>
int main (int argc, char **argv) {
if (argc < 2) {
printf("Usage: ./echo BOT_TOKEN\n");
exit(-1);
}
framebot_init(); // Inicializamos
return 0;
}
Aqui nós criamos uma condição caso o token não seja fornecido,
e inicializamos a biblioteca com a função framebot_init()
.
Variaveis¶
Agora precisaremos de algumas variáveis para manipular a biblioteca. Serão elas:
long int last_offset = 0;
Bot *echo;
Framebot *frame_update;
Update *message, *temp;
- Onde:
last_offset
vai ser utilizado para podermos resetar a lista de updates mais tardeecho
é o nosso objeto do tipoBot
, essencial para manipular a bibliotecaframe_update
que vai ser inicializado pela funçãoget_updates()
com as ultimas mensagensmessage
que vai conter nosso array de mensagens
Agora vamos inicializar nosso objeto Bot
para podermos usar a API do Telegram.
Para isso utilizamos a função framebot()
, caso aconteça algum erro, ela retornará NULL
.
Vamos passar para a função nosso token que está localizado em argv[1]
.
echo = framebot(argv[1]);
Pegando atualizações¶
Agora já podemos pegar as atualizações direto da API.
frame_update = get_updates(echo, NULL, last_offset, 100, 0, NULL);
message = frame_update->update_message;
temp = message;
Na primeira linha é retornado um objeto do tipo Framebot
,
que contem referencias para as atualizações de diferentes tipos.
Na segunda linha nós armazenamos na variavel message
os updates
do tipo Message.
Na ultima linhas nós passamos a referencia do primeiro Update pra variavel temp
,
que nós vamos utilizar para iterar os Updates.
Respondendo as mensagens¶
Com as atualizações da API em mãos, agora vamos responder as mensagens recebidas pelo bot. Primeiro vamos iterar nossos Updates, e responder com a mesma mensagem recebida.
while (temp) {
if (temp->message) {
if (send_message_chat (echo, temp->message->from->id, temp->message->text, NULL, 0, 0, temp->message->message_id, NULL)) {
printf("Sended: \"%s\" to %s!\n", temp->message->text, temp->message->from->username);
}
}
last_offset = temp->update_id + 1; // Aqui armazenamos o offset do ultimo update, para podermos resetar depois
temp = temp->next;
}
Aqui temos um while para iterar nossos Updates. Primeiro verificamos se recebemos de fato alguma mensagem,
depois tentamos enviar nossa resposta, caso consigamos é escrito na tela uma mensagem informando
o que foi enviado e para quem.
Depois atualizamos nosso last_offset
para podermos resetar a lista de updates.
Resetando updates¶
Resetar a lista de updates é importante para que não recebamos novamente as mesmas atualizações,
dessa forma só respondemos uma única vez.
Para resetar, nós fazemos mais uma chamada à get_updates()
e passamos o nosso last_offset
.
Dessa forma, na próxima chamada à get_updates()
não iremos receber os mesmos Updates.
get_updates(echo, frame_update, last_offset, 100, 0, NULL);
Limpando estruturas¶
No final nós liberamos a memória alocada com a função framebot_free()
.
framebot_free(frame_update);
Aqui finalizamos nosso tutorial.
Código final disponível em GitHub: Echo Bot.
Objetos¶
Nossa biblioteca implementa todos os objetos da API do telegram, com os mesmos nomes,
e a princípio com os mesmos membros.
Alguns tipos podem possuir um ponteiro next
apontando para o próximo objeto.
Objetos exclusivos¶
Objetos que existem somente na biblioteca, e não possuem representação na API do Telegram.
Referência completa¶
-
User
¶ -
long int
id
¶
-
bool
is_bot
¶
-
char *
first_name
¶
-
char *
last_name
¶
-
char *
username
¶
-
char *
language_code
¶
-
struct _user *
next
¶
-
long int
-
Bot
-
char *
token
-
User *
user
-
char *
-
Chat
¶ -
long int
id
¶
-
char *
type
¶
-
char *
title
¶
-
char *
username
¶
-
char *
first_name
¶
-
char *
last_name
¶
-
bool
all_members_are_administrators
¶
-
char *
description
¶
-
char *
invite_link
¶
-
struct _message *
pinned_message
¶
-
char *
sticker_set_name
¶
-
bool
can_set_sticker_set
¶
-
long int
-
MessageEntity
¶ -
char *
type
¶
-
long int
offset
¶
-
long int
length
¶
-
char *
url
¶
-
struct _message_entity *
next
¶
-
char *
-
Audio
¶ -
char *
file_id
¶
-
long int
duration
¶
-
char *
performer
¶
-
char *
title
¶
-
char *
mime_type
¶
-
long int
file_size
¶
-
char *
-
Game
¶ -
char *
file_id
¶
-
char *
file_name
¶
-
char *
mime_type
¶
-
long int
file_size
¶
-
char *
title
¶
-
char *
description
¶
-
char *
text
¶
-
Animation *
animation
¶
-
char *
-
Video
¶ -
char *
file_id
¶
-
int
width
¶
-
int
height
¶
-
long int
duration
¶
-
char *
mime_type
¶
-
long int
file_size
¶
-
char *
-
ShippingAddress
¶ -
char *
country_code
¶
-
char *
state
¶
-
char *
city
¶
-
char *
street_line1
¶
-
char *
street_line2
¶
-
char *
post_code
¶
-
char *
-
SuccessfulPayment
¶ -
char *
currency
¶
-
long
total_amount
¶
-
char *
invoice_payload
¶
-
char *
shipping_option_id
¶
-
char *
telegram_payment_charge_id
¶
-
char *
provider_payment_charge_id
¶
-
char *
-
PreCheckoutQuery
¶ -
char *
id
¶
-
char *
currency
¶
-
long
total_amount
¶
-
char *
invoice_payload
¶
-
char *
shipping_option_id
¶
-
char *
-
Message
¶ -
long int
message_id
¶
-
long int
date
¶
-
long int
forward_from_message_id
¶
-
char *
forward_signature
¶
-
long int
forward_date
¶
-
struct _message *
reply_to_message
¶
-
long int
edit_date
¶
-
char *
media_group_id
¶
-
char *
text
¶
-
Document *
document
¶
-
char *
new_chat_title
¶
-
bool
delete_chat_photo
¶
-
bool
group_chat_created
¶
-
bool
supergroup_chat_created
¶
-
bool
channel_chat_created
¶
-
long int
migrate_to_chat_id
¶
-
long int
migrate_from_chat_id
¶
-
struct _message *
pinned_message
¶
-
SuccessfulPayment *
successful_payment
¶
-
char *
connected_website
¶
-
long int
-
CallbackQuery
¶ -
char *
id
¶
-
char *
inline_message_id
¶
-
char *
chat_instance
¶
-
char *
data
¶
-
char *
game_short_name
¶
-
char *
-
Framebot
¶ -
long int
update_id
¶
-
InlineQuery *
inline_query
¶
-
ChosenInlineResult *
chosen_inline_result
¶
-
CallbackQuery *
callback_query
¶
-
ShippingQuery *
shipping_query
¶
-
PreCheckoutQuery *
pre_checkout_query
¶
-
struct _update *
next
¶
-
long int
update_id
-
UPMessage *
message
-
UPMessage *
edited_message
-
UPMessage *
channel_post
-
UPMessage *
edited_channel_post
-
UPIResult *
chosen_inline_result
-
UPPCQuery *
pre_checkout_query
-
long int
-
ChatMember
¶ -
-
char *
status
¶
-
long int
until_date
¶
-
bool
can_be_edited
¶
-
bool
can_change_info
¶
-
bool
can_post_messages
¶
-
bool
can_edit_messages
¶
-
bool
can_delete_messages
¶
-
bool
can_invite_users
¶
-
bool
can_restrict_members
¶
-
bool
can_pin_messages
¶
-
bool
can_promote_members
¶
-
bool
can_send_messages
¶
-
bool
can_send_media_messages
¶
-
bool
can_send_other_messages
¶
-
bool
can_add_web_page_previews
¶
-
struct _chat_member *
next
¶
-
char *
-
CallbackGame
¶ -
long int
user_id
¶
-
long int
score
¶
-
bool
force
¶
-
bool
disable_edit_message
¶
-
long int
chat_id
¶
-
long int
message_id
¶
-
char *
inline_message_id
¶
-
long int
-
KeyboardButton
¶ -
char *
text
¶
-
bool
request_contact
¶
-
bool
request_location
¶
-
struct _keyboard_button *
next
¶
-
char *
-
InlineKeyboardButton
¶ -
char *
text
¶
-
char *
url
¶
-
char *
callback_data
¶
-
char *
switch_nline_query
¶
-
char *
switch_inline_query_current_chat
¶
-
CallbackGame *
callback_game
¶
-
bool
pay
¶
-
char *
-
Keyboard
¶ -
int
type
¶
-
InlineKeyboardButton *
inline_keyboard_markup
¶
-
ReplyKeyboardMarkup *
reply_keyboard_markup
¶
-
ReplyKeyboardRemove *
reply_keyboard_remove
¶
-
ForceReply *
_force_reply
¶
-
int
Funções¶
Aqui você encontra as funções implementadas pela biblioteca.
Todas as funções disponíveis na API do Telegram, estão disponíveis na biblíoteca usando o formato lower case separando os nomes com underscore.
Referencia completa¶
-
User *
user
(long int id, bool is_bot, const char *first_name, const char *last_name, const char *username, const char *language_code)¶
-
void
message_entity_free
(MessageEntity *msgett)¶
-
void
message_entity_add
(MessageEntity *dest, MessageEntity *src)¶
-
size_t
message_entity_len
(MessageEntity *message_entity)¶
-
MessageEntity *
message_entity_get
(MessageEntity *message_entity, int index)¶
-
Audio *
audio
(const char *file_id, long int duration, const char *performer, const char *title, const char *mime_type, long int file_size)¶
-
Document *
document
(const char *file_id, PhotoSize *thumb, const char *file_name, const char *mime_type, long int file_size)¶
-
void
document_free
(Document *document)¶
-
Animation *
animation
(const char *file_id, PhotoSize *thumb, const char *file_name, const char *mime_type, long int file_size)¶
-
void
animation_free
(Animation *animation)¶
-
Game *
game
(const char *title, const char *description, PhotoSize *photo, const char *text, MessageEntity *text_entities, Animation *animation)¶
-
Sticker *
sticker
(const char *file_id, int width, int height, PhotoSize *thumb, const char *emoji, long int file_size)¶
-
Video *
video
(const char *file_id, int width, int height, long int duration, PhotoSize *thumb, const char *mime_type, long int file_size)¶
-
Contact *
contact
(const char *phone_number, const char *first_name, const char *last_name, long int user_id)¶
-
Venue *
venue
(Location *location, const char *title, const char *address, const char *foursquare_id)¶
-
ChosenInlineResult *
chosen_inline_result
(const char *result_id, User *from, Location *location, const char *inline_message_id, const char *query)¶
-
void
chosen_inline_result_free
(ChosenInlineResult *cir)¶
-
Update *
update
(long int update_id, Message *message, Message *edited_message, Message *channel_post, Message *edited_channel_post, InlineQuery *inline_query, ChosenInlineResult *chosen_inline_result, CallbackQuery *callback_query, ShippingQuery *shipping_query, PreCheckoutQuery *pre_checkout_query)¶
-
void
update_free
(Update *oupdate)¶
-
void
update_add
(Update *dest, Update *src)¶
-
Update *
update_get
(Update *u, int index)¶
-
size_t
update_len
(Update *u)¶
-
ChatMember *
chat_member
(User *user, const char *status, long int until_date, bool can_be_edited, bool can_change_info, bool can_post_messages, bool can_edit_messages, bool can_delete_messages, bool can_invite_users, bool can_restrict_members, bool can_pin_messages, bool can_promote_members, bool can_send_messages, bool can_send_media_messages, bool can_send_other_messages, bool can_add_web_page_previews)¶
-
void
chat_member_free
(ChatMember *chatMember)¶
-
void
chat_member_add
(ChatMember *dest, ChatMember *src)¶
-
ChatMember *
chat_member_get
(ChatMember *chatMember, int index)¶
-
size_t
chat_member_len
(ChatMember *chatMember)¶
-
InlineQuery *
inline_query
(const char *id, User *user, Location *location, const char *query, const char *offset)¶
-
void
inline_query_free
(InlineQuery *inline_query)¶
-
CallbackQuery *
callback_query
(const char *id, User *user, Message *message, const char *inline_message_id, const char *chat_instance, const char *data, const char *game_short_name)¶
-
void
callback_query_free
(CallbackQuery *callback_query)¶
-
VideoNote *
video_note
(const char *file_id, long length, long duration, PhotoSize *photo_size, long file_size)¶
-
Invoice *
invoice
(const char *title, const char *description, const char *start_parameter, const char *currency, long total_amount)¶
-
ShippingQuery *
shipping_query
(const char *id, User *from, const char *invoice_payload, ShippingAddress *shipping_address)¶
-
void
shipping_query_free
(ShippingQuery *shipping_query)¶
-
ShippingAddress *
shipping_address
(const char *country_code, const char *state, const char *city, const char *street_line1, const char *street_line2, const char *post_code)¶
-
void
shipping_address_free
(ShippingAddress *shipping_address)¶
-
OrderInfo *
order_info
(const char *name, const char *phone_number, const char *email, ShippingAddress *shipping_address)¶
-
void
pre_checkout_query_free
(PreCheckoutQuery *pcq)¶
-
SuccessfulPayment *
successful_payment
(const char *currency, long total_amount, const char *invoice_payload, const char *shipping_option_id, OrderInfo *oorder_info, const char *telegram_payment_charge_id, const char *provider_payment_charge_id)¶
-
void
successful_payment_free
(SuccessfulPayment *spayment)¶
-
UserProfilePhotos *
user_profile_photos
(long int total_count, PhotoSize ** photo_size)¶
-
void
user_profile_photos_free
(UserProfilePhotos *oupp)¶
-
void
error
(long int error_code, const char *description)¶
-
void
error_free
()¶
-
Error *
get_error
()¶
-
void
framebot_init
()¶
-
refjson *
generic_method_call
(const char *token, char *formats, ...)¶
-
Error *
show_error
()¶
-
Framebot *
get_updates
(Bot *bot, Framebot *framebot, long int offset, long int limit, long int timeout, char *allowed_updates)¶
-
Message *
send_message
(Bot *bot, char * chat_id, char *text, char * parse_mode, bool disable_web_page_preview, long int reply_to_message_id, char * reply_markup)¶
-
Message *
send_message_chat
(Bot *bot, long int chat_id, char *text, char * parse_mode, bool disable_web_page_preview, long int reply_to_message_id, char * reply_markup)¶
-
Message *
forward_message_from
(Bot * bot, long int chat_id, char * from_chat_id, long int message_id)¶
-
Message *
forward_message_from_chat
(Bot * bot, char * chat_id, long int from_chat_id, long int message_id)¶
-
Message *
forward_message_chat
(Bot * bot, long int chat_id, long int from_chat_id, long int message_id)¶
-
Message *
send_photo
(Bot * bot, char * chat_id, char * filename, char * caption, long int reply_to_message_id, char * reply_markup)¶
-
Message *
send_photo_chat
(Bot * bot, long int chat_id, char * filename, char * caption, long int reply_to_message_id, char * reply_markup)¶
-
Message *
send_audio
(Bot *bot, char * chat_id, char * filename, char * caption, long int duration, char * performer, char * title, long int reply_to_message_id, char * reply_markup)¶
-
Message *
send_audio_chat
(Bot * bot, long int chat_id, char * filename, char * caption, long int duration, char * performer, char * title, long int reply_to_message_id, char * reply_markup)¶
-
Message *
send_document
(Bot * bot, char * chat_id, char * filename, char * caption, long int reply_to_message_id, char * reply_markup)¶
-
Message *
send_document_chat
(Bot * bot, long int chat_id, char * filename, char * caption, long int reply_to_message_id, char * reply_markup)¶
-
Message *
send_video
(Bot * bot, char * chat_id, char * video, long int duration, long int width, long int height, char * caption, long int reply_to_message_id, char * reply_markup)¶
-
Message *
send_video_chat
(Bot * bot, long int chat_id, char * video, long int duration, long int width, long int height, char * caption, long int reply_to_message_id, char * reply_markup)¶
-
Message *
send_voice
(Bot *bot, char * chat_id, char * filename, char * caption, long int duration, long int reply_to_message_id, char * reply_markup)¶
-
Message *
send_voice_chat
(Bot *bot, long int chat_id, char * filename, char * caption, long int duration, long int reply_to_message_id, char * reply_markup)¶
-
Message *
send_video_note
(Bot * bot, char * chat_id, char * filename, long int duration, long int length, long int reply_to_message_id, char * reply_markup)¶
-
Message *
send_video_note_chat
(Bot * bot, long int chat_id, char * filename, long int duration, long int length, long int reply_to_message_id, char * reply_markup)¶
-
Message *
send_location
(Bot * bot, char * chat_id, float latitude, float longitude, long int live_period, long int reply_to_message_id, char * reply_markup)¶
-
Message *
send_location_chat
(Bot * bot, long int chat_id, float latitude, float logitude, long int live_period, long int reply_to_message_id, char * reply_markup)¶
-
Message *
edit_message_live_location
(Bot * bot, char * chat_id, long int message_id, char * inline_message_id, float latitude, float longitude, char * reply_markup)¶
-
Message *
edit_message_live_location_chat
(Bot * bot, long int chat_id, long int message_id, char * inline_message_id, float latitude, float longitude, char * reply_markup)¶
-
Message *
stop_message_live_location
(Bot * bot, char * chat_id, long int message_id, char * inline_message_id, char * reply_markup)¶
-
Message *
stop_message_live_location_chat
(Bot * bot, long int chat_id, long int message_id, char * inline_message_id, char * reply_markup)¶
-
Message *
send_venue
(Bot * bot, char * chat_id, float latitude, float longitude, char * title, char * address, char * foursquare_id, long int reply_to_message_id, char * reply_markup)¶
-
Message *
send_venue_chat
(Bot * bot, long int chat_id, float latitude, float longitude, char * title, char * address, char * foursquare_id, long int reply_to_message_id, char * reply_markup)¶
-
Message *
send_contact
(Bot * bot, char * chat_id, char * phone_number, char * first_name, char * last_name, long int reply_to_message_id, char * reply_markup)¶
-
Message *
send_contact_chat
(Bot * bot, long int chat_id, char * phone_number, char * first_name, char * last_name, long int reply_to_message_id, char * reply_markup)¶
-
UserProfilePhotos *
get_user_profile_photos
(Bot * bot, char * dir, char *user_id, long offset, long limit)¶
-
UserProfilePhotos *
get_user_profile_photos_chat
(Bot * bot, char * dir, long user_id, long offset, long limit)¶
-
bool
restrict_chat_member
(Bot *bot, char *chat_id, long int user_id, long int until_date, bool can_send_messages, bool can_send_media_messages, bool can_send_other_messages, bool can_add_web_page_previews)¶
-
bool
restrict_chat_member_chat
(Bot *bot, long int chat_id, long int user_id, long int until_date, bool can_send_messages, bool can_send_media_messages, bool can_send_other_messages, bool can_add_web_page_previews)¶
-
bool
promote_chat_member
(Bot *bot, char *chat_id, long int user_id, bool can_change_info, bool can_post_messages, bool can_edit_messages, bool can_delete_messages, bool can_invite_users, bool can_restrict_members, bool can_pin_messages, bool can_promote_members)¶
-
bool
promote_chat_member_chat
(Bot *bot, long int chat_id, long int user_id, bool can_change_info, bool can_post_messages, bool can_edit_messages, bool can_delete_messages, bool can_invite_users, bool can_restrict_members, bool can_pin_messages, bool can_promote_members)¶
-
bool
pin_chat_message_chat
(Bot *bot, long int chat_id, long int message_id, bool disable_notification)¶
-
ChatMember *
get_chat_administrators
(Bot *bot, char *chat_id)¶
-
ChatMember *
get_chat_administrators_chat
(Bot *bot, long int chat_id)¶
-
ChatMember *
get_chat_member
(Bot *bot, char *chat_id, long int user_id)¶
-
ChatMember *
get_chat_member_chat
(Bot *bot, long int chat_id, long int user_id)¶
-
Message *
edit_message_text
(Bot *bot, char *chat_id, long int message_id, char *inline_message_id, char *text, char *parse_mode, bool disable_web_page_preview, char *reply_markup)¶
-
Message *
edit_message_text_chat
(Bot *bot, long int chat_id, long int message_id, char *inline_message_id, char *text, char *parse_mode, bool disable_web_page_preview, char *reply_markup)¶
-
Message *
edit_message_reply_markup
(Bot *bot, char *chat_id, long int message_id, char *inline_message_id, char *reply_markup)¶
-
Message *
edit_message_reply_markup_chat
(Bot *bot, long int chat_id, long int message_id, char *inline_message_id, char *reply_markup)¶
-
bool
answerInlineQuery
(Bot *bot, char *inline_query_id, char *results, long int cache_time, bool is_personal, char *next_offset, char *switch_pm_text, char *switch_pm_parameter)¶
-
void
set_notification
(bool disable_notification)¶
-
bool
get_notification
()¶
-
void
set_parse_mode
(int32_t mode)¶
-
int32_t
get_parse_mode
()¶