Telegram

O canal Telegram recebe mensagens de um bot criado no BotFather. Cada caixa de entrada pode encaminhar as novas conversas para um agente de IA ou deixá-las com o atendimento humano.

O SquadOS processa mensagens comuns em chats privados e grupos: texto, legenda, foto, mensagem de voz, áudio e documento. Publicações de canal, mensagens editadas, vídeos e stickers não iniciam processamento.

Antes de conectar

Você precisa de um bot do Telegram e do token emitido pelo BotFather:

1. No Telegram, abra @BotFather.
2. Envie /newbot.
3. Informe o nome de exibição e um username terminado em bot.
4. Copie o token devolvido pelo BotFather. Trate-o como senha: quem tiver esse valor pode controlar o bot.

Também prepare o destino da caixa:

• para atendimento por IA, o agente precisa estar ativo;
• para atendimento humano, alguém deve acompanhar a caixa em Conversas.

Um mesmo bot não pode ficar conectado simultaneamente a duas caixas ativas do SquadOS, mesmo que elas pertençam a organizações diferentes.

Conectar pela caixa de entrada

1. No painel admin, abra Caixas de entrada.
2. Clique em Nova caixa de entrada.
3. Escolha Telegram — a opção é descrita como Conecte um bot criado no @BotFather.
4. Cole o valor no campo Token do Bot e clique em Conectar Bot.
5. Depois da validação, clique em Continuar.
6. Em Destino padrão, escolha atendimento humano ou um agente ativo.
7. Dê um nome à caixa e conclua o assistente.

O SquadOS primeiro confirma o token com o Telegram e registra o webhook. A caixa só é criada depois que essa configuração externa é aceita. Se o bot já estiver em outra caixa ativa, desconecte-o lá antes de tentar novamente.

Testar o recebimento

1. Abra o bot pelo @username mostrado na conexão ou procure esse username no Telegram.
2. Em uma conversa privada, inicie o chat e envie uma mensagem de teste.
3. Em Conversas, confirme que a mensagem apareceu na caixa correta.
4. Se o destino for um agente ativo, confirme também a resposta no Telegram. Se o destino for humano, a conversa é criada sem acionar IA.

O comando /start é uma forma comum de iniciar a conversa privada, mas não é um comando obrigatório do pipeline do SquadOS: qualquer mensagem comum entregue pelo Telegram pode ser processada.

Uso em grupos

Adicione o bot ao grupo. Com o modo de privacidade padrão do Telegram, ele pode receber apenas comandos, respostas e mensagens que o mencionem. Se a operação exigir todas as mensagens do grupo, ajuste Group Privacy no BotFather (/mybots → bot → Bot Settings → Group Privacy) e valide o comportamento no próprio grupo.

Todas as pessoas de um grupo compartilham o mesmo Chat ID e, portanto, a mesma identidade e conversa desse grupo no SquadOS.

Informações e troca de token

Na integração conectada, abra Informações. A janela Telegram — Informações do gatilho mostra o bot e permite:

• abrir o @username no Telegram;
• revelar ou ocultar o Token do Bot;
• substituir o token e Salvar.

A alteração é revalidada com o Telegram. Se ela falhar, considere o canal não verificado: restaure um token válido e repita um teste de recebimento antes de retomar a operação.

Enviar por automação

O Chat ID é gravado automaticamente como identidade do contato quando uma mensagem entra pelo bot. Para uma automação falar com esse contato, use os passos Escolher contato, Obter conversa do contato e Enviar mensagem. O editor não oferece um campo genérico para colar um Chat ID arbitrário.

Veja Chat ID do Telegram no SquadOS e Ações de automação.

Desconectar

Desconectar remove o webhook do bot e remove a caixa da lista ativa. Se não houver conversas, a caixa pode ser excluída; se houver histórico, ela é preservada como removida para manter as referências das conversas. O token continua válido no Telegram até ser revogado no BotFather.

Depois da desconexão, envie uma mensagem de teste somente após reconectar e confirmar a nova caixa.

Problemas comuns

• Erro ao conectar o bot. Verifique o token. — confirme que o valor foi copiado por inteiro e ainda corresponde ao bot no BotFather.
• Bot já conectado — o mesmo @username pertence a outra caixa ativa; desconecte essa caixa antes de reutilizá-lo.
• Mensagem privada não chega — confirme que a conversa com o bot foi iniciada e que o bot não foi bloqueado.
• Mensagem de grupo não chega — confirme que o bot está no grupo, mencione-o no teste e revise Group Privacy.
• Publicação de canal ou mensagem editada não aparece — esses tipos de atualização não são processados pelo canal atual.
• Conversa aparece, mas não há resposta da IA — confira o destino padrão e se o agente associado está ativo. Uma caixa com destino humano não chama o agente.