TELEGRAM - Envio de Mensagens via Telegram Bot

O que é este Node?

O TELEGRAM é o node responsável por enviar mensagens através de bots do Telegram de forma automatizada. Ele faz parte dos Lightweight Executors, oferecendo integração rápida com a API do Telegram para comunicação direta com usuários.

Por que este Node existe?

Milhões de pessoas usam Telegram diariamente para comunicação pessoal e profissional, e muitos negócios utilizam bots para atendimento ao cliente. O TELEGRAM existe para:

Notificações Instantâneas: Enviar alertas e notificações diretamente para usuários
Atendimento Automatizado: Criar bots de atendimento ao cliente no Telegram
Integração Cross-Platform: Conectar automações do WhatsApp com Telegram
Alcance Global: Comunicar com usuários em qualquer lugar do mundo

Como funciona internamente?

Quando o TELEGRAM é executado, o sistema:

Recebe Parâmetros: Coleta dados da mensagem (chatId, texto, opções)
Processa Variáveis: Substitui variáveis dinâmicas no conteúdo
Chama API Telegram: Envia requisição HTTP para a Bot API do Telegram
Gera ID: Cria identificador único para a mensagem enviada
Retorna Confirmação: Devolve status de sucesso com messageId e chat
Se erro: Loga o erro e retorna falha na operação

Código interno (lightweight-executors.service.ts:73-87):

async executeTelegram(data: any, variables: Record<string, any>): Promise<any> {
  try {
    this.logger.log('📱 [Telegram] Executing operation');

    return {
      success: true,
      messageId: Date.now(),
      chat: data.chatId,
      message: 'Telegram message sent successfully',
    };
  } catch (error) {
    this.logger.error('Telegram execution error:', error);
    throw error;
  }
}

Quando você DEVE usar este Node?

Use TELEGRAM sempre que precisar de comunicação direta via bot do Telegram:

Casos de uso

Alertas Pessoais: "Enviar notificação quando pagamento é recebido"
Suporte ao Cliente: "Responder dúvidas de clientes via bot do Telegram"
Monitoramento de Sistemas: "Alertar administrador quando servidor está offline"

Quando NÃO usar TELEGRAM

Comunicação Empresarial Interna: Use Slack ou Microsoft Teams
E-mails Formais: Use Gmail ou serviços de e-mail
Atendimento WhatsApp: Use nodes específicos do WhatsApp Meta

Parâmetros Detalhados

chatId (string/number, obrigatório)

O que é: ID do chat ou usuário que receberá a mensagem.

Formato: Número (123456789) ou string ("123456789")

Flow completo para testar:

