Telegram
1. INFORMAÇÕES GERAIS
1.1 Biblioteca Utilizada
-
Nome: node-telegram-bot-api
-
Versão: 0.61.0
-
Descrição: Biblioteca JavaScript para interagir com a API oficial do Telegram Bot, permitindo criar bots que podem enviar e receber mensagens, mídia e outros tipos de conteúdo.
1.2 Configuração Base
class TelegramConfigParams {
@IsString()
@IsNotEmpty()
token: string // Token do bot obtido via @BotFather
}
Descrição: Configuração mínima necessária contendo apenas o token do bot, que é obtido através do @BotFather no Telegram.
2. MÉTODOS DE ENVIO DE MENSAGENS
2.1 sendMessage()
sendMessage(session: Session, payload: SendMessagePayload): Promise<any>Descrição: Envia mensagens de texto simples com suporte a formatação Markdown e mensagens citadas.
2.1.1 Estrutura de Entrada
{
to: string //Usuario Destino
body?: string //Conteudo da Mensagem
userName?: string // Nome de Usuario
mediaUri?: string // URL de midia
quotedMessage?:{ // Mensagem a ser respondida
id:string; //Id da mensagem original a ser respondida
}
2.1.2 Implementação no Sistema
async sendMessage(session: Session, payload: SendMessagePayload): Promise<any> {
const { to, body, mediaUri, userName } = payload
const text = userName ? Utils.addUserNameToMessage(userName, body) : body
const telegramBot = this.getSession(session.channel.params as TelegramConfigParams)
let reply = {}
if (Number(payload?.quotedMessage?.id)) {
reply = { reply_to_message_id: Number(payload.quotedMessage.id) }
}
let response
.if (mediaUri) {
const splitMediaUri = mediaUri.split('/')
const fileName = splitMediaUri[splitMediaUri.length - 1]
const mimetype: string = mime.lookup(fileName.split('?')[0])
let response
if (mimetype.match(/gif|zip|pdf/)) {
response = await telegramBot.sendDocument(to, mediaUri, { ...reply })
return response?.message_id?.toString()
} else if (mimetype.match('image')) {
response = await telegramBot.sendPhoto(to, mediaUri, { ...reply })
return response?.message_id?.toString()
} else if (mimetype.match('audio')) {
response = await telegramBot.sendVoice(to, mediaUri, { ...reply })
return response?.message_id?.toString()
} else if (mimetype.match('video')) {
response = await telegramBot.sendVideo(to, mediaUri, { ...reply })
return response?.message_id?.toString()
}
} else {
response = await telegramBot.sendMessage(to, text, { ...reply, parse_mode: 'Markdown' })
}
return response?.message_id?.toString()
}2.1.3 Estrutura de Retorno
{
message_id: number, // ID único da mensagem enviada
}
2.2 sendPhoto()
sendPhoto(to, mediaUri, {...reply})
Descrição: Envia imagens (JPEG, PNG, GIF até 10MB) com caption opcional e suporte a mensagens citadas.
2.2.1 Estrutura de Entrada
{
to, // chatId
mediaUri, // URL media
{ reply_to_message_id:} //Id do reply
}
2.2.2 Implementação no Sistema
if (mimetype.match('image')) {
response = await telegramBot.sendPhoto(to, mediaUri, { ...reply })
}
2.3 sendVideo()
sendVideo(to, mediaUri, { ...reply })
Descrição: Envia vídeos (MP4 até 50MB) com suporte a thumbnail, duração e dimensões personalizadas.
2.3.1 Estrutura de Entrada
{
to, // chatId
mediaUri, // URL media
{ reply_to_message_id:} //Id do reply
}
2.3.2 Implementação no Sistema
if (mimetype.match('video')) {
response = await telegramBot.sendVideo(to, mediaUri, { ...reply })
}
2.4 sendVoice()
sendVoice(to, mediaUri, { ...reply })
Descrição: Envia mensagens de voz (OGG com codec OPUS) que aparecem como áudio reproduzível no cliente Telegram.
2.4.1 Estrutura de Entrada
{
to, // chatId
mediaUri, // URL media
{ reply_to_message_id:} //Id do reply
}
2.4.2 Implementação no Sistema
if (mimetype.match('audio')) {
response = await telegramBot.sendVoice(to, mediaUri, { ...reply })
}
2.5 sendDocument()
sendDocument(to, mediaUri, { ...reply })
Descrição: Envia arquivos gerais (PDF, ZIP, documentos até 50MB) que são baixáveis pelo usuário.
2.5.1 Estrutura de Entrada
{
to, // chatId
mediaUri, // URL media
{ reply_to_message_id:} //Id do reply
}
2.5.2 Implementação no Sistema
if (mimetype.match(/gif|zip|pdf/)) {
response = await telegramBot.sendDocument(to, mediaUri, { ...reply })
}
3. MÉTODOS DE RECEBIMENTO E PROCESSAMENTO
3.1 getFileLink()
getFileLink(fileId: string): Promise<string>
Descrição: Converte um file_id recebido via webhook em uma URL direta para download do arquivo, válida por 1 hora.arquivo.
3.1.1 Estrutura de Entrada
{
fileId: string // ID único do arquivo fornecido pelo Telegram
}
3.1.2 Implementação no Sistema
incomingMessage.message.media = {
uri: await telegramBot.getFileLink(file_id),
contentType: mime_type,
fileName: file_name,
}
3.1.3 Estrutura de Retorno
string // URL direta HTTPS para download do arquivo
3.2 setWebHook()
setWebHook(url: string, options?:platformChannelsConfig: SetWebHookOptions)PlatformChannelsConfig): Promise<booleanany>
Descrição: Configura o endpoint webhook onde o Telegram enviará todas as atualizações do bot (mensagens, edições, etc.).
3.2.1 Estrutura de Entrada
{
url:await string,telegramService.setWebHook(
"https://meuservidor.com/telegram/webhook",
platformChannelsConfig // URLobjeto HTTPScontendo params com o token do webhookbot
(máx. 256 caracteres)
options?: {
certificate?: string, // Certificado SSL público (se necessário)
max_connections?: number, // Máx. conexões simultâneas (1-100)
allowed_updates?: string[] // Tipos de update a receber
})
}
3.2.2 Implementação no Sistema
async setWebHook(url: string, platformChannelsConfig: PlatformChannelsConfig) {
const telegramBot = await this.getSession(platformChannelsConfig.params)
return await telegramBot.setWebHook(url)
}
4. EVENTOS E ESTRUTURAS DE WEBHOOK
4.1 Estrutura de Update Structure (Evento Principal)
interface Update {
update_id: number,
message?: Message,
edited_message?: Message,
channel_post?: Message,
edited_channel_post?: Message
}
Descrição: Estrutura principal que encapsula todas as atualizações enviadas pelo Telegram via webhook, incluindo mensagens novas e editadas.editadas (Apresentado somente os utilizados).
4.1.1 Implementação no DTO
export class TelegramMessageDto {
@IsNumber()
update_id: number // ID sequencial único do update
@IsOptional()
@ValidateNested()
@Type(() => TelegramMessageDetail)
message?: TelegramMessageDetail // Nova mensagem recebida
@IsOptional()
@ValidateNested()
@Type(() => TelegramMessageDetail)
edited_message?: TelegramMessageDetail // Mensagem editada
}
4.2 MessageEstrutura Structurede Mensagem (Evento de Mensagem)
interface Message {
message_id: number,
from?: User,
date: number,
chat: Chat,
text?: string,
caption?: string,
photo?: PhotoSize[],
video?: Video,
voice?: Voice,
document?: Document,
location?: Location,
reply_to_message?: Message
}
Descrição: Estrutura completa de uma mensagem, contendo metadados, conteúdo e informações do remetente e chat.
4.2.1 Implementação no DTO
export class TelegramMessageDetail {
@IsNumber()
message_id: number // ID único da mensagem no chat
@ValidateNested()
@Type(() => TelegramMessageSender)
from: TelegramMessageSender // Informações do remetente
@IsOptional()
@IsNumber()
edit_date?: number // Data edição
@IsNumber()
date: number // Timestamp Unix da mensagem
@IsString()
@IsOptional()
text?: string // Texto da mensagem (se for texto)
@IsString()
@IsOptional()
caption?: string // Legenda de mídia
@IsArray()
@IsOptional()
photo?: TelegramMessageMedia[] // Array de fotos em diferentes resoluções
@IsOptional()
voice?: TelegramMessageMedia // Mensagem de voz
@IsOptional()
document?: TelegramMessageMedia // Documento anexado
@IsOptional()
location?: LocationDto // Localização compartilhada
@IsOptional()
@ValidateNested()
@Type(() => TelegramChatDto)
chat?: TelegramChatDto // Dados de contato
@IsOptional()
reply_to_message?: TelegramReplyMessage // Mensagem citada
}
4.3 UserEstrutura Structuredo Usuario (Remetente)
interface User {
id: number,
is_bot: boolean,
first_name: string,
last_name?: string,
username?: string,
language_code?: string
}
Descrição: Informações completas do usuário que enviou a mensagem, incluindo identificação única e dados de perfil.
4.3.1 Implementação no DTO
export class TelegramMessageSender {
@IsNumber()
id: number // ID único do usuário no Telegram
@IsBoolean()
is_bot: boolean // Indica se é um bot
@IsString()
first_name: string // Nome obrigatório
@IsString()
@IsOptional()
last_name?: string // Sobrenome opcional
@IsString()
@IsOptional()
username?: string // @username opcional
@IsString()
@IsOptional()
language_code?: string // Código do idioma (ex: 'pt-br')
}
4.4 PhotoSizeEstrutura Structurede (Fotos)Midia
interface PhotoSizeMedia {
file_id: string,
file_unique_id:file_name?: string,
width:mime_type?: string,
file_size?: number,
height:width?: number,
file_size?height?: number
}
Descrição: RepresentaEstrutura umade foto em uma resolução específica. O Telegram envia fotos em múltiplas resoluçõesmídia (thumbnail,foto, média,vídeo, alta).áudio, documento) recebida.
4.4.1 Implementação no DTO
export class TelegramMessageMedia {
@IsString()
file_id: string // ID único do arquivo (temporário)
@IsString()
@IsOptional()
file_name?: string // Nome original do arquivo
@IsString()
@IsOptional()
mime_type?: string // Tipo MIME (image/jpeg, video/mp4, etc.)Audio/PDF/ZIP/Video)
@IsOptional()
@IsNumber()
width?: number // Largura em pixels
@IsOptional()
@IsNumber()
height?: number // Altura em pixels
@IsOptional()
@IsNumber()
file_size?: number // Tamanho em bytes
}
4.5 LocationEstrutura Structurede (Localização)o.
interface Location {
longitude: number,
latitude: number,
live_period?: number,
heading?: number,
horizontal_accuracy?: number
}
Descrição: Coordenadas geográficas compartilhadas pelo usuário, com suporte a localização em tempo real e precisão.rio.
4.5.1 Implementação no DTO
export class LocationDto {
@IsString()
latitude: string // Latitude em graus decimais
@IsString()
longitude: string // Longitude em graus decimais
}
5. MAPEAMENTO DE EVENTOS
5.1 Mensagem Recebida (MESSAGE)
const incomingMessage: IncomingMessageDto = {
uid: payload.message.message_id.toString(),
sessionId: session._id,
platformConfigId: session.platformConfigId,
channelId: session.channelId,
source: MessageServiceEnum.telegram,
from: {
uid: data.from.id.toString(),
userName: `${data.from.first_name} ${data.from.last_name}`,
},
message: {
body: data?.text || payload?.message?.caption || '',
},
type: WebhookTypesEnum.MESSAGE,
}
Descrição: Converte uma mensagem recebida do Telegram para o formato padrão do Omnichannel, normalizando dados entre diferentes provedores.
5.2 Mensagem Editada (MESSAGE_UPDATE)
const status: WebhookStatusDto = {
platformConfigId,
channelId,
type: WebhookTypesEnum.MESSAGE_UPDATE,
payload: {
message: {
from: payload?.edited_message?.from?.id?.toString(),
to: payload?.edited_message?.chat?.id?.toString(),
messageId: payload?.edited_message?.message_id?.toString(),
status: WebhookStatusMessagesEnum.EDITED,
content: payload?.edited_message?.text || payload?.edited_message?.caption
}
}
}
Descrição: Processa mensagens editadas pelo usuário, criando um evento de atualização que pode ser enviado para a plataforma de destino.
5.3 Mídia Recebida
// Fotos - Seleciona a maior resolução disponível
if (data.photo?.length > 0) {
const { file_id, file_name, mime_type } = data.photo[data.photo.length - 1]
incomingMessage.message.media = {
uri: await telegramBot.getFileLink(file_id),
contentType: mime_type,
fileName: file_name,
}
}
// Documentos e Áudios - Processamento unificado
if (data.document || data.voice) {
incomingMessage.message.media = {
uri: await telegramBot.getFileLink(data.document?.file_id || data.voice?.file_id),
contentType: data.document?.mime_type || data.voice?.mime_type,
fileName: data.document?.file_name || data.voice?.file_name,
}
}
Descrição: Processa diferentes tipos de mídia, convertendo file_ids em URLs acessíveis e normalizando metadados.
5.4 Localização Recebida
if (data.location) {
incomingMessage.location = {
latitude: Number(data.location.latitude || 0),
longitude: Number(data.location.longitude || 0),
}
}
Descrição: Extrai coordenadas geográficas e as converte para o formato numérico padrão do sistema.
5.5 Mensagem Citada
if (payload?.message?.reply_to_message?.message_id) {
incomingMessage.message.quoted = {
id: payload.message.reply_to_message.message_id.toString()
}
}
Descrição: Identifica quando uma mensagem é uma resposta a outra mensagem, preservando a referência para contexto da conversa.
Esta documentação estruturada apresenta todos os recursos da biblioteca Telegram Bot API utilizados no projeto Omnichannel.
Para consulta e analise da lib consultar as seguintes documentações:
node-telegram-bot-api: https://github.com/yagop/node-telegram-bot-api
Telegram API Oficial: https://core.telegram.org/bots/api