Consumindo APIs do Telegram

Automatize o envio e recebimento de mensagens no Telegram com o uso de BOT através de APIs

Pouco difundido, o Telegram é um concorrente do WhatsApp. Trata-se de um mensageiro mais conhecido (e bastante utilizado) pelos profissionais de TI. São inúmeras funcionalidades, dentre elas o uso de BOTs, aliado a facilidade do consumo de APIs para o envio automático de mensagens.

Um dos motivos da utilização de BOT no Telegram é a simplicidade de implementação. Basta criar uma conta BOT e efetuar requisições restfull, diferente da API do WhatsApp, onde requer um alto investimento de infraestrutura, além de ser reservado a médias e grandes empresas

Com o uso de um BOT no Telegram, você pode:

Automatizar o atendimento ao cliente, retendo o máximo possível de clientes no atendimento eletrônico.
Enviar uma galeria de fotos e vídeos aos usuários.
Solicitar o número do telefone ou localização por GPS, num único botão de resposta.
Realizar pesquisas anônimas/identificadas, única/múltipla escolha e temporizada.
Entre outros...

Este artigo é apenas um resumo. Caso queira acompanhar todas as funcionalidades da API do Telegram, consulte a documentação completa no link https://core.telegram.org/bots/api/

Pré-requisitos

Postman instalado » https://www.postman.com/
Collection Postman » https://github.com/leobreda/telegram/blob/main/Telegram-bot.postman_collection.json

Criando uma conta BOT

Localize o usuário @botFather
Execute o comando /newbot
Preencha informações como o nome do Bot, alias. Após o cadastro, anote o Token, pois será utilizado para o disparo das APIs.
Localize o usuário BOT criado e dê um "alô", para gerar o primeiro contato com o BOT.

Configurando o Postman

Com a Collection carregada no Postman, ...

... crie um Environment com o título Telegram, contendo variável denominada telegram_token, com o respectivo Token fornecido pelo @BotFather.

getMe

É o primeiro método a ser consumido. Consiste em recuperar informações relacionadas ao BOT

GET https://api.telegram.org/bot{{telegram_token}}/getMe

Retorno:

{
    "ok": true,
    "result": {
        "id": 17745479,
        "is_bot": true,
        "first_name": "leobreda_bot",
        "username": "leobreda_bot",
        "can_join_groups": true,
        "can_read_all_group_messages": false,
        "supports_inline_queries": true
    }
}

Conversando com o BOT

Você como usuário, faça o primeiro contato com o BOT.
A justificativa é que a API do Telegram lhe enxerga como um ID numérico, e esta é a única forma que o BOT identifica você na base de usuários.

Agora é hora de descobrir o ID de seu usuário, via método /getUpdates ;-)

getUpdates

É aqui que você recupera os usuários que estão conversando com o BOT e suas respectivas mensagens.

GET https://api.telegram.org/bot{{telegram_token}}/getUpdates

Retorno:

{
    "ok": true,
    "result": [
        {
            "update_id": 280024629,
            "message": {
                "message_id": 368,
                "from": {
                    "id": 590401,
                    "is_bot": false,
                    "first_name": "Leobreda",
                    "username": "Leobreda",
                    "language_code": "pt-br"
                },
                "chat": {
                    "id": 590401,
                    "first_name": "Leobreda",
                    "username": "Leobreda",
                    "type": "private"
                },
                "date": 1622502442,
                "text": "Olá"
            }
        },
        {
            "update_id": 280024630,
            "message": {
                "message_id": 369,
                "from": {
                    "id": 590401,
                    "is_bot": false,
                    "first_name": "Leobreda",
                    "username": "Leobreda",
                    "language_code": "pt-br"
                },
                "chat": {
                    "id": 590401,
                    "first_name": "Leobreda",
                    "username": "Leobreda",
                    "type": "private"
                },
                "date": 1622502755,
                "text": "Boa noite, querido BOT"
            }
        }
    ]
}

O ID 590401 corresponde ao usuário no qual fez o contato com o BOT.

Para facilitarmos os testes, faremos o retorno no Postman armazenar automaticamente o parâmetro message.from.id na variável {{user_id}}, necessário em todos os cenários explorados por aqui.

var json = pm.response.json();
pm.environment.set("user_id", json.result[0].message.from.id);

E assim, além da criação da variável {{user_id}}, gravamos o ID retornado.

getChat

O método retorna informações do usuário {{user_id}} que entrou em contato com o BOT. Lembre-se que atualizamos a variável via Postman na resposta do método /getUpdates.

POST https://api.telegram.org/bot{{telegram_token}}/getChat

{
	"chat_id":"{{user_id}}"
}

