EA MQL5 integrado ao Telegram (Parte 1): Envio de mensagens do MQL5 para o Telegram

Introdução

Este artigo aborda a integração do Telegram com o MetaTrader 5. Para realizar essa tarefa, criaremos um EA na linguagem MetaQuotes Language 5 (MQL5). Nosso objetivo principal é desenvolver um assistente de trading que opere em tempo real e nos mantenha informados sobre eventos por meio do chat no Telegram. O bot do Telegram que criaremos atuará como um servidor de atualizações, enviando informações valiosas que nos ajudarão a tomar decisões importantes no trading.

Criaremos um bot no Telegram e configuraremos nosso EA para trabalhar com a API do mensageiro. Inicialmente, configuraremos o BotFather, um bot do Telegram que auxilia na criação de novos bots e no gerenciamento dos já existentes. Com o BotFather, criaremos um novo bot e lhe daremos um nome. Também obteremos um token, um elemento essencial para identificarmos e acessarmos nosso bot via API. Depois disso, obteremos o identificador do chat e usaremos esses dois elementos para acessar a API e operá-la.

O artigo oferece um guia completo de desenvolvimento. Mostraremos como escrever e implementar um EA que estabeleça uma comunicação bidirecional entre o MetaTrader 5 e o Telegram. Não apenas explicaremos "como" fazer, mas também "por quê", para que você compreenda os aspectos técnicos e práticos da integração. Além disso, discutiremos possíveis erros que podem surgir durante a configuração e a operação, ajudando a evitá-los e a resolvê-los, mesmo com nossos esforços.

Para facilitar o entendimento, o artigo está dividido nos seguintes tópicos:

1. Introdução à integração MQL5 e Telegram
2. Configuração do bot do Telegram
3. Configuração do MetaTrader 5 para comunicação via Telegram
4. Implementação em MQL5
5. Teste da integração
6. Considerações finais

Ao final do artigo, você terá uma compreensão clara de como alcançar uma comunicação integrada e automatizada entre o terminal MetaTrader 5 e o Telegram. O produto final será um EA funcional.

Introdução à integração MQL5 e Telegram

• Visão geral da série e objetivos:

O objetivo desta série de artigos é unir o trading no MetaTrader 5 ao envio de mensagens instantâneas no Telegram. Ao final da série, você terá um EA desenvolvido em MQL5 capaz de enviar e receber mensagens e até retransmitir imagens da plataforma de trading para sua conta no Telegram. Cada parte da série se baseia na anterior, aprimorando a funcionalidade do EA e o sistema de trading como um todo.

• Vantagens da integração do Telegram com MQL5:

A integração do Telegram com o MQL5 oferece diversas vantagens. Em primeiro lugar, permite o envio de notificações instantâneas. Se você configurou um EA para operar via MQL5, pode programá-lo para enviar alertas pelo Telegram. Isso é extremamente útil, pois você pode ajustar seu algoritmo de negociação para receber apenas notificações sobre novas oportunidades excepcionais ou eventos críticos relacionados a uma posição aberta. Outra forma essencial de comunicação entre o algoritmo de trading e o Telegram é por meio de um bot. Os bots oferecem vantagens evidentes quando o assunto é programar um serviço de alertas e/ou fornecer um meio seguro e protegido para a transmissão de dados confidenciais sobre suas operações. Além disso, você pode compartilhar diversos tipos de mídia relevantes para a negociação, como gráficos e capturas de tela, que podem ser processadas pelo bot para melhorar a eficiência dos seus algoritmos. Tecnicamente, o bot atua como um intermediário na transmissão de mensagens entre o usuário e o servidor. A seguir, está uma visualização detalhada do fluxo de processos ao longo do tempo:

• Relevância no trading moderno:

No mercado financeiro de hoje, a capacidade de adaptação rápida é fundamental para o sucesso. O resultado pode ser lucro ou prejuízo. Os traders buscam maneiras de automatizar suas estratégias para acompanhar as oscilações do mercado sem a necessidade de permanecerem o tempo todo diante de suas telas. Uma das abordagens mais modernas para alcançar esse objetivo é a utilização do MQL5, uma linguagem de programação poderosa, em conjunto com o Telegram, um aplicativo de mensagens instantâneas que pode ser transformado em um painel de controle personalizado para o trader. Esse tipo de aplicação permite que os usuários sejam notificados sobre eventos relevantes para qualquer conta que estejam gerenciando. Seja você um trader individual ou parte de uma equipe, os recursos de atualização em tempo real e comunicação peer-to-peer do Telegram fazem dele uma ferramenta essencial para qualquer profissional do mercado financeiro.

• Estabelecendo as bases da série:

Compreender os conceitos fundamentais e as ferramentas básicas de integração é essencial. Começaremos pelo básico: criar um bot no Telegram e configurar o MQL5 para enviar mensagens por meio dele. Esse é um passo fundamental, pois estabelece a base sobre a qual poderemos desenvolver funções mais avançadas, complexas e úteis nas versões futuras. Ao final desta primeira fase, teremos um sistema simples, porém funcional, capaz de enviar mensagens de texto do nosso EA para o Telegram. Esse alicerce não apenas nos proporcionará experiência prática, mas também nos preparará para desafios mais avançados, como o envio de imagens e a implementação de uma comunicação bidirecional entre o MQL5 e o Telegram. No final, teremos a seguinte integração:

