Notificações de Pedidos no Telegram

Este documento explica como configurar o módulo de Notificações de Pedidos no Telegram para lojas Magento 1 openmage na plataforma mageshop. Com este recurso, a equipe da loja recebe alertas automáticos em um grupo do Telegram sempre que um novo pedido é realizado.
O que você vai aprender:

Como criar um Bot no Telegram usando o BotFather.
Como criar um grupo no Telegram e adicionar o Bot como administrador.
Como obter o Token do Bot e o ID do Chat.
Como configurar o módulo no painel administrativo da loja.
Como personalizar a mensagem de notificação com variáveis dinâmicas.

Tutorial em Vídeo
Assista ao vídeo tutorial completo com a demonstração passo a passo da configuração:

Passo a Passo da Configuração
Parte 1 — Criar o Bot no Telegram
Passo 1: Abra o Telegram e pesquise pelo BotFather
Acesse o Telegram pelo navegador ou pelo aplicativo de desktop. Na barra de pesquisa, digite BotFather e selecione o resultado que exibe o selo de verificação oficial (ícone azul).
ATENÇÃO: Existem bots falsos com nomes semelhantes. Selecione apenas o BotFather que possui o selo de verificado oficial do Telegram.
Passo 2: Inicie uma conversa com o BotFather
Clique em Iniciar (ou envie /start) para abrir a conversa com o BotFather.
Passo 3: Crie um novo Bot
Digite o comando /newbot e pressione Enter. O BotFather solicitará duas informações:

Nome do Bot: Escolha um nome descritivo (ex: Notificações Minha Loja).

Username do Bot: Defina um username único. Ele deve obrigatoriamente terminar com a palavra bot (ex: minhaloja_notify_bot).

IMPORTANTE: O username do Bot precisa terminar com "bot" (ex: minhaloja_notify_bot). Caso contrário, o Telegram não permitirá a criação.
Passo 4: Copie o Token do Bot
Após a criação, o BotFather exibirá o Token de acesso do Bot. Copie esse token e guarde-o em local seguro. Ele será inserido na configuração do módulo.
Resultado esperado: O BotFather confirma a criação do Bot e exibe o token no formato 123456789:ABCdefGHI....

Parte 2 — Criar o Grupo e Adicionar o Bot
Passo 5: Crie um novo grupo no Telegram
No Telegram, clique em Novo grupo (New Group). Na tela de seleção de membros, pesquise pelo username do Bot criado no passo anterior e adicione-o ao grupo. Defina um nome para o grupo (ex: Notificações Pedidos) e finalize a criação.
Passo 6: Promova o Bot a Administrador do grupo
Abra as configurações do grupo, acesse Administradores (Administration) e adicione o Bot como administrador. Salve as alterações.
Resultado esperado: O Bot aparece listado como administrador do grupo com as permissões necessárias para enviar mensagens.

Parte 3 — Obter o ID do Chat do Grupo
Passo 7: Envie uma mensagem de teste no grupo
Antes de obter o ID, envie qualquer mensagem no grupo onde o Bot foi adicionado. Isso garante que a API do Telegram registre o chat.
Passo 8: Acesse a URL da API do Telegram
Abra o navegador e acesse a seguinte URL, substituindo <TOKEN> pelo token do seu Bot:
A URL da API do Telegram é: https://api.telegram.org/bot<TOKEN>/getUpdates
Exemplo: https://api.telegram.org/bot123456789:ABCdef.../getUpdates
Passo 9: Localize o ID do Chat
A página retornará um JSON com as mensagens recentes. Localize o campo "chat" e, dentro dele, o campo "id". Copie o valor completo, incluindo o sinal de menos (se houver). Ex: -1001234567890.
ATENÇÃO: O ID de grupos normalmente começa com sinal negativo (-). Copie o número completo incluindo o sinal.

Parte 4 — Configurar o Módulo no Painel Magento
Passo 10: Acesse a configuração do módulo
No painel administrativo da loja, navegue até Sistema > Configuração > Vendas > Vendas. Localize a seção Notificações de Pedidos no Telegram e expanda-a.
Passo 11: Habilite o módulo e preencha os campos
Configure os seguintes campos:

Habilitado: Selecione "Sim" para ativar o módulo.

Token do Bot: Cole o token gerado pelo BotFather (Passo 4).

ID do Chat: Cole o ID do chat obtido no Passo 9.

Passo 12: Personalize o template de mensagem (opcional)
O módulo já inclui um template de mensagem padrão. Para personalizar, edite o campo de template utilizando as variáveis dinâmicas disponíveis:

Variável

Descrição

{{var order.increment_id}}

Número do pedido

{{var order.grand_total}}

Valor total do pedido

{{var order.customer_name}}

Nome do cliente

{{var order.getAdminUrl()}}

URL do pedido no admin

Exemplo de template personalizado:
🛒 Novo Pedido #{{var order.increment_id}}
💰 Total: R$ {{var order.grand_total}}
👤 Cliente: {{var order.customer_name}}
🔗 Admin: {{var order.getAdminUrl()}}
SUCESSO: A mensagem "Configuração salva com sucesso" é exibida no painel. Configuração concluída. O módulo está ativo e pronto para enviar notificações.
Passo 13: Salve a configuração e limpe o cache
Clique em Salvar Configuração. Em seguida, faça a atualização do cache. Para isso, acesse Sistema > Gerenciamento de Cache, selecione todos os tipos de cache e clique em Atualizar para aplicar as alterações.
A mensagem "Caches foram atualizados" é exibida no painel.

Validação e Testes
Para verificar se a configuração foi aplicada corretamente, realize um pedido de teste:
Passo 1: Realize um pedido de teste
Acesse a loja virtual, adicione qualquer produto ao carrinho e finalize a compra normalmente.
Passo 2: Verifique a notificação no Telegram
Dentro de alguns instantes, o grupo configurado no Telegram deve receber a notificação com os dados do pedido conforme o template definido.
Passo 3: Confirme os dados do pedido
No painel administrativo, acesse Vendas > Pedidos e confirme que o número do pedido exibido no Telegram corresponde ao pedido registrado na loja.
Resultado esperado: A mensagem no Telegram exibe corretamente o número do pedido, valor total, nome do cliente e link do admin (se configurados).
INFORMAÇÃO: Caso a notificação não chegue, revise o Token do Bot e o ID do Chat. Verifique também se o Bot é administrador do grupo.

Referências e Links Úteis

Documentação oficial do Telegram Bot API: https://core.telegram.org/bots/api

BotFather no Telegram: https://t.me/BotFather

URL para obter o ID do chat: https://api.telegram.org/bot<TOKEN>/getUpdates

Caso tenha ficado alguma dúvida entre em contato com nosso time de suporte através do chat online dentro da sua loja virtual ou através do e-mail web@tryideas.com.br