Integração Telegram

Esta página descreve como conectar um Agente SipPulse AI a um bot do Telegram usando um token de bot do BotFather.

1. O que é a Integração Telegram?

A Integração Telegram é um canal de implantação que permite conectar seu agente a um bot do Telegram. Os usuários podem interagir com seu agente diretamente pelo Telegram enviando mensagens ao bot.

Como Criar um Bot do Telegram

Antes de conectar, você precisa de um bot do Telegram. Abra o Telegram, pesquise por @BotFather e envie o comando /newbot. Siga as instruções para criar seu bot e obter o token do bot.

Quando Usar o Telegram

Cenários ideais:

• Suporte ao cliente e automação de FAQ
• Notificações e alertas entregues via Telegram
• Serviços interativos acessíveis de qualquer cliente Telegram (celular, desktop, web)
• Implantação rápida sem necessidade de infraestrutura

2. Configuração Inicial

Pré-requisitos

• Um bot do Telegram criado via @BotFather
• O token do bot fornecido pelo BotFather
• O bot não pode estar conectado a outro agente

Conectar um Bot

1. Navegue até Agentes e selecione o agente desejado.
2. Abra a aba Deploy e localize o card Telegram.
3. Clique em Conectar.
4. No modal, cole seu token do bot (obtido do BotFather).
5. Clique em Conectar para confirmar.
6. Uma vez conectado, o card exibirá o @username do bot (com link para o Telegram) e o status mudará para Online.

Um bot por agente

Cada bot do Telegram só pode estar conectado a um agente por vez. Se você tentar conectar um bot que já está em uso, verá uma mensagem de erro.

Teste Antes de Implantar

Você pode testar seu agente no Playground antes de implantá-lo no Telegram. Isso ajuda a garantir que o fluxo conversacional funcione como esperado.

3. Comandos do Bot

Quando a integração está ativa, seu bot suporta os seguintes comandos:

Comando	Descrição
/start	Inicia o bot e envia a mensagem de boas-vindas configurada
/reset	Reseta a thread de conversa atual e começa do zero
/help	Mostra a lista de comandos disponíveis
/auth <código>	Autentica com um código de acesso (disponível apenas no modo Código de Acesso)
/voice	Alterna o modo voz — agente responde com áudio além do texto (disponível apenas quando TTS está configurado)

Os usuários podem digitar esses comandos a qualquer momento durante a conversa.

4. Como Funciona na Prática

Fluxo de Mensagens

Usuário envia mensagem → Telegram → SipPulse AI → Agente processa → Resposta enviada ao Telegram

Quando a integração está ativa, cada mensagem enviada ao seu bot é encaminhada ao agente para processamento. O agente analisa a mensagem e gera uma resposta apropriada baseada em sua configuração.

O Comando /start

Quando um usuário inicia uma conversa com seu bot (enviando /start), o bot envia uma mensagem de boas-vindas customizável. Isso é configurado nas preferências do bot (veja Configuração).

O Comando /reset

O comando /reset fecha a thread de conversa atual do usuário e inicia uma nova. Isso é útil quando o usuário quer recomeçar sem que o agente retenha contexto da interação anterior.

5. Gerenciamento

Ativar ou Desativar Rapidamente

Use o botão de alternância no card para controlar a integração:

• Ligado — O agente processa mensagens recebidas em tempo real.
• Desligado — Mensagens recebidas são ignoradas; sem cobrança de tokens.

Status

O card exibe o status atual:

Status	Descrição
Online	Bot está ativo e processando mensagens.
Offline	Bot está desativado ou não conectado.

Menu de Opções

Clique no menu de opções no card do Telegram para acessar:

• Preferências — Configurar a mensagem inicial e controle de acesso (veja Configuração).
• Gerenciar Usuários — Ver e gerenciar usuários que interagiram com o bot (veja Gestão de Usuários).
• Remover — Desconectar e remover a integração do bot completamente.

6. Configuração

Mensagem Inicial

A mensagem inicial é enviada automaticamente quando um usuário envia /start para seu bot. Esta é tipicamente a primeira interação que um usuário tem com seu bot.

Para configurar:

1. Clique no menu de opções no card do Telegram.
2. Selecione Preferências.
3. Escreva sua mensagem de boas-vindas na área de texto.
4. Clique em Salvar.

TIP

Use a mensagem inicial para apresentar seu agente, explicar o que ele pode fazer e orientar os usuários sobre como interagir com ele.

