Telegram

O canal Telegram permite que seu Agente atenda conversas 1:1 por meio de um bot do Telegram.

Use-o quando precisar de suporte de entrada e saída no Telegram com texto, imagens, áudio e arquivos PDF.

Requisitos de conexão

Antes que o canal funcione, você precisa de um token de bot do Telegram.

A Zaia valida o token antes de salvar a conexão.

A conexão só é ativada quando:

O token pertence a um bot válido do Telegram
O bot ainda não está ativo em outra conexão do Telegram
O webhook é configurado com sucesso

Se a configuração do webhook falhar, a conexão permanece em status failed e não é ativada.

Fluxo de conexão

Vá até Workspace Settings → Connections → New Connection.
Selecione Telegram.
Digite um nome e o token do bot.
Salve a conexão.
Aguarde a configuração do webhook ser concluída.
Crie um Channel vinculado a essa conexão.
Atribua um Agente ou Squad.

Quando tanto a conexão quanto o canal estiverem ativos, a Zaia poderá trocar mensagens com os usuários do Telegram.

Escopo de conversas suportado

O suporte ao Telegram é limitado a chats privados.

A Zaia processa mensagens enviadas diretamente ao bot por um usuário individual.

A Zaia ignora mensagens de:

Grupos
Supergrupos
Canais

Na primeira mensagem válida de um usuário, a Zaia cria automaticamente o usuário externo e a conversa, caso ainda não existam.

A Zaia também evita o processamento duplicado da mesma mensagem do Telegram.

Tipos de mensagem suportados

Recebidas do Telegram

A Zaia pode receber:

Text
Image
Audio / voice
PDF document

Enviadas ao Telegram

A Zaia pode enviar:

Text
Image
Audio
PDF document

Comportamento de mídia

Imagens

Se o usuário enviar uma imagem com legenda, a Zaia armazena a legenda como o texto da mensagem.

Se o Telegram enviar múltiplas versões da mesma imagem, a Zaia usa a maior delas.

Quando a Zaia envia uma resposta com uma imagem e texto de até 1024 caracteres, o texto é enviado como legenda da imagem.

Se a resposta incluir texto mais longo ou outra combinação de mídia, o texto é enviado separadamente da mídia.

Documentos

O tratamento de documentos está implementado para arquivos PDF.

Outros tipos de documento não fazem parte do escopo atual do Telegram.

Áudio

Quando o usuário envia áudio ou mensagem de voz, a Zaia baixa o arquivo e o normaliza para WAV para processamento interno.

Comportamento de mensagens longas

O Telegram tem um limite técnico para o tamanho do texto.

A Zaia sempre respeita esse limite e divide automaticamente respostas muito longas.

Você também pode ativar Split long messages no canal.

Quando ativado, respostas longas são intencionalmente divididas em mensagens menores do Telegram antes da entrega.

Limitações importantes

O Telegram usa um token de bot. Ele não oferece suporte a login de usuário.
O canal só funciona quando a conexão vinculada está active.
O compartilhamento público de canal está desativado para o Telegram no web app.
A assunção manual por reação não está disponível para o Telegram.
A opção específica do canal Telegram é Split long messages.

Casos de uso ideais

O Telegram funciona melhor para:

Conversas de suporte 1:1
Troca de arquivos e mídia durante o atendimento
Fluxos de Agente que reagem a texto, imagens, áudio ou PDFs do usuário

Não foi projetado para moderação de comunidade ou fluxos de menção em grupo.

Escopo atual vs. ideias planejadas

Um planejamento anterior considerou responder dentro de grupos ou comunidades quando o bot fosse mencionado.

Esse comportamento não faz parte da implementação atual.

Apenas mensagens de chat privado são processadas.

Solução de problemas

A conexão não ativa
Verifique se o token pertence a um bot e se o bot já não está ativo em outra conexão.

A conexão entra em status failed logo após a criação
A configuração do webhook provavelmente falhou. Verifique o token novamente e tente reconectar.

As mensagens não aparecem na Zaia
Certifique-se de que a mensagem veio de um chat privado e que tanto a conexão quanto o canal estão ativos.