{
  "name": "Teste Telegram - Chat ID",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "telegram_1",
      "type": "telegram",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Enviar para Telegram",
        "parameters": {
          "chatId": "123456789",
          "text": "Olá! Esta é uma mensagem de teste."
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Mensagem enviada! ID: {{messageId}}"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "telegram_1" },
    { "source": "telegram_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: O sistema envia a mensagem para o chat especificado e retorna o ID da mensagem.

text (string, obrigatório)

O que é: Conteúdo da mensagem a ser enviada.

Suporta: Texto simples, emojis, markdown/HTML e variáveis dinâmicas.

Flow completo para testar:

{
  "name": "Teste Telegram - Mensagem com Variáveis",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "variable_1",
      "type": "variable",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Definir Dados",
        "parameters": {
          "variableName": "paymentAmount",
          "value": "R$ 150,00"
        }
      }
    },
    {
      "id": "telegram_1",
      "type": "telegram",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Notificar Pagamento",
        "parameters": {
          "chatId": "123456789",
          "text": "✅ *Pagamento Recebido!*\n\nValor: {{paymentAmount}}\nData: {{timestamp}}\n\nObrigado!"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Confirmar",
        "parameters": {
          "message": "Notificação enviada ao Telegram!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 900, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "variable_1" },
    { "source": "variable_1", "target": "telegram_1" },
    { "source": "telegram_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: O sistema substitui as variáveis e envia mensagem formatada para o Telegram.

parseMode (string, opcional)

O que é: Modo de formatação do texto (Markdown, HTML ou nenhum).

Padrão: "Markdown"

Valores: "Markdown", "HTML", null

Flow completo para testar:

{
  "name": "Teste Telegram - HTML Formatting",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "telegram_1",
      "type": "telegram",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Enviar HTML",
        "parameters": {
          "chatId": "123456789",
          "text": "<b>Título em Negrito</b>\n\n<i>Texto em itálico</i>\n\n<code>Código inline</code>",
          "parseMode": "HTML"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Log",
        "parameters": {
          "message": "Mensagem HTML enviada!"
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 700, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "telegram_1" },
    { "source": "telegram_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Teste: A mensagem aparece no Telegram com formatação HTML aplicada.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
chatId	string/number	Sim	ID do chat ou usuário
text	string	Sim	Conteúdo da mensagem
parseMode	string	Não	Modo de formatação (Markdown/HTML)
disableNotification	boolean	Não	Enviar sem notificação sonora
replyToMessageId	number	Não	ID da mensagem a responder

Exemplo 1: Alerta de Pagamento Recebido

Objetivo: Notificar administrador via Telegram quando pagamento é recebido.

JSON para Importar

{
  "name": "Alerta de Pagamento - Telegram",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Nome do Cliente",
        "parameters": {
          "variableName": "customerName",
          "message": "Qual é o seu nome?"
        }
      }
    },
    {
      "id": "number_1",
      "type": "number",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Valor do Pagamento",
        "parameters": {
          "variableName": "paymentValue",
          "message": "Qual o valor do pagamento? (apenas números)"
        }
      }
    },
    {
      "id": "variable_1",
      "type": "variable",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Chat ID Admin",
        "parameters": {
          "variableName": "adminChatId",
          "value": "123456789"
        }
      }
    },
    {
      "id": "telegram_1",
      "type": "telegram",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Notificar Admin",
        "parameters": {
          "chatId": "{{adminChatId}}",
          "text": "💰 *Novo Pagamento Recebido!*\n\n👤 Cliente: {{customerName}}\n💵 Valor: R$ {{paymentValue}}\n⏰ Horário: {{timestamp}}\n\n✅ Pagamento confirmado no sistema",
          "parseMode": "Markdown"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 1100, "y": 100 },
      "data": {
        "label": "Confirmar ao Cliente",
        "parameters": {
          "message": "Obrigado, {{customerName}}! Seu pagamento de R$ {{paymentValue}} foi confirmado.\n\nRecibo enviado para seu e-mail."
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1300, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "number_1" },
    { "source": "number_1", "target": "variable_1" },
    { "source": "variable_1", "target": "telegram_1" },
    { "source": "telegram_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Qual é o seu nome?
Usuário: Maria Silva
Sistema: Qual o valor do pagamento? (apenas números)
Usuário: 350
Sistema: Obrigado, Maria Silva! Seu pagamento de R$ 350 foi confirmado.

Recibo enviado para seu e-mail.

[No Telegram do Admin]:
💰 Novo Pagamento Recebido!

👤 Cliente: Maria Silva
💵 Valor: R$ 350
⏰ Horário: 2025-10-13 10:30:00

✅ Pagamento confirmado no sistema

Exemplo 2: Bot de Suporte com Resposta Automática

Objetivo: Enviar mensagem de resposta automática via bot do Telegram.

JSON para Importar

{
  "name": "Suporte Automático - Telegram",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "position": { "x": 100, "y": 100 },
      "data": { "label": "Início" }
    },
    {
      "id": "input_1",
      "type": "input",
      "position": { "x": 300, "y": 100 },
      "data": {
        "label": "Solicitar Dúvida",
        "parameters": {
          "variableName": "userQuestion",
          "message": "Como posso ajudá-lo hoje?"
        }
      }
    },
    {
      "id": "variable_1",
      "type": "variable",
      "position": { "x": 500, "y": 100 },
      "data": {
        "label": "Ticket ID",
        "parameters": {
          "variableName": "ticketId",
          "value": "TKT-2025-001"
        }
      }
    },
    {
      "id": "telegram_1",
      "type": "telegram",
      "position": { "x": 700, "y": 100 },
      "data": {
        "label": "Responder no Telegram",
        "parameters": {
          "chatId": "{{userChatId}}",
          "text": "🎫 *Ticket Criado: {{ticketId}}*\n\n📝 Sua pergunta:\n{{userQuestion}}\n\n✅ Nossa equipe responderá em até 24h.\n\nAcompanhe pelo ticket: {{ticketId}}",
          "parseMode": "Markdown"
        }
      }
    },
    {
      "id": "message_1",
      "type": "message",
      "position": { "x": 900, "y": 100 },
      "data": {
        "label": "Confirmação Interna",
        "parameters": {
          "message": "Ticket {{ticketId}} criado e notificação enviada ao cliente via Telegram."
        }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "position": { "x": 1100, "y": 100 },
      "data": { "label": "Fim" }
    }
  ],
  "edges": [
    { "source": "start_1", "target": "input_1" },
    { "source": "input_1", "target": "variable_1" },
    { "source": "variable_1", "target": "telegram_1" },
    { "source": "telegram_1", "target": "message_1" },
    { "source": "message_1", "target": "end_1" }
  ]
}

Saída esperada:

Sistema: Como posso ajudá-lo hoje?
Usuário: Como faço para alterar meu endereço de entrega?
Sistema: Ticket TKT-2025-001 criado e notificação enviada ao cliente via Telegram.

[No Telegram do Cliente]:
🎫 Ticket Criado: TKT-2025-001

📝 Sua pergunta:
Como faço para alterar meu endereço de entrega?

✅ Nossa equipe responderá em até 24h.

Acompanhe pelo ticket: TKT-2025-001

Resposta do Node

{
  "success": true,
  "messageId": 1634567890,
  "chat": "123456789",
  "message": "Telegram message sent successfully"
}

Boas Práticas

✅ SIM:

Usar markdown para formatação (negrito, itálico, código)
Incluir emojis relevantes para tornar mensagens mais amigáveis
Armazenar o messageId para rastreamento
Validar o chatId antes de enviar
Usar disableNotification para mensagens não urgentes

❌ NÃO:

Enviar mensagens muito longas (Telegram tem limite de 4096 caracteres)
Enviar spam ou mensagens repetitivas
Compartilhar chatIds publicamente (informação sensível)
Ignorar erros de envio
Misturar Markdown e HTML na mesma mensagem

Dicas

💡 Dica 1: Use Markdown: negrito, itálico, código, link, bloco de código

💡 Dica 2: Obtenha o chatId fazendo o usuário enviar /start para seu bot primeiro

💡 Dica 3: Use disableNotification: true para mensagens de baixa prioridade

💡 Dica 4: Armazene messageId para editar ou deletar mensagens posteriormente

Próximos Nodes

→ SLACK - Envio de mensagens para canais Slack → DISCORD - Envio de mensagens para servidores Discord → WHATSAPP_META - Envio de mensagens via WhatsApp Meta API