Ir para o conteúdo principal

Telegram(Edição)

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
  
      .
      .
      .
  
   } 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.

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?: SetWebHookOptions): Promise<boolean>

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: string,              // URL HTTPS do webhook (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 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.

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 Message Structure (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

  @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()
  reply_to_message?: TelegramReplyMessage  // Mensagem citada
}

4.3 User Structure (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 PhotoSize Structure (Fotos)

interface PhotoSize {
  file_id: string,
  file_unique_id: string,
  width: number,
  height: number,
  file_size?: number
}

Descrição: Representa uma foto em uma resolução específica. O Telegram envia fotos em múltiplas resoluções (thumbnail, média, alta).

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.)

  @IsOptional()
  @IsNumber()
  width?: number           // Largura em pixels

  @IsOptional()
  @IsNumber()
  height?: number          // Altura em pixels

  @IsOptional()
  @IsNumber()
  file_size?: number       // Tamanho em bytes
}

4.5 Location Structure (Localizaçã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.

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() 
  }
}
typescript

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.