Patrick Brandão

Guia do bot Telegram

Saudações.

Nesse tutorial vou explicar como usar um Bot do Telegram para automações.

1 – Abrindo uma conversa com o Bot Father

O primeiro passo é criar um bot.

Um bot é uma conta virtual que pertence a uma conta real (você).

Para criar é necessário chamar um bot nativo do Telegram chamado “Bot Father“

Você pode ir até ele pelo QR-CODE:

Ou pelo link da conta:

Inicie uma conversa com o comando /help, retorno:

Telegram Bot Father /help
I can help you create and manage Telegram bots. If you're new to the Bot API, please see the manual.

You can control me by sending these commands:

/newbot - create a new bot
/mybots - edit your bots

Edit Bots
/setname - change a bot's name
/setdescription - change bot description
/setabouttext - change bot about info
/setuserpic - change bot profile photo
/setcommands - change the list of commands
/deletebot - delete a bot

Bot Settings
/token - get authorization token
/revoke - revoke bot access token
/setinline - toggle inline mode
/setinlinegeo - toggle inline location requests
/setinlinefeedback - change inline feedback settings
/setjoingroups - can your bot be added to groups?
/setprivacy - toggle privacy mode in groups

Web Apps
/myapps - edit your web apps
/newapp - create a new web app
/listapps - get a list of your web apps
/editapp - edit a web app
/deleteapp - delete an existing web app

Games
/mygames - edit your games
/newgame - create a new game
/listgames - get a list of your games
/editgame - edit a game
/deletegame - delete an existing game

2 – Criar novo bot

Na conversa com o Bot Father, envie a mensagem: /newbot
Se você digitou errado, cancele e comece novamente com o comando: /cancel

Ele vai responder:

  • Alright, a new bot. How are we going to call it? Please choose a name for your bot.
  • Tradução: Muito bem, um novo bot. Como vamos chamá-lo? Por favor, escolha um nome para o seu bot.

Responda o nome de exibição do bot, exemplo: Kirkland Meeseeks

Ele vai responder (se aceitar o nome):

  • Good. Now let’s choose a username for your bot. It must end in bot. Like this, for example: TetrisBot or tetris_bot.
  • Tradução: Ótimo. Agora, vamos escolher um nome de usuário para o seu bot. Ele deve terminar com bot. Assim, por exemplo: TetrisBot ou tetris_bot.

Você deve responder com o nome do bot que deseja criar – nome de usuário para login.

Esse bot será uma conta @nome_do_bot para que qualquer pessoa possa encontrar e chamar.

O nome do bot deve terminar com “bot“, é uma regra que não da para contornar, se você não colocar esse sufixo ele responderá:

  • Sorry, the username must end in bot. E.g. Tetris_bot or Tetrisbot.
  • Tradução: Desculpe, o nome de usuário deve terminar com “bot”. Ex.: Tetris_bot ou Tetrisbot.

No meu exemplo seria:

  • Login: “kirkland_meeseeks“,
  • Mas com final “bot”, fica: kirkland_meeseeks_bot

Se o login já existir ele recusará, quando você digitar um nome único ele irá aprovar com essa mensagem:

  • Done! Congratulations on your new bot…
    Use this token to access the HTTP API:
    7234567890:ABC1D2Efgh2ijKlMnOpQRStuVXyzw3AbCdE
    For a description of the Bot API, see this page:
    https://core.telegram.org/bots/api

O que importa nessa resposta é a chave de API do bot (BOT API KEY):

  • 1234567890:ABC1D2Efgh2ijKlMnOpQRStuVXyzw3AbCdE

Com ele temos controle completo do bot para integrá-lo com automações.

3 – Personalizando o bot

Mande para o Bot Father o comando: /mybots

Ele vai mostrar os seus bots, clique no nome do bot desejado
(kirkland_meeseeks_bot no meu caso).

Opções que ele exibirá:

  • API Token – Consulta a chave atual, com opção de revogar e gerar nova chave (cancela a chave anterior);
  • Edit Bot – É onde personalizamos as características do bot;
    • Edit Name
    • Edit About
    • Edit Description
    • Edit Description Picture
    • Edit Botpic
    • Edit Commands
    • Edit Privacy Policy
    • Edit Commands
  • Bot Settings – É onde alteramos as configurações do bot;
    • Inline mode;
    • Secretary Mode;
    • Allow Groups?
    • Group Privacy
    • Group Admin Rights
    • Channel Admin Rights
    • Payments
    • Domain
    • Menu Button
    • Configure Mini App
    • Paid Broadcast
  • Payments – É onde fica a relação entre o bot e pagamentos;
  • Transfer Ownership – É onde você pode transferir o bot para outra conta do Telegram (vender bot, delegar a um funcionário, etc);
  • Delete Bot – É onde você deleta completamente seu bot.