A integração completa entre MQL5 e Telegram servirá como base para as próximas etapas.

Configuração do bot do Telegram

O primeiro passo para conectar o Telegram ao MetaTrader 5 é criar um bot no Telegram. Esse bot atuará como um intermediário para as mensagens enviadas e recebidas entre o Telegram e o MetaTrader 5. Usaremos o BotFather para criar um novo bot, conceder as permissões necessárias e, em seguida, obter um token de API, que nos permitirá interagir com o bot.

Abra o Telegram e pesquise por BotFather. Esse é um bot oficial para a criação e gerenciamento de outros bots. Como pode haver várias contas com nomes semelhantes, certifique-se de digitar o nome corretamente, conforme mostrado na ilustração.

Inicie um chat com o BotFather e utilize o comando /newbot para criar um novo bot. Em seguida, o BotFather solicitará que você forneça um nome e um nome de usuário para o bot. Após essa etapa, você receberá um token de API único. Esse token é extremamente importante, pois permite que seu aplicativo se autentique nos servidores do Telegram e interaja com eles. O processo pode ser visualizado na animação demonstrada abaixo.

Configuração do bot: Após obter o token de API, precisamos configurar o bot de acordo com nossas necessidades. Podemos programá-lo para reconhecer e responder a comandos usando a funcionalidade do BotFather, através do comando /setcommands. Para abrir o bot, você pode procurá-lo pelo nome ou simplesmente clicar no primeiro link fornecido pelo BotFather, conforme mostrado na ilustração abaixo.

Também podemos personalizar o bot para torná-lo mais intuitivo para os usuários. Adicionar um perfil, uma descrição e uma foto pode torná-lo mais atraente, embora isso seja um passo opcional. O próximo passo na configuração do bot é garantir que ele seja capaz de processar mensagens reais conforme nossas exigências.

Obtenção do identificador do chat (Chat ID): Para que nosso bot possa enviar mensagens diretamente para um chat ou grupo específico, precisamos obter o identificador do chat. Isso pode ser feito enviando uma mensagem para o nosso bot e, em seguida, usando o método da API do Telegram getUpdates para extrair o chat ID. Esse identificador é necessário caso queiramos que nosso bot envie mensagens não apenas para o seu proprietário. Se quisermos que o bot envie mensagens para um grupo ou canal, podemos primeiro adicionar o bot ao grupo e depois usar os mesmos métodos para obter o chat ID. Para isso, utilizamos o seguinte trecho de código. Basta copiá-lo, substituir o token do bot pelo seu próprio e executá-lo no navegador.

//CHAT ID = https://api.telegram.org/bot{BOT TOKEN}/getUpdates
//https://api.telegram.org/bot7456439661:AAELUurPxI1jloZZl3Rt-zWHRDEvBk2venc/getUpdates

Aqui está o que obtemos como resultado:

Ao analisar os dados retornados, vemos que nosso resultado não contém nenhuma atualização de mensagens, mesmo ao retornarmos o valor true, o que indica que todos os dados fornecidos estão corretos. Caso você insira algo incorreto no link, receberá uma requisição inválida e um retorno falso, conforme mostrado abaixo:

{"ok":false,"error_code":404,"description":"Not Found"}

No nosso caso, estamos retornando true, mas a estrutura de resposta ainda está vazia. Isso acontece porque precisamos enviar uma mensagem ao bot para que a atualização ocorra. No nosso exemplo, enviamos o comando inicial /start.

Após enviar a mensagem e atualizar o link novamente, obtemos uma resposta com uma atualização. É importante notar que as mensagens ficam armazenadas no servidor do Telegram por apenas 24 horas antes de serem apagadas. Portanto, se você for obter o chat ID por esse método, certifique-se de que as mensagens foram enviadas dentro desse período. Vamos examinar o resultado:

Agora conseguimos obter as atualizações, mas a estrutura de saída ainda está compacta e difícil de ler. Para obter um formato mais organizado e legível, habilite a opção Pretty-Print, e a estrutura de dados aparecerá de maneira mais compreensível.

{
  "ok": true,
  "result": [
    {
      "update_id": 794283176,
      "message": {
        "message_id": 1,
        "from": {
          "id": [YOUR ID],
          "is_bot": false,
          "first_name": "Forex Algo-Trader",
          "username": "Forex_Algo_Trader",
          "language_code": "en"
        },
        "chat": {
          "id": [YOUR ID],
          "first_name": "Forex Algo-Trader",
          "username": "Forex_Algo_Trader",
          "type": "private"
        },
        "date": 1722368989,
        "text": "/start",
        "entities": [
          {
            "offset": 0,
            "length": 6,
            "type": "bot_command"
          }
        ]
      }
    }
  ]
}

