Telegram

Esta página é para quem quer o agente no ar hoje. O Telegram é o canal com menos burocracia dos nove: não há aprovação de aplicativo, não há revisão de modelo, não há janela de 24 horas.

O que você precisa antes

• Uma conta no Telegram.
• Um administrador do ChatMade com a permissão manage_organization.
• O seu backend acessível por HTTPS público. O Telegram registra o webhook contra a sua URL e recusa endereço local.

Onde pegar o token

No próprio Telegram:

1. Abra a conversa com @BotFather.
2. Mande /newbot.
3. Responda ao que ele pedir: o nome do bot e o nome de usuário, que precisa terminar em bot.
4. Ele devolve um token no formato 123456789:AAF…. Copie.

Essa é exatamente a instrução que o ChatMade mostra na tela, em três passos:

Open @BotFather in Telegram and send /newbot Follow the prompts to name your bot Copy the bot token and paste it below

Conectar

1. No painel, abra Settings → Integrations (“Configurações → Integrações”).
2. Ache o cartão Telegram, com a descrição “Connect a Telegram bot so customers can chat with your AI agent on Telegram.”
3. Clique em Connect (“Conectar”). Abre o modal Connect Telegram.
4. Cole o token no campo Bot token (“Token do bot”). Ele aceita Enter para enviar.
5. Clique em Connect (“Conectar”).

Deixando o campo vazio, você lê Paste the bot token from @BotFather. Token errado devolve Invalid bot token.

O webhook

Você não configura webhook nenhum. Assim que o token é aceito, o ChatMade registra o endereço no Telegram sozinho, com um cabeçalho de segredo próprio dessa conta.

Atenção: se o registro falhar, o erro aparece na hora: Failed to register Telegram webhook: {motivo}. Quando o motivo tem a ver com HTTPS, a mensagem completa vem com a dica — “set BACKEND_URL to a public HTTPS URL”. É o erro mais comum de quem está testando na própria máquina. Em desenvolvimento, use um túnel HTTPS e aponte BACKEND_URL para ele.

Escolha o agente

O modal passa para a última etapa: escolher o agente e clicar em Assign agent (“Atribuir agente”). A confirmação é Agent assigned — your bot is live!.

Sem agente atribuído, o bot recebe mensagem e não responde nada.

Testar

Não há botão de teste. Abra o Telegram, procure o nome de usuário do bot, mande um “oi” e veja se a resposta chega — e se a conversa aparece na sua caixa de entrada.

O que o Telegram faz de diferente

• Botões. O agente pode oferecer botões de resposta rápida.
• Digitando. O indicador de “digitando…” aparece enquanto o agente pensa.
• Pedir o telefone. O Telegram tem um botão nativo de compartilhar contato, e o agente pode usá-lo.
• Sem janela de tempo. Diferente do WhatsApp, você pode responder a qualquer momento.

Limites

• Resposta cortada em 4.096 caracteres.
• Chamadas ao Telegram com tempo limite de 15 segundos.
• Trava contra evento duplicado de 1 hora.
• As respostas vão em texto puro, sem interpretação de marcação. Um **negrito** que o agente escrever chega assim mesmo, com os asteriscos.

Atenção: o Telegram não recebe nem envia mídia neste sistema. Uma foto com legenda entrega a legenda e perde a imagem. Foto sem legenda, áudio, vídeo e documento chegam vazios e são descartados.

Desconectar

Botão Disconnect (“Desconectar”) no cartão. A confirmação avisa que o bot vai parar de receber e responder, que o roteamento do agente é removido, e que reconectar exige colar o token de novo.

Próximo passo

Se o seu público também está no Instagram ou no Messenger, veja Messenger e Instagram.