Para mexer no perfil do bot, clique no botão: Edit Bot.

Atributos editáveis:

  • Name: O nome de exibição;
  • About: Informações sobre o bot;
  • Description: Descrição detalhada do bot, sua função e tarefas que ele executa (use como Agent Card);
  • Description Picture: Altera a imagem do bot;
  • Privacy Policy: Contrato que define como informações pessoais e sigilosas são tratadas no armazenamento de dados do bot.

Para personalizar a foto do bot, clique em:

  • Description Picture: Envie a foto que aparece no meio da tela ao iniciar uma nova conversa;
  • Edit Botpic: Envie a foto de perfil do contato.

Suas opções:

  • Enviar uma foto no chat, tipo e tamanho:
    • Tamanho aceito (único) para tipos PNG ou JPEG:
      • 640 x 360;
    • Tamanhos aceitos no formato GIF
      • 320 x 180;
      • 640 x 360;
      • 960 x 540;

Ao enviar a foto no tamanho correto, ele responderá:

  • Success! Description media updated. You will be able to see the changes within a few minutes.
  • Tradução: Sucesso! A mídia da descrição foi atualizada. Você poderá ver as alterações em alguns minutos.

Se você quiser apagar a imagem e deixar o bot sem nenhuma foto, use: /empty

4 – Primeira interação

Para que o bot possa interagir com qualquer usuário, o usuário precisa abrir uma nova conversa com o login do bot e mandar o comando: /start

Primeira foto de Botpic(bolinha com qr-code) e a segunda foto de Description Picture (quadro de boas vindas):

5 – API básica de controle do bot

Com a chave de API do bot em mãos, vamos rodar alguns comandos CURL para manipular nosso bot.

A única operação que não existe é “obter lista de chats” entre o bot e os usuários chamaram. Você precisará usar a técnica de registrar o id dos chats via webhook.

Principais chaves no JSON que transita entre o bot e seu servidor:

  • Cada conta tem um id único “id“;
  • Cada conversa entre um contato ou grupo e o bot gera um “chat_id“. Ele é necessário para responder e enviar mensagens de volta;
  • Cada mensagem em uma conversa tem seu “message_id“, utilizada para apagar, encaminhar e editar a mensagem.

Com isso, o “id” do remetente, o “chat_id” da conversa e os identificadores “message_id” de cada mensagem são únicos e relativo aos participantes.

5.1 – Autenticação e teste inicial

Teste se o token funciona e obtenha o “id” do bot.
O boleano “ok“=[false|true] é a flag de funcionamento.

Bash
# Coloque o TOKEN do seu bot
TOKEN="12345...AbCdE";
curl "https://api.telegram.org/bot${TOKEN}/getMe";
JSON
{
    "ok": true,
    "result": {
        "id": 8975793915,
        "is_bot": true,
        "first_name": "Kirkland Meeseeks",
        "username": "kirkland_meeseeks_bot",
        "can_join_groups": true,
        "can_read_all_group_messages": false,
        "supports_inline_queries": false,
        "supports_guest_queries": false,
        "can_connect_to_business": false,
        "has_main_web_app": false,
        "has_topics_enabled": false,
        "allows_users_to_create_topics": false,
        "can_manage_bots": false,
        "supports_join_request_queries": false
    }
}

5.2 – Vincular webhook no bot

Essa é a API mais importante. Com ela, todas as mensagens e eventos relacionados ao seu boot são:

Diagrama de eventos:

A cada evento (inicio, envio de mensagem/foto/video/audio/pagamento) o servidor do Telegram envia um documento JSON para sua URL de Webhook.

Associando URL de webhook no bot:

Bash
# Coloque o TOKEN do seu bot
TOKEN="12345...AbCdE";

# Coloque a URL gerada pelo seu sistema de automacao
WEBHOOK="https://webhook.dominio.com/telegram/boot01";

# Acionar API para definir URL de Webhook
curl \
    -X POST "https://api.telegram.org/bot${TOKEN}/setWebhook" \
    -H "Content-Type: application/json" \
    -d "{\"url\": \"${WEBHOOK}\"}";
JSON
{
    "ok": true,
    "result": true,
    "description": "Webhook was set"
}