Retorno:

{
    "ok": true,
    "result": {
        "id": 590401,
        "first_name": "Leobreda",
        "username": "Leobreda",
        "type": "private",
        "photo": {
            "small_file_id": "AQADAQADuacxG4nhhAMACFQ33ikABAIAA4nhhAMABF651OUdlKmf",
            "small_file_unique_id": "AQADVDfeKQAE",
            "big_file_id": "AQADAQADuacxG4nhhAMACFQ33ikABAMAA4nhhAMABF651OUdlKmf",
            "big_file_unique_id": "AQADVDfeKQAE"
        }
    }
}

sendLocation

Possibilita o envio de determinada localização ao usuário.

POST https://api.telegram.org/bot{{telegram_token}}/sendLocation

{
    "chat_id":"{{user_id}}",
    "latitude":-23.5578519,
    "longitude":-46.617725
}

sendContact

Envia o contato telefônico/eletrônico no formato VCARD.

O código presente na variável vcard precisa estar na mesma tabulação do código abaixo, caso contrário, as informações não aparecerão no contato.

POST https://api.telegram.org/bot{{telegram_token}}/sendContact

{
	"chat_id":"{{user_id}}",
	"phone_number":"+55 11 99999-8047",
	"first_name":"Leonardo Breda",
	"vcard":"BEGIN:VCARD
VERSION:2.1
ORG:Tech Lead @ Itau Unibanco
TITLE:Itau Unibanco
TEL;WORK;VOICE:+55 11 2345-6789
TEL;HOME;VOICE:+55 11 99999-8888
ADR;WORK;PREF:;;Av do Estado, 3355;São Paulo;SP
EMAIL:leobreda@email.com.br
REV:20080424T195243Z
END:VCARD"}

sendMessage

Envio de mensagem texto e diferentes formas, seja texto puro, no formato HTML, entre outras coisas.

Texto puro

POST https://api.telegram.org/bot{{telegram_token}}/sendMessage

{
    "chat_id":"{{user_id}}",
    "text":"Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book."
}

Texto com HTML

"parse_mode":"HTML"

POST https://api.telegram.org/bot{{telegram_token}}/sendMessage

{
    "chat_id":"{{user_id}}",
    "parse_mode":"HTML",
    "text":"<b>bold</b>\n<strong>strong</strong>\n <i>italic</i>\n<em>em</em>\n<u>underline</u>\n<ins>ins</ins>\n<strike>strike</strike>\n<a href=\"https://www.leobreda.net/\">https://www.leobreda.net/</a>\n<code>code</code>\n<pre>pre lorem ipsum  samet   dolor</pre>"
}

inline_keyboard

Criam botões abaixo da caixa de texto, que ao clicá-los o valor é retornado ao chat como texto.

"one_time_keyboard":true para que os botões desapareçam após o clique

POST https://api.telegram.org/bot{{telegram_token}}/sendMessage

{
    "chat_id":"{{user_id}}",
    "text":"Bom dia! Tudo bem com você?",
    "reply_markup": {
            "one_time_keyboard":true,
        "resize_keyboard":true,
            "inline_keyboard": [[
                {
                    "text": "Sim"         
                }, 
                {
                    "text": "Não"         
                } 
                ]
            ]
        }
}

inline_keyboard + url

É possível transformar o botão em um link. Para isso:

"url":"https://leobreda.net"

POST https://api.telegram.org/bot{{telegram_token}}/sendMessage

{
    "chat_id":"{{user_id}}",
    "parse_mode":"HTML",
    "text":"Clique no botão abaixo para abrir o site",
    "reply_markup": {
        "resize_keyboard":true,
            "inline_keyboard": [[
                {
                    "text": "Abrir site",
                    "url":"http://leobreda.net"       
                }]]
            
        }
}

request_contact

Faz um pedido ao usuário para o envio do contato telefônico, ao clicar no botão "Enviar contato".

POST https://api.telegram.org/bot{{telegram_token}}/sendMessage

{
	"chat_id":"{{user_id}}",
	"parse_mode":"HTML",
	"text":"Qual o seu telefone?",
    "reply_markup": {
        "one_time_keyboard":true,
        "resize_keyboard":true,
            "keyboard": [[
                { "request_contact":true,
                    "text": "Enviar contato",
                    "callback_data": "aaaaa"            
                }, 
                {
                    "text": "Não desejo informar",
                    "callback_data": "bbbbb"            
                } 
                ]
            ]
        }
}

request_location

Faz um pedido ao usuário para o envio de sua localização, ao clicar no botão "Enviar localização"

POST https://api.telegram.org/bot{{telegram_token}}/sendMessage

{
	"chat_id":"{{user_id}}",
	"parse_mode":"HTML",
	"text":"Qual o seu telefone?",
    "reply_markup": {
        "one_time_keyboard":true,
        "resize_keyboard":true,
            "keyboard": [[
                { "request_contact":true,
                    "text": "Enviar contato"           
                }, 
                {
                    "text": "Não desejo informar"          
                } 
                ]
            ]
        }
}

sendPool

São mensagens no formato de enquete, com possibilidade de resposta anônima, identificada, única/múltipla escolha e cronometrada.

Enquete anônima

Onde o BOT não consegue identificar quem respondeu o quê...

"is_anonymous":true

POST https://api.telegram.org/bot{{telegram_token}}/sendPoll

{
	"chat_id":"{{user_id}}",
	"question":"Qual o seu Estado?",
	"options":["Acre","Minas Gerais","Paraná","Rio de Janeiro","São Paulo","Tocantins"],
    "is_anonymous":true,
	"allows_multiple_answers":false
}

Enquete identificada

Onde o BOT consegue identificar quem respondeu o quê...

"is_anonymous":false

POST https://api.telegram.org/bot{{telegram_token}}/sendPoll
{
    "chat_id":"{{user_id}}",
    "question":"Qual a sua cor favorita?",
    "options":["Preto","Amarelo","Azul","Branco","Cinza","Roxo"],
    "is_anonymous":false,
    "allows_multiple_answers":false
}

Múltipla escolha

Onde o usuário possa responder mais de uma resposta.

"allows_multiple_answers":true

POST https://api.telegram.org/bot{{telegram_token}}/sendPoll
{
    "chat_id":"{{user_id}}",
    "question":"Selecione as suas frutas favoritas?",
    "options":["Mamão","Pera","Maçã","Banana","Abacaxi","Kiwi"],
    "allows_multiple_answers":true
}

Única escolha

Apenas uma resposta é aceita.

"allows_multiple_answers":false

POST https://api.telegram.org/bot{{telegram_token}}/sendPoll
{
    "chat_id":"{{user_id}}",
    "question":"Qual o seu sexo?",
    "options":["Masculino","Feminino"],
    "allows_multiple_answers":false
}

Cronometrada

O usuário tem 60 segundos para responder. Caso ultrapasse o tempo para responder, a questão é encerrada.

"open_period":"60"

POST https://api.telegram.org/bot{{telegram_token}}/sendPoll
{
    "chat_id":"{{user_id}}",
    "question":"Qual o seu seu dia preferido? Esta pergunta encerra em 60 segundos",
    "options":["Domingo","Segunda-feira","Terça-feira","Quarta-feira","Quinta-feira","Sexta-feira","Sábado"],
    "allows_multiple_answers":false,
    "open_period":"60"
}

sendDocument

Envio de arquivos ZIP, PDF, XLS, DOC, etc

O parâmetro caption é opcional

POST https://api.telegram.org/bot{{telegram_token}}/sendDocument

{
    "chat_id":"{{user_id}}",
    "document":"https://leobreda.net/download/lorem-ipsum.pdf",
    "caption":"Lorem Ipsum samet dolor"
}

sendMediaGroup

Possibilita o envio de conteúdo multimídia (imagem ou vídeo).

O parâmetro media é um array, portanto, é possível passar mais de um arquivo em uma única requisição.

Envio de imagem

"type":"photo"

POST https://api.telegram.org/bot{{telegram_token}}/sendMediaGroup

{
    "chat_id":"{{user_id}}",
    "media":[{"type":"photo","media":"https://telegram.org/img/t_logo.png"}]
}

Envio de múltiplas imagens

POST https://api.telegram.org/bot{{telegram_token}}/sendMediaGroup

{
    "chat_id":"{{user_id}}",
    "media":[{"type":"photo","media":"https://telegram.org/img/t_logo.png"},
    {"type":"photo","media":"https://core.telegram.org/file/811140934/1/tbDSLHSaijc/fdcc7b6d5fb3354adf"},
    {"type":"photo","media":"https://telegram.org/file/464001796/3/RuL3KG9PxoQ.32309.png/9492993f15dad7ef3c"}]
}

Envio de vídeo

"type":"video"

POST https://api.telegram.org/bot{{telegram_token}}/sendMediaGroup

{
    "chat_id":"{{user_id}}",
    "media":[{"type":"video","media":"https://leobreda.net/download/nodemcu-hello-world.mp4"}]
}

Enfim, os métodos apresentados por aqui é apenas um resumo das principais funcionalidades disponibilizadas pela API do Telegram. A relação completa se encontra no link https://core.telegram.org/bots/api/

Acessar todos os artigos »