Controle de Acesso

O controle de acesso determina quem pode interagir com seu bot do Telegram. Três modos estão disponíveis:

Aberto (Padrão)

Qualquer pessoa pode interagir com o agente imediatamente. Os usuários são aprovados automaticamente no primeiro contato. Nenhuma autenticação é necessária.

Código de Acesso

Os usuários devem fornecer um código para autenticar antes de poder conversar com o agente.

Como funciona:

1. Quando um usuário não autenticado envia mensagem ao bot, ele recebe uma instrução: "Para acessar este agente, envie: /auth <seu código de acesso>"
2. O usuário envia /auth meucodigo123
3. Se o código estiver correto, o usuário é aprovado e pode interagir normalmente
4. Se o código estiver incorreto, o usuário recebe um erro e pode tentar novamente

Campos de configuração:

Campo	Descrição	Restrições
Código de Acesso	O código que os usuários devem fornecer	8–100 caracteres
Máx. Tentativas de Autenticação	Número de tentativas falhas antes do bloqueio automático	Mínimo 1 (opcional)
Enviar Mensagem de Rejeição	Se deve enviar feedback para usuários não autenticados	Liga/desliga
Mensagem de Rejeição	Mensagem customizada para usuários não autenticados	Texto livre (opcional)

Se Máx. Tentativas de Autenticação estiver definido e um usuário exceder o limite, ele é automaticamente bloqueado e recebe: "Você excedeu o número máximo de tentativas. Seu acesso foi bloqueado."

Whitelist

Apenas usuários manualmente aprovados podem interagir com o agente. Novos usuários aparecem como pendentes e precisam ser aprovados por um administrador.

Como funciona:

1. Um novo usuário envia mensagem ao bot
2. Ele recebe uma mensagem: "Seu acesso está pendente de aprovação. Aguarde a liberação pelo administrador."
3. O usuário aparece na tabela de Gerenciar Usuários com status Pendente
4. Um administrador aprova ou nega o usuário
5. Uma vez aprovado, o usuário pode interagir normalmente

Modo Silencioso

Quando Enviar Mensagem de Rejeição está desativado, usuários não autenticados ou pendentes não recebem nenhum feedback — o bot simplesmente não responde. Isso pode ser útil para implantações sensíveis à segurança onde você não quer revelar a existência do bot para usuários não autorizados.

Idioma

As mensagens de sistema do bot (prompts de autenticação, mensagens de erro, etc.) são enviadas no idioma configurado. Idiomas suportados: Inglês (en) e Português (pt).

7. Gestão de Usuários

A opção Gerenciar Usuários no menu de opções do card do Telegram abre uma tabela com todos os usuários que interagiram com seu bot.

Tabela de Usuários

Coluna	Descrição
Nome	Primeiro nome do usuário no Telegram
Username	@username do Telegram (pode estar vazio)
Status	Status de acesso atual (veja abaixo)
Primeira Interação	Data em que o usuário contatou o bot pela primeira vez

Status dos Usuários

Status	Descrição
Aprovado	Usuário pode interagir com o bot
Pendente	Usuário enviou mensagem ao bot mas aguarda aprovação (modo whitelist) ou não se autenticou (modo código de acesso)
Revogado	O acesso do usuário foi removido manualmente
Bloqueado	Usuário foi bloqueado manualmente ou por exceder o máximo de tentativas de autenticação

Ações Disponíveis

Cada linha de usuário tem um menu de contexto com as seguintes ações (visibilidade depende do status atual):

• Aprovar — Concede acesso ao usuário. Disponível para usuários pendentes, revogados e bloqueados.
• Negar — Rejeita um usuário pendente (muda status para revogado). Apenas para usuários pendentes.
• Revogar — Remove o acesso de um usuário aprovado ou bloqueado.
• Bloquear — Bloqueia permanentemente um usuário de interagir com o bot.

Filtragem

Use o filtro de status para visualizar apenas usuários com um status específico (ex: mostrar apenas usuários pendentes aguardando aprovação).

8. Funcionalidades de Voz

Seu bot do Telegram pode transcrever mensagens de voz dos usuários e responder com áudio. Ambas as funcionalidades são opcionais e configuradas independentemente nas preferências do bot.

Transcrição de Mensagens de Voz (Áudio para Texto)

Quando habilitada, mensagens de voz enviadas pelos usuários são automaticamente transcritas para texto e processadas pelo agente como uma mensagem de texto normal.

