Telegram

ACTIVEVersão 1.1.0Telegram

Envie e receba mensagens por um bot do Telegram.

Ver como JSON

Pré-requisitos

• uma conta no Telegram;
• permissão no iBPMS para criar ou selecionar conexões;
• um bot criado pelo BotFather;
• um token válido armazenado como credencial.

telegram.json

{
  "schemaVersion": 1,
  "key": "telegram",
  "name": "Telegram",
  "description": "Envie e receba mensagens por um bot do Telegram.",
  "category": "communication",
  "vendor": "Telegram",
  "version": "1.1.0",
  "status": "ACTIVE",
  "credentials": [
    {
      "type": "API_KEY",
      "secretLabel": "Token do bot",
      "secretPlaceholder": "123456789:AAExxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "helpText": "Fale com o @BotFather no Telegram, use /newbot e cole aqui o token que ele devolver.",
      "helpUrl": "https://t.me/BotFather"
    }
  ],
  "actions": [
    {
      "key": "message.send",
      "name": "Enviar mensagem",
      "description": "Envia uma mensagem de texto para um chat.",
      "inputs": [
        {
          "key": "chatId",
          "label": "Chat",
          "type": "TEXT",
          "required": true,
          "description": "ID numérico do chat ou @canal."
        },
        {
          "key": "text",
          "label": "Mensagem",
          "type": "TEXT",
          "required": true,
          "description": "Aceita expressões do processo."
        }
      ],
      "outputs": [
        {
          "key": "messageId",
          "label": "Message Id",
          "type": "OUTPUT",
          "required": false
        }
      ]
    }
  ],
  "triggers": [
    {
      "key": "message.received",
      "name": "Mensagem recebida",
      "description": "Dispara quando o bot recebe uma mensagem. A inscrição é automática (setWebhook) — atenção: o Telegram permite apenas UM webhook por bot.",
      "mode": "PUSH",
      "exclusiveByConnection": true,
      "inputs": [
        {
          "key": "commands",
          "label": "Comandos sugeridos do bot",
          "type": "KEY_VALUE",
          "required": false,
          "description": "Aparecem no menu do Telegram quando o usuário digita '/'. O nome aceita até 32 caracteres, só letras minúsculas, números e _. Opcional — o bot recebe qualquer comando digitado, cadastrado ou não."
        }
      ],
      "events": [
        {
          "type": "MESSAGE_RECEIVED",
          "messageType": "TEXT"
        },
        {
          "type": "MESSAGE_RECEIVED",
          "messageType": "IMAGE"
        },
        {
          "type": "MESSAGE_RECEIVED",
          "messageType": "AUDIO"
        },
        {
          "type": "MESSAGE_RECEIVED",
          "messageType": "VIDEO"
        },
        {
          "type": "MESSAGE_RECEIVED",
          "messageType": "DOCUMENT"
        },
        {
          "type": "MESSAGE_RECEIVED",
          "messageType": "LOCATION"
        },
        {
          "type": "MESSAGE_RECEIVED",
          "messageType": "OTHER"
        }
      ]
    }
  ]
}

Criando um bot

1. Abra o @BotFather no Telegram.
2. Execute /newbot e informe nome e username.
3. Copie o token retornado e guarde-o como segredo.

Proteja o token

O token concede controle sobre o bot. Não o coloque em Markdown, regras, capturas de tela ou logs; armazene-o somente no campo de credencial do iBPMS.

Credenciais

Credencial

Token do bot

API_KEY

Fale com o @BotFather no Telegram, use /newbot e cole aqui o token que ele devolver.

Campo	Formato esperado
Token do bot	123456789:AAExxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Abrir guia do provedor

Ações disponíveis

Ação

Enviar mensagem

message.send

Envia uma mensagem de texto para um chat.

Entradas

Campo	Tipo	Obrigatório	Descrição
chatIdChat	TEXT	Sim	ID numérico do chat ou @canal.
textMensagem	TEXT	Sim	Aceita expressões do processo.

Saídas

Campo	Tipo	Obrigatório	Descrição
messageIdMessage Id	OUTPUT	Não	—

Chamada

{
  "connection": "telegram-producao",
  "operation": "message.send",
  "inputs": {
    "chatId": "{{ context.chatId }}",
    "text": "{{ context.text }}"
  }
}

Resposta

{
  "messageId": 123
}

Triggers disponíveis

Trigger

Mensagem recebida

PUSHConexão exclusiva

Dispara quando o bot recebe uma mensagem. A inscrição é automática (setWebhook) — atenção: o Telegram permite apenas UM webhook por bot.

Configuração

Campo	Tipo	Obrigatório	Descrição
commandsComandos sugeridos do bot	KEY_VALUE	Não	Aparecem no menu do Telegram quando o usuário digita '/'. O nome aceita até 32 caracteres, só letras minúsculas, números e _. Opcional — o bot recebe qualquer comando digitado, cadastrado ou não.

Eventos normalizados

• MESSAGE_RECEIVED · TEXT
• MESSAGE_RECEIVED · IMAGE
• MESSAGE_RECEIVED · AUDIO
• MESSAGE_RECEIVED · VIDEO
• MESSAGE_RECEIVED · DOCUMENT
• MESSAGE_RECEIVED · LOCATION
• MESSAGE_RECEIVED · OTHER

Evento recebido

{
  "event": "MESSAGE_RECEIVED",
  "data": {
    "commands": "{{ context.commands }}"
  }
}

Limitações

• uma conexão que usa o trigger de mensagens recebidas é exclusiva, porque o Telegram aceita um webhook por bot;
• o destinatário deve ser um identificador de chat válido ou um canal acessível pelo bot;
• limites e políticas de envio do Telegram continuam se aplicando;
• alterações feitas diretamente no BotFather podem exigir nova validação da conexão.

Erros comuns

Sintoma	Possível causa	Correção
Não autorizado	Token inválido ou revogado	Gere um token novo e atualize a credencial.
Chat não encontrado	`chatId` incorreto ou bot sem acesso	Confirme o identificador e adicione o bot ao chat.
Eventos não chegam	Outro webhook substituiu o endpoint	Reative o trigger usando uma conexão exclusiva.
Mensagem não enviada	Campo `text` vazio ou expressão inválida	Inspecione os inputs resolvidos na execução.

Veja também

• Todos os conectores
• Integrações
• Solução de problemas