Integração com Telegram

Conecte seu agent ao Telegram e deixe os usuários conversarem com ele direto no app do Telegram.

Visão Geral

A integração com Telegram oferece:

• Respostas em streaming ao vivo (Bot API 9.5 sendMessageDraft com fallback de edição de mensagem)
• Mensagens de voz transcritas automaticamente com Whisper
• Formatação MarkdownV2 que renderiza limpa toda vez
• Campanhas com deep links com boas-vindas e respostas sugeridas personalizadas
• Reações com emoji em um toque com classificação de sentimento
• Slash commands integrados (/start, /help, /reset, /new)
• Mensagens diretas e chats em grupo (sessões por usuário em grupos)
• Uma Loja integrada ao bot — catálogo de produtos com várias páginas, chat de IA por produto e captação leve de pedidos, tudo dentro do Telegram (gratuita em todos os planos)
• Co-pilot opcional do Telegram Business para usuários Premium (integração separada)
• Saba no Telegram para operadores (integração separada)

Pré-requisitos

• Uma conta do Telegram
• Acesso ao BotFather (a ferramenta de criação de bots do Telegram)

Passos de Configuração

1. Criar um Bot do Telegram

1. Abra o Telegram e procure por @BotFather
2. Inicie uma conversa e envie /newbot
3. Siga os passos:
   • Insira um nome para o seu bot (por exemplo, “My Support Bot”)
   • Insira um nome de usuário (precisa terminar em “bot”, por exemplo, “mysupportbot”)
4. O BotFather vai te dar um Bot Token — guarde com segurança

2. Conectar ao Cuneiform Chat

1. Vá para Agents → Selecione seu agent
2. Navegue até a aba Integrations
3. Clique em Telegram
4. Cole seu Bot Token
5. Clique em Connect

3. Configurar Seu Bot

Configurações opcionais do bot via BotFather:

• /setdescription — O que o bot faz
• /setabouttext — Informações no perfil do bot
• /setuserpic — Foto de perfil do seu bot

4. Testar Seu Bot

1. Encontre seu bot no Telegram pesquisando pelo nome de usuário
2. Inicie uma conversa com /start
3. Envie uma mensagem e verifique se você recebe uma resposta

Como Funciona

Usuário envia mensagem → Telegram → Cuneiform Chat → Agent processa → Resposta enviada de volta

As mensagens são processadas em tempo real. O agent pesquisa no seu conteúdo e gera respostas com base na sua configuração.

Recursos

Respostas em streaming ao vivo

A resposta do bot aparece em milissegundos e cresce no lugar enquanto seu agent pensa — usando o sendMessageDraft nativo do Telegram (Bot API 9.5) onde for suportado, com um fallback de edição de mensagem com throttling nos demais casos. Acabou aquele silêncio de 5 a 15 segundos entre a pergunta e a resposta.

Mensagens de voz

As notas de voz enviadas ao bot são transcritas via Whisper e respondidas como se tivessem sido digitadas. O idioma é detectado automaticamente a partir da conversa, então clipes curtos em qualquer idioma continuam precisos. Limite de 2 minutos por nota. Disponível em todos os planos, incluindo o trial gratuito.

Formatação MarkdownV2

Negrito, itálico, blocos de código, listas e links renderizam exatamente como o seu agent pretendeu — sem markdown quebrado nem asteriscos perdidos. O escape é centralizado na plataforma para que cada resposta fique limpa. MarkdownV2 é o padrão; o modo HTML está disponível por integração, se necessário.

Deep links e campanhas de indicação

Gere links t.me/your-bot?start=your-code a partir do card da integração. Cada código pode trazer uma mensagem de boas-vindas personalizada e até três respostas sugeridas. Click-through, usuários únicos e conversão de conversas são rastreados por código — útil para campanhas de anúncios, QR codes e atribuição multicanal.

Reações com emoji em um toque

Os usuários reagem às mensagens do bot com 👍, ❤, 😡 ou qualquer emoji. O bot reconhece com o tom certo via respostas curtas de confirmação de reação. Um classificador integrado mapeia qualquer emoji para um sinal positivo, negativo ou neutro que você pode analisar depois. Atualmente ativo em DMs.

Slash commands

A integração registra uma lista de comandos padrão no Telegram ao conectar, então os usuários veem /start, /help, /reset e quaisquer comandos personalizados que você criar no menu de autocompletar nativo do Telegram. /start, /help, /reset e /new são tratados inline sem custo de AI. Arraste para reordenar; até 32 entradas.

Mensagens diretas

Os usuários conversam com seu bot um a um para conversas privadas de suporte. Cada usuário tem sua própria sessão.

Chats em grupo

Adicione seu bot a chats em grupo:

1. Adicione o bot a um grupo
2. Torne-o admin (para acesso total às mensagens — veja Group Privacy abaixo)
3. Os usuários mencionam o bot (@your_bot) ou respondem às mensagens dele

Cada usuário em um grupo tem o seu próprio thread de conversa — o bot não mistura sessões entre os membros. Grupos com forum-topic são suportados; os threads ficam restritos ao seu tópico.