5.3 – Consultar webhook do bot

Conferir qual webhook está definida na conta (se acontecer de vários softwares tentarem usar o mesmo bot, esse valor vai ficar sambando entre as várias URLs):

Bash
# Coloque o TOKEN do seu bot
TOKEN="12345...AbCdE";

# Conferir qual URL de webhook esta recebendo eventos do bot
curl "https://api.telegram.org/bot${TOKEN}/getWebhookInfo";
JSON
{
    "ok": true,
    "result": {
        "url": "https://webhook.dominio.com/telegram/boot01",
        "has_custom_certificate": false,
        "pending_update_count": 0,
        "max_connections": 40,
        "ip_address": "104.23.47.123"
    }
}

5.4 – Desativar webhook do bot

Caso deseje deletar a URL de webhook (desativar aviso de eventos via URL):

Bash
# Coloque o TOKEN do seu bot
TOKEN="12345...AbCdE";

# Apagar URL de webhook e desativar aviso de eventos via URL/HTTP
curl "https://api.telegram.org/bot${TOKEN}/deleteWebhook";
JSON
{
    "ok": true,
    "result": true,
    "description": "Webhook was deleted"
}

5.5 – Exemplo de eventos na webhook

Exemplos de mensagens (JSON) recebidas na webhook:

Primeiro contato iniciando o chat com o comando /start (comando enviado):

JSON
{
    "update_id": 954888273,
    "message": {
        "message_id": 5,
        "from": {
            "id": 464557464,
            "is_bot": false,
            "first_name": "Patrick",
            "last_name": "Brandão",
            "username": "patrickbrandao",
            "language_code": "pt-br",
            "is_premium": true
        },
        "chat": {
            "id": 464557464,
            "first_name": "Patrick",
            "last_name": "Brandão",
            "username": "patrickbrandao",
            "type": "private"
        },
        "date": 1790390624,
        "text": "/start",
        "entities": [
            {
                "offset": 0,
                "length": 6,
                "type": "bot_command"
            }
        ]
    }
}

Mensagem de texto enviada pelo usuário:

JSON
{
    "update_id": 954888274,
    "message": {
        "message_id": 6,
        "from": {
            "id": 464557464,
            "is_bot": false,
            "first_name": "Patrick",
            "last_name": "Brandão",
            "username": "patrickbrandao",
            "language_code": "pt-br",
            "is_premium": true
        },
        "chat": {
            "id": 464557464,
            "first_name": "Patrick",
            "last_name": "Brandão",
            "username": "patrickbrandao",
            "type": "private"
        },
        "date": 1790390790,
        "text": "Kirk, meu irmão, qual a novidade do dia?"
    }
}

Imagem (sem texto):

JSON
{
    "update_id": 954888275,
    "message": {
        "message_id": 7,
        "from": {
            "id": 464557464,
            "is_bot": false,
            "first_name": "Patrick",
            "last_name": "Brandão",
            "username": "patrickbrandao",
            "language_code": "pt-br",
            "is_premium": true
        },
        "chat": {
            "id": 464557464,
            "first_name": "Patrick",
            "last_name": "Brandão",
            "username": "patrickbrandao",
            "type": "private"
        },
        "date": 1790390915,
        "photo": [
            {
                "file_id": "AgACAgEAAxkBAAMHarcyg2_0BG12Jz5pF19O_zqZFScAAqsMaxs-krlF4kDiq1AeN_QBAAMCAANzAAM9BA",
                "file_unique_id": "AQADqwxrGz6SuUV4",
                "file_size": 2037,
                "width": 90,
                "height": 79
            },
            {
                "file_id": "AgACAgEAAxkBAAMHarcyg2_0BG12Jz5pF19O_zqZFScAAqsMaxs-krlF4kDiq1AeN_QBAAMCAANtAAM9BA",
                "file_unique_id": "AQADqwxrGz6SuUVy",
                "file_size": 15871,
                "width": 320,
                "height": 282
            },
            {
                "file_id": "AgACAgEAAxkBAAMHarcyg2_0BG12Jz5pF19O_zqZFScAAqsMaxs-krlF4kDiq1AeN_QBAAMCAAN4AAM9BA",
                "file_unique_id": "AQADqwxrGz6SuUV9",
                "file_size": 24243,
                "width": 476,
                "height": 420
            }
        ]
    }
}

Imagem com caption (texto da imagem):