Como funciona:

Usuário envia mensagem de voz → Bot transcreve o áudio → Agente processa o texto → Envia resposta em texto

Para habilitar:

1. Clique no menu de opções no card do Telegram.
2. Selecione Preferências.
3. Na seção Transcrição de Áudio, ative o recurso.
4. Selecione um Modelo de Transcrição no dropdown (os modelos disponíveis são exibidos na interface).
5. Clique em Salvar.

Campo	Descrição
Habilitado	Controle principal da transcrição de mensagens de voz (padrão: desativado)
Modelo de Transcrição	O modelo de fala para texto usado para transcrever mensagens de voz

Apenas Mensagens de Voz

A transcrição se aplica a mensagens de voz gravadas diretamente no Telegram. Se a transcrição estiver desabilitada, mensagens de voz são ignoradas e o usuário recebe uma mensagem pedindo para enviar texto.

TIP

Este recurso funciona perfeitamente com o controle de acesso — os usuários devem estar autenticados antes que suas mensagens de voz sejam processadas.

Respostas por Voz (Texto para Fala)

Quando habilitado, o comando /voice fica disponível. Os usuários podem alternar o modo voz para receber respostas em áudio junto com as mensagens de texto.

Como funciona:

1. Usuário envia /voice → modo voz é ativado
2. O agente responde com texto e áudio para cada mensagem
3. Usuário envia /voice novamente → modo voz é desativado (apenas texto)

O Texto É Sempre Enviado

As respostas em áudio são enviadas além da mensagem de texto, não como substituição. Os usuários sempre recebem a resposta em texto, independentemente do modo voz.

Para habilitar:

1. Clique no menu de opções no card do Telegram.
2. Selecione Preferências.
3. Na seção Texto para Voz, ative o recurso.
4. Selecione um Modelo TTS no dropdown.
5. Selecione uma Voz no dropdown (as vozes são filtradas pelo idioma do agente).
6. Clique em Salvar.

Campo	Descrição
Habilitado	Controle principal das respostas por voz (padrão: desativado)
Modelo TTS	O modelo de texto para fala usado para gerar áudio
Voz	A voz usada para respostas em áudio (filtrada pelo idioma do agente)

Modelo e Voz São Obrigatórios

O comando /voice só aparece no menu de comandos do bot quando um modelo TTS e uma voz estão selecionados. Se qualquer um estiver faltando, os usuários não verão o comando.

9. Solução de Problemas

Token do Bot Inválido

Se você vir um erro ao conectar, verifique se:

• O token foi copiado corretamente do BotFather (formato: 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ).
• O bot não foi excluído ou revogado no BotFather.

Bot Já em Uso

Se o bot já está conectado a outro agente, você precisa:

• Remover o bot do outro agente primeiro, ou
• Criar um novo bot via BotFather.

Bot Não Responde

Se o bot está conectado mas não responde às mensagens:

• Verifique se o botão de alternância está Ligado (não desativado).
• Verifique se o agente tem instruções adequadas configuradas.
• Teste o agente no Playground para garantir que ele responde corretamente.

Usuário Bloqueado Após Muitas Tentativas

Se um usuário foi bloqueado por exceder o máximo de tentativas de autenticação:

1. Abra Gerenciar Usuários no menu de opções do card do Telegram.
2. Encontre o usuário bloqueado na tabela.
3. Clique no menu de contexto e selecione Aprovar para restaurar o acesso.

Usuários Presos como Pendentes

No modo Whitelist, os usuários requerem aprovação manual:

1. Abra Gerenciar Usuários no menu de opções do card do Telegram.
2. Encontre os usuários pendentes na tabela.
3. Clique em Aprovar ou Negar para cada usuário.

Mensagens de Voz Não Estão Sendo Transcritas

Se os usuários enviam mensagens de voz mas o bot não responde:

• Verifique se a Transcrição de Áudio está habilitada nas Preferências.
• Certifique-se de que um Modelo de Transcrição está selecionado.
• Verifique se o usuário está autenticado (o controle de acesso se aplica antes da transcrição).

Comando /voice Não Aparece

Se os usuários não conseguem ver o comando /voice:

• Verifique se o Texto para Voz está habilitado nas Preferências.
• Certifique-se de que tanto um Modelo TTS quanto uma Voz estão selecionados — ambos são necessários para o comando aparecer.