O identificador do chat pode ser encontrado na seção chat id. Nesse ponto, já possuímos o token do bot e o chat ID, o que nos permite criar um programa capaz de enviar mensagens do MQL5 para o nosso bot do Telegram.

Configuração do MetaTrader 5 para comunicação via Telegram

Para garantir que o MetaTrader 5 possa interagir corretamente com o Telegram, precisamos adicionar o URL da API do Telegram à lista de URLs permitidos no MetaTrader 5. Para isso, abra o MetaTrader 5 e acesse o menu "Serviço". Em seguida, selecione "Configurações" ou pressione CTRL + O.

Na janela "Configurações", vá até a aba "Expert Advisors". Marque a opção "Permitir WebRequest para os seguintes URLs" e adicione "https://api.telegram.org" à lista. Esse passo é essencial, pois concede ao nosso EA as permissões necessárias para enviar requisições HTTP à API do Telegram, permitindo o envio de mensagens e atualizações ao nosso bot do Telegram. Configurando esses parâmetros, garantimos uma comunicação estável e segura entre o MetaTrader 5 e o Telegram, permitindo monitorar e gerenciar nossas operações em tempo real de forma eficiente.

Agora podemos prosseguir com a implementação no MQL5, onde definiremos toda a lógica do programa responsável por enviar mensagens do MQL5 para o Telegram.

Implementação em MQL5

A integração será baseada em um EA. No terminal MetaTrader 5, selecione "Serviço" > "Editor MetaQuotes Language" ou simplesmente pressione F4. Como alternativa, você pode clicar no ícone da IDE (Ambiente de Desenvolvimento Integrado) na barra de ferramentas. Isso abrirá o ambiente de programação MQL5, que permite escrever robôs de negociação, indicadores técnicos, scripts e bibliotecas de funções.

Na barra de ferramentas, selecione "Arquivo" > "Novo Arquivo" ou pressione CTRL + N para criar um novo documento. Você também pode clicar no ícone "Criar" na barra de ferramentas. Isso abrirá o Assistente MQL.

No assistente que se abre, selecione "Expert Advisor (template)" e clique em "Avançar".

Nas propriedades gerais, defina o nome do arquivo do seu EA. Para especificar ou criar uma pasta caso ela não exista, utilize uma barra invertida antes do nome do EA. Por padrão, a pasta especificada é "Experts". Isso significa que nosso EA será criado dentro dessa pasta. Os outros campos são bastante simples, mas você pode acessar um link na parte inferior do assistente para obter mais detalhes.

Após definir o nome do arquivo do EA, clique em "Avançar" > "Avançar" > "Concluir". Agora estamos prontos para começar a escrever o código e desenvolver nosso programa.

Começamos definindo alguns metadados sobre o EA, incluindo o nome do programa, informações de direitos autorais e um link para o site da MetaQuotes. Também especificamos a versão do EA, que no momento é 1.00. 

//+------------------------------------------------------------------+
//|                                          TG NOTIFICATIONS EA.mq5 |
//|                                  Copyright 2024, MetaQuotes Ltd. |
//|                                             https://www.mql5.com |
//+------------------------------------------------------------------+
#property copyright "Copyright 2024, MetaQuotes Ltd."
#property link      "https://www.mql5.com"
#property version   "1.00"

Ao carregar o programa, as seguintes informações são exibidas.

Em seguida, definimos algumas constantes que serão utilizadas em nosso código. 

const string TG_API_URL = "https://api.telegram.org";
const string botTkn = "7456439661:AAELUurPxI1jloZZl3Rt-zWHRDEvBk2venc";
const string chatID = "{YOUR CHAT ID}";

Aqui, a constante TG_API_URL contém o URL base da API do Telegram, essencial para o envio de requisições HTTP aos servidores do Telegram. A constante botTkn armazena o token único do nosso bot do Telegram, fornecido pelo BotFather e necessário para autenticação. A constante chatID representa o identificador único do chat do Telegram para o qual queremos enviar mensagens. Esse identificador é obtido através do método getUpdates da API do Telegram. É importante notar que usamos variáveis constantes de tipo string. A palavra-chave const garante que essas variáveis permaneçam inalteradas após sua definição. Isso evita a necessidade de redefini-las repetidamente, garantindo que seus valores iniciais sejam mantidos ao longo de todo o código. Esse método economiza tempo e espaço, pois eliminamos a necessidade de digitá-las manualmente sempre que precisarmos de seus valores. Além disso, reduz a possibilidade de erros ao inserir os dados.

Nosso código será amplamente baseado na seção de inicialização do EA, pois queremos realizar testes rápidos sem precisar aguardar ticks no gráfico para gerar sinais. Por esse motivo, o manipulador de eventos OnInit conterá a maior parte da estrutura do código.

//+------------------------------------------------------------------+
//| Expert initialization function                                   |
//+------------------------------------------------------------------+

int OnInit(){

   ...
   
   return(INIT_SUCCEEDED);
}

A função OnInit atua como um manipulador de eventos, sendo chamada na inicialização do EA para executar as configurações necessárias. 

