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
- Navegue até Agentes e selecione o agente desejado.
- Abra a aba Deploy e localize o card Telegram.
- Clique em Conectar.
- No modal, cole seu token do bot (obtido do BotFather).
- Clique em Conectar para confirmar.
- 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. Como Funciona na Prática
Fluxo de Mensagens
Usuário envia mensagem → Telegram → SipPulse AI → Agente processa → Resposta enviada ao TelegramQuando 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 pode enviar uma mensagem de boas-vindas customizável. Isso é configurado nas preferências do bot (veja Configuração).
4. 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 (veja Configuração).
- Remover — Desconectar e remover a integração do bot completamente.
5. 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:
- Clique no menu de opções no card do Telegram.
- Selecione Preferências.
- Ative o toggle de Mensagem Inicial.
- Escreva sua mensagem de boas-vindas na área de texto.
- 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.
6. 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.