Passo a passo pra conectar um bot do Telegram ao Codewo, incluindo criação do bot no @BotFather, configuração de webhook e uso do deep link de atribuição de leads.
O que você vai precisar
- Conta no Telegram (qualquer número).
- ~5 minutos.
Não precisa de empresa cadastrada, verificação ou pagamento. Telegram não cobra pra usar Bot API.
Como funciona
No Telegram, atendimento empresarial não é feito pelo número pessoal — é feito por um bot que você cria. O bot tem nome próprio (@SuaEmpresaBot) e recebe mensagens dos clientes. Quando o cliente abre conversa com o bot e manda mensagem, ela cai no Inbox do Codewo.
Passo a passo
1. Criar o bot no @BotFather
No Telegram, busque por @BotFather (bot oficial pra criar bots) e abra conversa com ele.
- Envie
/newbot - Escolha um nome de exibição (ex: "Suporte Codewo"). Pode mudar depois.
- Escolha um username terminando em "bot" (ex:
codewo_suporte_bot). Esse não pode mudar. - O BotFather responde com um token no formato
123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11. Copie esse token e guarde — é a credencial do seu bot.
2. Conectar no Codewo
Em Configurações → Canais → Novo canal → Telegram:
- Cole o token do bot no campo Bot Token.
- Clique em "Verificar conexão" — Se o token está certo, o Codewo busca dados do bot na API do Telegram e mostra o avatar e o nome atual.
- (Opcional) Edite perfil do bot — Nome, descrição curta, descrição longa. Tudo isso é alterado diretamente no Telegram pelo Codewo.
- Configure o webhook — O Codewo registra na API do Telegram o endpoint que vai receber as mensagens (
/api/telegram/webhook/...). Você não precisa fazer nada — é automático. - Dê um nome interno ao canal (ex: "Telegram Suporte") e escolha a equipe.
- Salve. Pronto.
3. (Opcional) Deep link de atribuição
Pra rastrear de qual campanha veio cada cliente, o Codewo gera deep links no formato https://t.me/seu_bot?start=CW-XXXX. Quando o cliente clica nesse link e manda /start, o Codewo captura o CW-XXXX e marca a conversa com aquela origem.
Você cria esses códigos em Configurações → Atribuição → Códigos de origem. Cole o link em anúncios, posts no Instagram, página do site, etc.
Pegadinhas comuns
- Telegram exige HTTPS no webhook. Em produção, isso funciona automaticamente (Codewo já roda em HTTPS). Em ambiente local de desenvolvimento, não funciona — precisa de ngrok ou similar.
- Rate limit da Telegram API. Se você fizer muitas chamadas em curto tempo (mudar nome do bot várias vezes, editar perfil em loop), o Telegram bloqueia o bot por 30–60 minutos com erro 429. Não dá pra acelerar — espere passar.
- Token comprometido = bot comprometido. Se alguém pegar o token, controla o bot. Se vazar, vá no BotFather, envie
/revokepra gerar token novo e atualize no Codewo. - Cliente precisa iniciar a conversa. Pelo Telegram, bot só fala depois que o cliente mandar primeira mensagem. Não dá pra "mandar uma promoção pra todos os clientes" — exceto pra quem já interagiu.
- Sem o código de atribuição cadastrado,
/start CW-XXXXviradirect. Se você divulgar um link?start=CW-VENDAS-INSTAmas não tiver cadastrado esse código no Codewo, a conversa entra normalmente mas com origem "direct" em vez de "Instagram Vendas". Cadastre o código antes de divulgar o link.
Boas práticas
- Username do bot importa pra divulgação. Escolha algo simples e memorável (
@empresa_suporte_boté melhor que@xyz123_bot_2024). E lembre: não pode mudar depois. - Configure descrição e foto do bot — Cliente vê isso ao abrir a conversa. Vazio passa amador.
- Use deep link em anúncios — Sem isso, todo o tráfego pago vira "direct" no relatório, e você não sabe qual campanha está performando.
- Defina horário de atendimento da equipe — Telegram não tem janela de 24h como WhatsApp Cloud, então conversa pode ficar parada por dias se ninguém pegar.