Telegram | ElevenLabs Documentation

Visão geral

Conecte seus agentes de IA da ElevenLabs ao Telegram para responder às mensagens enviadas ao seu bot. Essa integração permite que seus agentes recebam mensagens em conversas privadas e grupos, consultem informações da conversa, enviem respostas e reajam a mensagens pela API do Telegram Bot.

Recursos

Recurso	Suporte
Modo de retenção zero (ZRM)	Não compatível
Anexos em gatilhos	Não compatível — fotos, arquivos e outras mídias em mensagens recebidas não são encaminhados ao agente
Anexos em ferramentas	Não compatível — as ferramentas operam apenas com texto

Configuração

Criar um bot no Telegram

Abra o Telegram e inicie uma conversa com @BotFather. Envie /newbot e siga as instruções para escolher um nome e um nome de usuário para seu bot. O BotFather responderá com um token do bot.

Conectar na ElevenLabs

Na configuração da integração da ElevenLabs, clique em Connect e cole o token do bot fornecido pelo BotFather.

Ativar o gatilho

Depois de conectar, ative o gatilho Telegram Message e selecione o agente que deve lidar com as mensagens recebidas. A ElevenLabs registrará automaticamente um webhook no Telegram para que seu bot comece a receber mensagens.

Como usar o bot em grupos

O bot não precisa ser administrador do grupo, e você não precisa desativar o modo de privacidade do Telegram. Com o modo de privacidade ativado (o padrão), o Telegram entrega mensagens que mencionam explicitamente o bot, exatamente o que esta integração monitora:

Menções com @ ao nome de usuário do bot, por exemplo, @my_bot qual é o status?.
Respostas às próprias mensagens do bot, incluindo interações seguintes na mesma conversa.

Mensagens que não mencionam o bot são ignoradas por padrão. O bot também ignora mensagens de outros bots e não age em mensagens editadas ou excluídas.

O Telegram aplica alterações no modo de privacidade e na função de administrador apenas aos grupos dos quais o bot entra depois da alteração. Se você já alternou o modo de privacidade no @BotFather ou tornou o bot administrador de um grupo para “corrigir” menções, remova o bot do grupo e adicione-o novamente para que a nova configuração entre em vigor — geralmente é isso que faz as menções começarem a funcionar, não a função de administrador em si.

Em conversas de grupos e supergrupos, a resposta do agente é enviada como uma resposta citada à mensagem que acionou o gatilho, para que a resposta permaneça visualmente vinculada à pergunta mesmo quando a conversa estiver movimentada. Em conversas privadas 1:1, a resposta citada é suprimida porque seria redundante.

Ferramentas do agente

Quando você adiciona ferramentas do Telegram a um agente, as seguintes ferramentas integradas ficam disponíveis:

Ferramenta	Descrição
`telegram_get_chat`	Consulta metadados sobre a conversa atual, como tipo, título, nome de usuário e descrição. O `chat_id` está vinculado à conversa atual e não pode ser redirecionado.
`telegram_send_message`	Envia uma mensagem de texto para a conversa atual. O `chat_id` está vinculado; o modelo controla `text` e o `parse_mode` opcional (`HTML`, `Markdown` ou `MarkdownV2`).
`telegram_react_to_message`	Reage à mensagem que acionou o gatilho com um único emoji do conjunto de reações permitido para bots no Telegram — útil quando uma breve confirmação (`👍`, `🎉`, `❤`) é mais natural do que uma resposta em texto. Tanto `chat_id` quanto `message_id` estão vinculados à interação de origem. Definir uma nova reação substitui qualquer reação que o bot tenha definido anteriormente na mesma mensagem.

Algumas conversas restringem quais emojis são permitidos pela configuração Available reactions do Telegram. Se uma chamada de reação for rejeitada, instrua o agente a recorrer a uma resposta em texto.

Variáveis dinâmicas

Quando um agente é executado pelo Telegram, as seguintes variáveis dinâmicas ficam disponíveis em prompts e ferramentas:

Variável	Descrição
`integration__telegram_chat_id`	ID da conversa do Telegram onde a conversa está acontecendo.
`integration__telegram_message_id`	`message_id` do Telegram da mensagem do usuário que acionou a interação atual do agente.
`integration__telegram_connection_id`	ID da conexão da integração da ElevenLabs.

Consulte variáveis dinâmicas para saber como fazer referência a elas em prompts e chamadas de ferramentas.