JSON
{
    "update_id": 954888276,
    "message": {
        "message_id": 8,
        "from": {
            "id": 464557464,
            "is_bot": false,
            "first_name": "Patrick",
            "last_name": "Brandão",
            "username": "patrickbrandao",
            "language_code": "pt-br",
            "is_premium": true
        },
        "chat": {
            "id": 464557464,
            "first_name": "Patrick",
            "last_name": "Brandão",
            "username": "patrickbrandao",
            "type": "private"
        },
        "date": 1790391122,
        "photo": [
            {
                "file_id": "AgACAgEAAxkBAAMIarczUidA-hhEjTpaUMXxXv0BvUoAAqwMaxs-krlFIRtaMId1P3kBAAMCAANzAAM9BA",
                "file_unique_id": "AQADrAxrGz6SuUV4",
                "file_size": 1750,
                "width": 90,
                "height": 90
            },
            {
                "file_id": "AgACAgEAAxkBAAMIarczUidA-hhEjTpaUMXxXv0BvUoAAqwMaxs-krlFIRtaMId1P3kBAAMCAANtAAM9BA",
                "file_unique_id": "AQADrAxrGz6SuUVy",
                "file_size": 11753,
                "width": 320,
                "height": 320
            },
            {
                "file_id": "AgACAgEAAxkBAAMIarczUidA-hhEjTpaUMXxXv0BvUoAAqwMaxs-krlFIRtaMId1P3kBAAMCAAN4AAM9BA",
                "file_unique_id": "AQADrAxrGz6SuUV9",
                "file_size": 19026,
                "width": 512,
                "height": 512
            }
        ],
        "caption": "Icone do freeradius"
    }
}

Arquivo de audio (MP3) anexado com caption:

JSON
{
    "update_id": 954888277,
    "message": {
        "message_id": 9,
        "from": {
            "id": 464557464,
            "is_bot": false,
            "first_name": "Patrick",
            "last_name": "Brandão",
            "username": "patrickbrandao",
            "language_code": "pt-br",
            "is_premium": true
        },
        "chat": {
            "id": 464557464,
            "first_name": "Patrick",
            "last_name": "Brandão",
            "username": "patrickbrandao",
            "type": "private"
        },
        "date": 1790391462,
        "audio": {
            "duration": 1,
            "file_name": "ss-red-alert.mp3",
            "mime_type": "audio/mpeg",
            "file_id": "CQACAgEAAxkBAAMJarc0phu5Ed0b0Ofr8_G-1nEbVeYAAgwHAAI-ksFFV5SWypP_au89BA",
            "file_unique_id": "AgADDAcAAj6SwUU",
            "file_size": 10092
        },
        "caption": "MP3 do Red Alert"
    }
}

5.6 – Respondendo o usuário

Agora que temos as mensagens entrando na webhook, chegou a hora de responder o usuário com alguma automação básica (n8n por exemplo).

Antes disso precisamos saber como usar a API do Telegram para enviar conteúdo dentro da conversa (chat_id).

O chat_id é obtido na propriedade “chat” na chave “id” (chat.id).

Nos exemplos acima os valores são:

  • Identificador da conversa: chat.id = 464557464;
  • Identificador do remetente (usuário): from.id = 464557464;
  • Quando ambos são iguais significa que o chat é privado entre o bot e o usuário, quando for diferente significa que a conversa ocorre num grupo.

Enviando mensagem de texto na conversa:

Bash
# Coloque o TOKEN do seu bot
TOKEN="12345...AbCdE";

# ID do chat
CHAT_ID="464557464";

# Mensagem de texto
MESSAGE="Olha a temperatura do equipamento, vai explodir...";

# Acionar API para definir URL de Webhook
curl \
    -X POST "https://api.telegram.org/bot${TOKEN}/sendMessage" \
    -H "Content-Type: application/json" \
    -d "{\"chat_id\": \"$CHAT_ID\", \"text\": \"$MESSAGE\"}";
JSON
{
    "ok": true,
    "result": {
        "message_id": 10,
        "from": {
            "id": 8975793915,
            "is_bot": true,
            "first_name": "Kirkland Meeseeks",
            "username": "kirkland_meeseeks_bot"
        },
        "chat": {
            "id": 464557464,
            "first_name": "Patrick",
            "last_name": "Brandão",
            "username": "patrickbrandao",
            "type": "private"
        },
        "date": 1790392642,
        "text": "Olha a temperatura do equipamento, vai explodir..."
    }
}

Terminamos por hoje!

Patrick Brandão, patrickbrandao@gmail.com

“unca existiu uma grande inteligência
sem uma veia de loucura.“
Aristóteles