Telegram(Edição)

Visão Geral

Recursos da Biblioteca Telegram Bot API Utilizados no Omnichannel

Biblioteca:

node-telegram-bot-api

Versão: 0.61.0

Métodos da API Utilizados

1. Configuração e Inicialização

new TelegramBot(token, options)

getSession(config: TelegramConfigParams) {
  const { token } = config
  return new TelegramBot(token, { polling: false })
}

Uso: Criação da instância do bot
Token: Obtido da configuração do canal

1.1 Configuração de Webhook

setWebHook(url, options)

async setWebHook(url: string, platformChannelsConfig: PlatformChannelsConfig) {
  const telegramBot = await this.getSession(platformChannelsConfig.params)
  return await telegramBot.setWebHook(url)
}

Funcionalidade: Configuração de webhook para receber mensagens
URL: Endpoint do Omnichannel para processar updates

2. Envio de Mensagens

sendMessage(chatId, text, options)

response = await telegramBot.sendMessage(to, text, { 
  ...reply, 
  parse_mode: 'Markdown' 
})

Funcionalidade: Envio de mensagens de texto
Parse Mode: Markdown para formatação
Reply: Suporte a mensagens citadas

Retorno:

Estrutura da Mensagem

{
  message_id: number,
  from: TelegramMessageSender,
  date: number,
  text?: string,
  caption?: string,
  photo?: TelegramMessageMedia[],
  voice?: TelegramMessageMedia,
  document?: TelegramMessageMedia,
  location?: LocationDto,
  reply_to_message?: TelegramReplyMessage
}

SendPhoto

sendPhoto(chatId, photo, options)

response = await telegramBot.sendPhoto(to, mediaUri, { ...reply })

Funcionalidade: Envio de imagens
Mídia: Suporte a URLs e file_id
Reply: Mensagens citadas suportadas

SendVideo:

sendVideo(chatId, video, options)

response = await telegramBot.sendVideo(to, mediaUri, { ...reply })

Funcionalidade: Envio de vídeos
Formatos: MP4 e outros formatos de vídeo

SendVoice:

sendVoice(chatId, voice, options)

response = await telegramBot.sendVoice(to, mediaUri, { ...reply })

Funcionalidade: Envio de áudios/voice messages
Formatos: OGG e outros formatos de áudio

SendDocument:

sendDocument(chatId, document, options)

response = await telegramBot.sendDocument(to, mediaUri, { ...reply })

Funcionalidade: Envio de documentos
Tipos: PDF, ZIP, GIF e outros arquivos

3. Gerenciamento de Arquivos

getFileLink(fileId)

incomingMessage.message.media = {
  uri: await telegramBot.getFileLink(file_id),
  contentType: mime_type,
  fileName: file_name,
}

Funcionalidade: Obter URL de download de arquivos
Uso: Conversão de file_id para URL acessível

Estruturas de Dados Recebidas

Update Structure

{
  update_id: number,
  message?: TelegramMessageDetail,
  edited_message?: TelegramMessageDetail
}

Message Structure

{
  message_id: number,
  from: TelegramMessageSender,
  date: number,
  text?: string,
  caption?: string,
  photo?: TelegramMessageMedia[],
  voice?: TelegramMessageMedia,
  document?: TelegramMessageMedia,
  location?: LocationDto,
  reply_to_message?: TelegramReplyMessage
}

Media Structure

{
  file_id: string,
  file_name?: string,
  mime_type?: string,
  file_size?: number,
  width?: number,
  height?: number
}

Recursos Implementados

Funcionalidades Ativas

Recebimento de Mensagens

✅ Mensagens de texto
✅ Fotos (array de diferentes resoluções)
✅ Vídeos
✅ Áudios/Voice messages
✅ Documentos (PDF, ZIP, etc.)
✅ Localização (latitude/longitude)
✅ Mensagens citadas (reply_to_message)
✅ Mensagens editadas (edited_message)

Envio de Mensagens

✅ Texto com formatação Markdown
✅ Imagens via URL
✅ Vídeos via URL
✅ Áudios via URL
✅ Documentos via URL
✅ Mensagens citadas (reply_to_message_id)
✅ Adição de nome do usuário nas mensagens

Detecção de Tipos de Mídia

if (mimetype.match(/gif|zip|pdf/)) {
  // sendDocument
} else if (mimetype.match('image')) {
  // sendPhoto
} else if (mimetype.match('audio')) {
  // sendVoice
} else if (mimetype.match('video')) {
  // sendVideo
}

Configuração Automática

✅ Setup automático de webhook em desenvolvimento
✅ Validação de token e configuração

❌ Funcionalidades Não Implementadas

Recursos Disponíveis mas Não Utilizados

❌
```
deleteMessage()
```
- Exclusão de mensagens
❌
```
sendMessageReaction()
```
- Reações em mensagens
❌
```
deleteMessageReaction()
```
- Remoção de reações
❌
```
sendProactiveMessage()
```
- Mensagens proativas
❌
```
startConversation()
```
- Início de conversas (retorna erro)

Outros Recursos da API Não Implementados

❌ Inline keyboards
❌ Custom keyboards
❌ Polls/enquetes
❌ Stickers
❌ Games
❌ Payments
❌ Passport data
❌ Chat actions (typing, uploading, etc.)
❌ Group management
❌ Channel management
❌ Bot commands menu

Fluxo de Processamento

Recebimento (Webhook → Incoming Message)

Webhook recebe update do Telegram
Validação da estrutura via
```
TelegramMessageDto
```
Mapeamento via
```
telegramPayloadToIncomingMessage
```
Conversão de
```
file_id
```
para URL via
```
getFileLink
```
Processamento da mensagem no sistema

Envio (Outgoing Message → Telegram)

Recebimento via
```
SendMessageDto
```
Detecção do tipo de mídia via MIME type
Seleção do método apropriado da API
Envio com suporte a reply
Retorno do
```
message_id
```