Loja no Telegram

Cada bot do Telegram que você conecta vem com uma Loja integrada — um site sofisticado, com várias páginas, dentro do bot, que abre no Telegram quando os usuários finais tocam no botão de menu ao lado do compositor de mensagens. Cards de produto, galerias, vídeos, páginas temáticas, chat de IA por produto e captação leve de pedidos que repassa para uma pessoa real na sua caixa de entrada — tudo sem instalação de aplicativo e sem site separado.

Configuração automática ao conectar: o botão do menu de chat abre a loja, rotulado como “Shop” se você publicar um produto ou “Open” caso contrário. Disponível em todos os planos, inclusive no trial gratuito.

O guia completo do recurso — composer, blocos, temas, chat por produto, CTAs de pedido, limites por plano — vive em uma página dedicada:

→ Loja no Telegram para a configuração completa, referência de blocos e fluxo do cliente.

Um pequeno painel de suporte Help Center fica fixado ao final do menu de páginas da loja para atalhos pontuais de FAQ + ask-the-bot. A maioria das lojas não depende muito dele — produtos e CTAs de pedido respondem às dúvidas do fluxo de compra na própria loja. Crie entradas a partir do menu de três pontos no card do bot → Help Center (até ~50 entradas, arraste para reordenar, cache do servidor de ~5 minutos).

Co-pilot do Telegram Business

Usuários do Telegram com nível Premium podem fazer seu bot responder DMs na conta pessoal deles via o modo Business do Telegram. O bot responde através do business_connection_id do usuário Premium, então os contatos veem o que parece ser a resposta do próprio usuário Premium — útil para founders, criadores e equipes pequenas que recebem DMs nas contas pessoais o dia inteiro.

A configuração é uma integração separada no painel admin (“Telegram Business co-pilot”). Invariantes principais:

• 1 bot = 1 customer agent. Um bot do Telegram só pode apontar para um webhook por vez — você não pode compartilhar um bot com a integração regular do Telegram nem com o Saba no Telegram. Crie um novo bot no BotFather para o modo Business.
• A chave Business Mode do BotFather é obrigatória. Sem ela, os usuários Premium veem “this bot doesn’t support Telegram Business yet” ao adicioná-lo. Ative em Bot Settings → Business Mode.
• N usuários Premium por integração. Cada um vincula uma vez via /start <code> em uma DM regular com o bot.
• Apenas DMs. As conexões Business não cobrem chats em grupo.
• O takeover manual é automático. Quando o usuário Premium digita uma resposta ele mesmo, o bot pausa naquele chat por uma janela deslizante para não atravessar uma conversa ao vivo.
• Kill switch no nível da conexão. Ative “Disable auto-reply” no card da integração para pausar o bot em todos os usuários Premium vinculados sem desconectar.

Veja Connect Business bot na seção Telegram Business co-pilot da página Integrations do painel admin para o playbook completo de configuração.

Saba no Telegram

Os operadores também podem conversar com Saba (o assistente da plataforma) a partir de um bot do Telegram dedicado. As mesmas permissões e o mesmo acesso a dados do painel admin — útil quando você está longe do laptop e precisa checar estatísticas de agents, billing ou atividade recente.

Duas superfícies sobre o mesmo canal:

• DM bot — respostas em texto em uma DM regular do Telegram, com botões de ação inline que fazem deep-link de volta para a página correta do painel admin (?from=saba_telegram para atribuição).
• Saba Mini App — uma superfície de chat mais rica dentro do Telegram em saba-mini.cuneiform.chat com histórico de conversas, detalhe de tool-call, entrada de voz pelo navegador e exportação em markdown. Toda resposta de DM vem com um botão inline “Open in Mini App” para trocar de superfície no meio da conversa.

A configuração é do lado do admin: conecte um novo bot do BotFather em “Saba on Telegram” em Integrations. Cada membro da organização então vincula a conta pessoal com um código de 10 minutos.

Veja Platform Assistant → From Telegram para a experiência do lado do usuário.

Comandos do Bot

Você pode configurar comandos personalizados via BotFather:

Solução de Problemas

O Bot Não Está Respondendo

1. Verifique se o bot token está correto
2. Confira se a integração está conectada no Cuneiform Chat
3. Garanta que seu agent está configurado corretamente
4. Teste primeiro o agent no Playground

Problemas com o Token

Se você precisar de um novo token:

1. Vá para o BotFather
2. Envie /mybots → Selecione seu bot → API Token → Revoke
3. Atualize o novo token no Cuneiform Chat

Problemas em Chats de Grupo

• Garanta que o bot tem permissões de admin
• Confira as configurações do modo de privacidade via BotFather (/setprivacy)

Segurança

• Os bot tokens são criptografados e armazenados de forma segura
• As conversas são processadas por conexões seguras

Desconectando

Para remover a integração com Telegram:

1. Vá para Agents → Selecione o agent → Integrations
2. Clique em Telegram → Disconnect

Isso impede o bot de responder, mas não apaga o bot do Telegram em si. Apague pelo BotFather, se precisar.