Skip to main content
Acessar Studio

Telegram

A integração com o Telegram permite que o agente converse com usuários diretamente no Telegram, através de um bot registrado no @BotFather.

Acesse pelo ícone Configurações → aba Integrações → card Telegram.

Habilitar a integração​

Ative o toggle no card do Telegram. Os campos de configuração ficam visíveis após a ativação.

Como funciona​

  1. O usuário envia uma mensagem para o bot no Telegram.
  2. O Telegram encaminha o update para o webhook do Roberty.
  3. O Roberty valida o header X-Telegram-Bot-Api-Secret-Token (quando configurado).
  4. O agente é executado e a resposta é enviada com sendMessage.

Endpoint do webhook:

https://agent-backend.roberty.app/integrations/telegram/<AGENT_ID>

Use o botão Copiar ID, no topo da aba Integrações, para obter o AGENT_ID.

Campos de configuração​

CampoObrigatórioDescrição
Bot TokenSimToken fornecido pelo @BotFather ao criar o bot
Secret TokenNãoString de segurança — deve ser a mesma usada no parâmetro secret_token da chamada setWebhook
Allowed Chat IDsNãoIDs de chats separados por vírgula (ex.: 123456789,-100987654321). Quando preenchido, o bot responde somente nesses chats

Criando o bot no Telegram​

1. Criar o bot​

  1. No Telegram, abra o chat com @BotFather.
  2. Envie /newbot e siga as instruções para nomear o bot.
  3. O BotFather fornece o Bot Token ao final do processo.

2. Registrar o webhook​

Use a API setWebhook para registrar o endpoint do Roberty:

curl -X POST "https://api.telegram.org/bot<BOT_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://agent-backend.roberty.app/integrations/telegram/<AGENT_ID>",
    "secret_token": "SEU_SEGREDO_OPCIONAL",
    "allowed_updates": ["message", "edited_message"]
  }'
  • secret_token é opcional mas altamente recomendado em produção.
  • Para remover o webhook: POST /bot<TOKEN>/deleteWebhook.

3. Configurar o agente no Roberty​

Preencha Bot Token e, opcionalmente, Secret Token e Allowed Chat IDs.

4. (Opcional) Restringir quem pode conversar​

Use Allowed Chat IDs para restringir o bot a conversas específicas.

Para descobrir o chat.id:

  1. Envie /start ao seu bot.
  2. Chame https://api.telegram.org/bot<BOT_TOKEN>/getUpdates.
  3. O message.chat.id aparece no JSON retornado.
info

Chats não permitidos recebem 200 silenciosamente, sem resposta.

Validação de segurança​

Se Secret Token estiver configurado no agente, o Telegram envia o header X-Telegram-Bot-Api-Secret-Token: <valor>. Requests sem o header ou com valor diferente recebem 401.

Se Secret Token estiver em branco, a validação é desativada.

Tipos de update suportados​

UpdateTratamento
messageExecuta o agente com message.text.
edited_messageTratado como uma nova mensagem (texto atualizado).

Outros tipos (callbacks de botões, comandos, fotos, etc.) são ignorados na versão atual.

Referências​