Para a comunicação com os servidores do Telegram, utilizamos a função interna WebRequest do MQL5. Essa função é essencialmente sobrecarregada e possui duas formas.

Para simplificar, utilizaremos a segunda versão. Vamos analisá-la para entender o significado de cada um de seus parâmetros.

int WebRequest(
   const string method,      // HTTP method (e.g., "GET", "POST")
   const string url,         // URL of the web server
   const string headers,     // Optional HTTP headers
   int timeout,              // Request timeout in milliseconds
   const char &data[],       // Data to send with the request
   char &result[],           // Buffer to store the response
   string &result_headers    // Buffer to store the response headers
);

Uma explicação breve dos parâmetros da função WebRequest:

• method – Método HTTP utilizado para a requisição. Métodos comuns incluem GET e POST. O GET é geralmente usado para recuperar dados do servidor, enquanto o POST é usado para enviar dados ao servidor.
• url – O endereço URL do servidor para onde a requisição será enviada. Esse endereço inclui o protocolo (http:// ou https://), o domínio e o caminho/recurso que será acessado.
• headers – Cabeçalhos HTTP opcionais que podem ser incluídos na requisição. Eles fornecem informações adicionais ao servidor (por exemplo, tipo de conteúdo, tokens de autenticação).
• timeout – O tempo máximo de espera (em milissegundos) para a resposta do servidor. Se o servidor não responder dentro desse tempo, a requisição é interrompida e um código de erro é retornado. Por exemplo, se definirmos um tempo limite de 10.000 milissegundos, teremos um tempo de espera de 10.000 / 1000 = 10 segundos.
• data – Dados enviados junto com a requisição. Para requisições POST, geralmente consiste no corpo da requisição (por exemplo, dados de formulário, payload JSON).
• result – Buffer para armazenar os dados da resposta do servidor. Esse array será preenchido com a resposta do servidor, que poderá ser processada posteriormente no código.
• result_headers – Buffer para armazenar os cabeçalhos da resposta do servidor. Essa string conterá os cabeçalhos enviados pelo servidor como parte da resposta.

Agora que temos uma compreensão dos parâmetros e de sua finalidade, vamos continuar definindo algumas das variáveis essenciais que utilizaremos.

   char data[];
   char res[];
   string resHeaders;
   string msg = "EA INITIALIZED ON CHART "+_Symbol;
   //https://api.telegram.org/bot{HTTP_API_TOKEN}/sendmessage?chat_id={CHAT_ID}&text={MESSAGE_TEXT}
   const string url = TG_API_URL+"/bot"+botTkn+"/sendmessage?chat_id="+chatID+
   "&text="+msg;

Primeiro, declaramos os arrays data e res do tipo char. Esses arrays serão usados na função WebRequest para armazenar os dados enviados ao servidor web e os dados recebidos como resposta. O array data é destinado a qualquer payload que desejamos enviar com nossa requisição HTTP, embora, por enquanto, o deixemos vazio. Já o array res será preenchido com a resposta do servidor, permitindo-nos processá-la e utilizá-la em nosso programa.

Em seguida, definimos a variável string chamada resHeaders, que armazenará os cabeçalhos da resposta HTTP recebida do servidor. Os cabeçalhos da resposta HTTP contêm metadados importantes sobre a resposta, como o tipo de conteúdo, informações do servidor e códigos de status. Ao coletar esses cabeçalhos, podemos obter mais detalhes sobre a resposta e processá-la adequadamente no EA.

Depois, criamos a variável msg, que contém a mensagem que queremos enviar para o Telegram. Neste caso, a mensagem será "EA INITIALIZED ON CHART", seguida pelo símbolo do ativo atual, representado pela variável interna _Symbol. A variável _Symbol contém o nome do ativo financeiro no qual o EA está sendo executado, como AUDUSD ou GBPUSD. Ao incluir essa informação na mensagem, garantimos que o contexto do evento seja claro e específico, o que pode ser particularmente útil para monitoramento e registro de logs. Como esse é apenas um valor de exibição definido na inicialização do programa, você pode modificar a mensagem conforme necessário.

Agora, criamos a (URL), necessária para realizar a requisição à API do Telegram. Começamos pelo URL base armazenado na constante TG_API_URL, que é "https://api.telegram.org". Em seguida, adicionamos o caminho para o método sendMessage da API, incluindo o token do nosso bot (botTkn). Esse token identifica e autentica nosso bot nos servidores do Telegram, garantindo que a requisição seja válida e autorizada. O caminho da URL será estruturado da seguinte maneira: "/bot<botTkn>/sendMessage", onde <botTkn> será substituído pelo token do bot.

Em seguida, adicionamos os parâmetros da requisição ao URL. O primeiro parâmetro é chat_id, que especifica o identificador único do chat no Telegram para o qual queremos enviar a mensagem. Esse valor é armazenado na constante chatID. O segundo parâmetro é text, que contém a mensagem que queremos enviar e está armazenada na variável msg. Esses parâmetros são combinados com o URL base para formar o URL completo da requisição. O URL final terá o seguinte formato: "https://api.telegram.org/bot<botTkn>/sendMessage?chat_id=<chatID>&text=<msg>" onde <botTkn>, <chatID> e <msg> são substituídos pelos valores correspondentes.

Por fim, chamamos a função responsável por realizar a comunicação, passando os argumentos necessários.

   int send_res = WebRequest("POST",url,"",10000,data,res,resHeaders);

Utilizamos a função WebRequest para enviar uma requisição HTTP POST para o URL especificado. Essa função é essencial para interagir com serviços web externos, como a API do Telegram. Devemos definir o método HTTP, que, neste caso, é POST. Esse método é usado quando queremos enviar dados para um servidor que executará uma ação. A ação necessária aqui é o envio de uma mensagem para um chat no Telegram. Passamos a variável url, que criamos anteriormente no código. Esse URL contém o endereço base da API do Telegram, o token único do bot, o método sendMessage da API, o identificador do chat e o próprio texto da mensagem.

O parâmetro headers é definido como uma string vazia, indicando que não há necessidade de cabeçalhos HTTP adicionais para esta requisição. O tempo limite (timeout) é configurado para 10 segundos, o que equivale a 10 * 1000 = 10.000 milissegundos. Esse valor é relativamente alto, considerando que servidores modernos geralmente respondem em poucos segundos. Esse timeout evita que a requisição fique presa indefinidamente e garante que o EA continue responsivo. Em seguida, passamos o array data e o array res para a função. O array data pode conter informações adicionais que desejamos enviar com a requisição, enquanto o array res armazenará a resposta recebida do servidor. Por fim, passamos a string resHeaders, que a função utilizará para armazenar os cabeçalhos da resposta enviados pelo servidor.

A função retorna um código de status numérico, armazenado na variável send_res, que indica se a requisição foi bem-sucedida ou se ocorreu um erro. Com base no resultado, podemos verificar se a mensagem foi enviada com sucesso e, caso contrário, relatar qualquer erro ocorrido.

Após a execução da requisição HTTP, podemos processar a resposta verificando o código de status armazenado na variável send_res. Para isso, utilizamos operadores condicionais para determinar o resultado da requisição e tomar as ações apropriadas com base no código retornado.

   if (send_res == 200){
      Print("TELEGRAM MESSAGE SENT SUCCESSFULLY");
   }

Se a variável contiver o código de status 200, significa que a requisição foi bem-sucedida. Isso indica que a mensagem foi entregue ao chat especificado no Telegram. Nesse caso, exibimos no terminal a mensagem "TELEGRAM MESSAGE SENT SUCCESSFULLY" (mensagem no Telegram enviada com sucesso).

   else if (send_res == -1){
      if (GetLastError()==4014){
         Print("PLEASE ADD THE ",TG_API_URL," TO THE TERMINAL");
      }
      Print("UNABLE TO SEND THE TELEGRAM MESSAGE");
   }

Se o resultado não for 200, verificamos se ele é igual a -1. Esse status nos informa que ocorreu um erro na requisição HTTP. Não podemos simplesmente deixar o usuário final diante de uma tela com erro sem explicação. Podemos tornar as mensagens de erro mais informativas.

Primeiro, verificamos a mensagem específica de erro retornada quando a função falha. Utilizamos a função GetLastError para obter o código de erro, que nos indica o que deu errado. Em seguida, interpretamos o cenário provável com base nesse código de erro e exibimos uma mensagem útil para o usuário, ajudando-o a resolver a causa do problema. Se o código de erro for 4014, sabemos que o URL não foi especificado ou permitido no terminal. Nesse caso, informamos ao usuário que ele precisa adicionar e ativar o URL correto em seu terminal de trading.

Se o problema não estiver relacionado a restrições de URL (ou seja, se GetLastError não retornar 4014), continuamos analisando a situação. Exibimos uma mensagem clara ao usuário indicando a falha no envio da mensagem para o Telegram: "UNABLE TO SEND THE TELEGRAM MESSAGE" (não foi possível enviar a mensagem no Telegram). Também monitoramos possíveis respostas inesperadas ou "anômalas".

   else if (send_res != 200){
      Print("UNEXPECTED RESPONSE ",send_res," ERR CODE = ",GetLastError());
   }

Se send_res não for igual a 200 nem -1, significa que há um problema não identificado. Nesse caso, verificamos a resposta retornada e registramos o valor recebido para análise.

   return(INIT_SUCCEEDED);

Agora, vamos testar e ver se tudo funciona corretamente.

No chat do bot do Telegram, recebemos a seguinte mensagem:

No terminal de trading, vemos a seguinte saída:

Conseguimos enviar a mensagem do terminal de trading para o servidor do Telegram, que a retransmitiu para o chat do Telegram. Isso confirma que a integração foi bem-sucedida.

O código-fonte completo responsável por enviar a mensagem do terminal de trading para o chat do Telegram por meio do bot é o seguinte:

//+------------------------------------------------------------------+
//|                                          TG NOTIFICATIONS EA.mq5 |
//|                                  Copyright 2024, MetaQuotes Ltd. |
//|                                             https://www.mql5.com |
//+------------------------------------------------------------------+
#property copyright "Copyright 2024, MetaQuotes Ltd."
#property link      "https://www.mql5.com"
#property version   "1.00"

// Define constants for Telegram API URL, bot token, and chat ID
const string TG_API_URL = "https://api.telegram.org";  // Base URL for Telegram API
const string botTkn = "7456439661:AAELUurPxI1jloZZl3Rt-zWHRDEvBk2venc";  // Telegram bot token
const string chatID = "{YOUR CHAT ID}";  // Chat ID for the Telegram chat

// The following URL can be used to get updates from the bot and retrieve the chat ID
// CHAT ID = https://api.telegram.org/bot{BOT TOKEN}/getUpdates
// https://api.telegram.org/bot7456439661:AAELUurPxI1jloZZl3Rt-zWHRDEvBk2venc/getUpdates

//+------------------------------------------------------------------+
//| Expert initialization function                                   |
//+------------------------------------------------------------------+
int OnInit() {
   char data[];  // Array to hold data to be sent in the web request (empty in this case)
   char res[];  // Array to hold the response data from the web request
   string resHeaders;  // String to hold the response headers from the web request
   string msg = "EA INITIALIZED ON CHART " + _Symbol;  // Message to send, including the chart symbol

   // Construct the URL for the Telegram API request to send a message
   // Format: https://api.telegram.org/bot{HTTP_API_TOKEN}/sendmessage?chat_id={CHAT_ID}&text={MESSAGE_TEXT}
   const string url = TG_API_URL + "/bot" + botTkn + "/sendmessage?chat_id=" + chatID +
      "&text=" + msg;

   // Send the web request to the Telegram API
   int send_res = WebRequest("POST", url, "", 10000, data, res, resHeaders);

   // Check the response status of the web request
   if (send_res == 200) {
      // If the response status is 200 (OK), print a success message
      Print("TELEGRAM MESSAGE SENT SUCCESSFULLY");
   } else if (send_res == -1) {
      // If the response status is -1 (error), check the specific error code
      if (GetLastError() == 4014) {
         // If the error code is 4014, it means the Telegram API URL is not allowed in the terminal
         Print("PLEASE ADD THE ", TG_API_URL, " TO THE TERMINAL");
      }
      // Print a general error message if the request fails
      Print("UNABLE TO SEND THE TELEGRAM MESSAGE");
   } else if (send_res != 200) {
      // If the response status is not 200 or -1, print the unexpected response code and error code
      Print("UNEXPECTED RESPONSE ", send_res, " ERR CODE = ", GetLastError());
   }

   return(INIT_SUCCEEDED);  // Return initialization success status
}
//+------------------------------------------------------------------+
//| Expert deinitialization function                                 |
//+------------------------------------------------------------------+
void OnDeinit(const int reason) {
   // Code to execute when the expert is deinitialized
}
//+------------------------------------------------------------------+
//| Expert tick function                                             |
//+------------------------------------------------------------------+
void OnTick() {
   // Code to execute on every tick event
}
//+------------------------------------------------------------------+

No próximo trecho, modificaremos o código para testar diferentes formatos de mensagens, permitindo-nos visualizar o volume de mensagens enviadas, os erros que podem ocorrer e como superá-los.

Teste da integração

Para garantir que nosso EA esteja enviando corretamente as mensagens para o Telegram, precisamos testar a integração de maneira rigorosa. Um dos aspectos mais importantes do teste é verificar como o EA se comporta quando há configurações incorretas, como quando a opção "Permitir WebRequest para os seguintes URLs" está desativada no terminal de trading. Para confirmar se tudo foi configurado corretamente, vamos desativar essa opção.

Se executarmos o programa nesse estado, receberemos uma mensagem de erro informando o usuário de que a comunicação só pode ser estabelecida se a URL fornecida estiver ativada e permitida no terminal de trading.

Além de apenas informar o erro, oferecemos ao usuário uma solução eficaz para corrigi-lo.

Agora que conseguimos detectar e corrigir erros, podemos começar a criar formatos de mensagens mais criativos, claros e envolventes. Para começar, adicionamos um emoji ao nosso primeiro envio de mensagem.

   //--- Simple Notification with Emoji:
   string msg = "🚀 EA INITIALIZED ON CHART " + _Symbol + " 🚀";

Aqui, simplesmente adicionamos dois emojis de foguete à mensagem original. Após compilar o código, obtemos o seguinte resultado:

Uma mensagem simples com emojis foi enviada com sucesso. Para inserir emojis, basta pressionar as teclas Windows + . ao mesmo tempo. Agora podemos continuar aprimorando nossos alertas para incluir sinais de trading, como BUY (compra) ou SELL (venda), informações sobre o saldo da conta, abertura de operações, mudanças nos níveis de stop-loss e take-profit, um resumo diário dos resultados e atualizações de status da conta. Esses são apenas exemplos de mensagens que podem ser personalizadas de acordo com seu estilo de trading. Vamos inseri-las usando o código a seguir.

   //--- Simple Notification with Emoji:
   string msg = "🚀 EA INITIALIZED ON CHART " + _Symbol + " 🚀";
   //--- Buy/Sell Signal with Emoji:
   string msg = "📈 BUY SIGNAL GENERATED ON " + _Symbol + " 📈";
   string msg = "📉 SELL SIGNAL GENERATED ON " + _Symbol + " 📉";
   //--- Account Balance Notification:
   double accountBalance = AccountInfoDouble(ACCOUNT_BALANCE);
   string msg = "💰 Account Balance: $" + DoubleToString(accountBalance, 2) + " 💰";
   //--- Trade Opened Notification:
   string orderType = "BUY";  // or "SELL"
   double lotSize = 0.1;  // Example lot size
   double price = 1.12345;  // Example price
   string msg = "🔔 " + orderType + " order opened on " + _Symbol + "; Lot size: " + DoubleToString(lotSize, 2) + "; Price: " + DoubleToString(price, 5) + " 🔔";
   //--- Stop Loss and Take Profit Update:
   double stopLoss = 1.12000;  // Example stop loss
   double takeProfit = 1.13000;  // Example take profit
   string msg = "🔄 Stop Loss and Take Profit Updated on " + _Symbol + "; Stop Loss: " + DoubleToString(stopLoss, 5) + "; Take Profit: " + DoubleToString(takeProfit, 5) + " 🔄";
   //--- Daily Performance Summary:
   double profitToday = 150.00;  // Example profit for the day
   string msg = "📅 Daily Performance Summary 📅; Symbol: " + _Symbol + "; Profit Today: $" + DoubleToString(profitToday, 2);
   //--- Trade Closed Notification:
   string orderType = "BUY";  // or "SELL"
   double profit = 50.00;  // Example profit
   string msg = "❌ " + orderType + " trade closed on " + _Symbol + "; Profit: $" + DoubleToString(profit, 2) + " ❌";
   //--- Account Status Update:
   double accountEquity = AccountInfoDouble(ACCOUNT_EQUITY);
   double accountFreeMargin = AccountInfoDouble(ACCOUNT_FREEMARGIN);
   string msg = "📊 Account Status 📊; Equity: $" + DoubleToString(accountEquity, 2) + "; Free Margin: $" + DoubleToString(accountFreeMargin, 2);

Ao executar esse código com os diferentes formatos de mensagens separadamente, obtemos os seguintes resultados:

Os logs e imagens acima confirmam que a integração foi bem-sucedida. Assim, alcançamos nosso objetivo de enviar mensagens diretamente do terminal de trading para um chat de bot no Telegram. Se quiser enviar mensagens para um canal ou grupo no Telegram, basta adicionar o bot ao grupo ou canal e conceder-lhe permissões de administrador. Por exemplo, criamos um grupo chamado Forex Algo Trader Group e adicionamos um logotipo. Depois disso, promovemos o bot a administrador. 

No entanto, mesmo que você conceda privilégios de administrador ao bot, ainda precisará obter o identificador do chat do grupo específico. Se utilizar apenas o identificador de chat do próprio bot, as mensagens sempre serão enviadas diretamente para ele, e não para o grupo desejado. Portanto, o processo de obtenção do identificador do grupo segue os mesmos passos descritos anteriormente. 

// The following URL can be used to get updates from the bot and retrieve the chat ID
// CHAT ID = https://api.telegram.org/bot{BOT TOKEN}/getUpdates
https://api.telegram.org/bot7456439661:AAELUurPxI1jloZZl3Rt-zWHRDEvBk2venc/getUpdates

Basta enviar uma mensagem para o grupo e executar o código no navegador. A mensagem enviada foi:

No navegador, obtemos a seguinte informação em um formato estruturado:

{
  "ok": true,
  "result": [
    {
      "update_id": 794283177,
      "my_chat_member": {
        "chat": {
          "id": -4273023945,
          "title": "Forex Algo Trader Group",
          "type": "group",
          "all_members_are_administrators": true
        },
        "from": {
          "id": <YOUR ID>,
          "is_bot": false,
          "first_name": "Forex Algo-Trader",
          "username": "Forex_Algo_Trader",
          "language_code": "en"
        },
        "date": 1722593740,
        "old_chat_member": {
          "user": {
            "id": 
<YOUR ID> ,
            "is_bot": true,
            "first_name": "mql5tg_allan_bot",
            "username": "mql5_tg_allan_bot"
          },
          "status": "left"
        },
        "new_chat_member": {
          "user": {
            "id": <YOUR ID>,
            "is_bot": true,
            "first_name": "mql5tg_allan_bot",
            "username": "mql5_tg_allan_bot"
          },
          "status": "member"
        }
      }
    },
    {
      "update_id": 794283178,
      "message": {
        "message_id": 64,
        "from": {
          "id": 
<FROM ID> ,
          "is_bot": false,
          "first_name": "Forex Algo-Trader",
          "username": "Forex_Algo_Trader",
          "language_code": "en"
        },
        "chat": {
          "id": -4273023945,
          "title": "Forex Algo Trader Group",
          "type": "group",
          "all_members_are_administrators": true
        },
        "date": 1722593740,
        "new_chat_participant": {
          "id": 
<NEW ID> ,
          "is_bot": true,
          "first_name": "mql5tg_allan_bot",
          "username": "mql5_tg_allan_bot"
        },
        "new_chat_member": {
          "id": <NEW ID>,
          "is_bot": true,
          "first_name": "mql5tg_allan_bot",
          "username": "mql5_tg_allan_bot"
        },
        "new_chat_members": [
          {
            "id": 
<NEW ID> ,
            "is_bot": true,
            "first_name": "mql5tg_allan_bot",
            "username": "mql5_tg_allan_bot"
          }
        ]
      }
    },
    {
      "update_id": 794283179,
      "my_chat_member": {
        "chat": {
          "id": -4273023945,
          "title": "Forex Algo Trader Group",
          "type": "group",
          "all_members_are_administrators": true
        },
        "from": {
          "id": <FROM ID>,
          "is_bot": false,
          "first_name": "Forex Algo-Trader",
          "username": "Forex_Algo_Trader",
          "language_code": "en"
        },
        "date": 1722593975,
        "old_chat_member": {
          "user": {
            "id": <USER ID>,
            "is_bot": true,
            "first_name": "mql5tg_allan_bot",
            "username": "mql5_tg_allan_bot"
          },
          "status": "member"
        },
        "new_chat_member": {
          "user": {
            "id": <USER ID>,
            "is_bot": true,
            "first_name": "mql5tg_allan_bot",
            "username": "mql5_tg_allan_bot"
          },
          "status": "administrator",
          "can_be_edited": false,
          "can_manage_chat": true,
          "can_change_info": true,
          "can_delete_messages": true,
          "can_invite_users": true,
          "can_restrict_members": true,
          "can_pin_messages": true,
          "can_promote_members": false,
          "can_manage_video_chats": true,
          "can_post_stories": false,
          "can_edit_stories": false,
          "can_delete_stories": false,
          "is_anonymous": false,
          "can_manage_voice_chats": true
        }
      }
    },
    {
      "update_id": 794283180,
      "message": {
        "message_id": 65,
        "from": {
          "id": <YOUR FROM ID>,
          "is_bot": false,
          "first_name": "Forex Algo-Trader",
          "username": "Forex_Algo_Trader",
          "language_code": "en"
        },
        "chat": {
          "id": -4273023945,
          "title": "Forex Algo Trader Group",
          "type": "group",
          "all_members_are_administrators": true
        },
        "date": 1722594029,
        "text": "MESSAGE TO GET THE CHAT ID"
      }
    }
  ]
}

Aqui, o identificador do chat apresenta um sinal de menos (-) antes do número. Esse é o identificador que devemos extrair e substituir no código original. Agora, nosso identificador de chat ficará assim:

// Define constants for Telegram API URL, bot token, and chat ID
const string TG_API_URL = "https://api.telegram.org";  // Base URL for Telegram API
const string botTkn = "7456439661:AAELUurPxI1jloZZl3Rt-zWHRDEvBk2venc";  // Telegram bot token
const string chatID = "-4273023945";  // Chat ID for the Telegram chat

Ao executar, obtemos o seguinte resultado.

Como podemos ver, conseguimos criar um EA em MQL5 que envia corretamente mensagens do terminal de trading para um chat do Telegram com todas as informações necessárias. No entanto, mensagens mais complexas contendo quebras de linha (\n) ou caracteres do padrão Unicode, como emojis com código U+1F600, não podem ser enviadas diretamente dessa maneira. Abordaremos esses casos em partes futuras. Por enquanto, mantemos tudo simples e objetivo.

Considerações finais

Nesta série de artigos, criamos um EA que integra MQL5 ao Telegram, possibilitando o envio de mensagens tanto do terminal para o bot quanto do bot para o terminal. Esse recurso é incrivelmente útil por dois motivos: primeiro, porque o bot funciona como um servidor proxy entre o usuário e o terminal, facilitando a troca de informações; segundo, porque essa funcionalidade torna a comunicação de trading muito mais eficiente e interessante do que o envio de e-mails convencionais.

Também exploramos o processo de testes, identificando possíveis erros que podem ocorrer quando os parâmetros de WebRequest não estão configurados corretamente. Analisamos as causas desses erros e os corrigimos, garantindo que o programa opere de maneira mais confiável. Agora, ele funciona sem falhas, enviando mensagens com informações corretas para os destinos adequados no momento certo. Compreender o porquê e como os erros ocorrem nos dá mais segurança ao implementar soluções.

Nas próximas partes desta série, levaremos a integração a um nível mais avançado, criando um indicador personalizado que gerará sinais de trading. Esses sinais serão usados para enviar mensagens diretamente para o chat do grupo no Telegram, fornecendo oportunidades de negociação em tempo real. Isso não apenas aprimorará nossa estratégia de trading, mas também demonstrará como podemos combinar MQL5 e Telegram para criar um fluxo de operações dinâmico e automatizado. Na próxima parte, continuaremos desenvolvendo e aprimorando essa integração.