🔗 Por que integrar Hermes com ferramentas externas
Hermes isolado em um terminal é um app. Hermes integrado com Telegram, N8N e Zapier é um serviço — tarefas chegam de qualquer canal, executam em background e respondem onde fizer sentido. A mudança é arquitetural, não cosmética.
O que é
Integração externa é a conversão do Hermes de um binário local interativo em um serviço acessível por webhook — capaz de receber tarefas via HTTP, dispatchar para o Triad em background e devolver o resultado no canal de origem (chat, email, planilha, CRM).
🌐 Triad como serviço — três camadas
💡 Por que aprender
Sem integrações, você fica preso ao terminal. Com integrações, o Triad responde a tarefas que aparecem em qualquer lugar — uma reclamação de cliente vira briefing em 30s, um email importante vira resumo, um lead novo vira proposta. O Hermes deixa de ser ferramenta e vira backbone.
🔑 Conceitos-chave
Não um app local, mas um endpoint acessível por qualquer cliente HTTP autenticado
A mesma execução serve Telegram, email, CRM ou planilha — depende só do orquestrador
Tarefas longas rodam async — o canal só recebe o callback final, sem bloquear
A interface estável entre o canal e o Hermes — POST JSON com task + callback_url
💬 Telegram como canal de comunicação com o Hermes
Telegram é o canal mais rápido para começar — instalação móvel já existe, push notifications já funcionam, e a API é gratuita e estável. Você manda uma mensagem no celular, o Hermes despacha o Triad, e em minutos a resposta volta no chat.
O que é
Um bot Telegram conectado ao Hermes recebe mensagens de texto como tarefas, encaminha o payload por webhook ao serviço Hermes, e devolve o resultado da execução do Triad como mensagem no mesmo chat — tornando o celular o terminal de entrada/saída do sistema.
✓ Interação assíncrona (Telegram)
- ✓Você dispara a tarefa de qualquer lugar, no celular
- ✓Hermes executa em background no servidor
- ✓Push notification quando o Triad termina
- ✓Histórico do chat = log natural de execuções
✗ Interação síncrona (CLI local)
- ✗Você precisa estar na máquina onde o Hermes roda
- ✗Terminal aberto durante toda a execução
- ✗Sem notificação — você fica olhando o output
- ✗Histórico depende de scrollback do terminal
📱 Fluxo típico de uso móvel
[14:02] você → bot: "analise o concorrente xyz.com e gere 3 ângulos de diferenciação"
[14:02] bot: ✅ Tarefa #842 recebida. Triad executando...
[14:11] bot: 🎯 SHIP — 3 ângulos prontos:
1. Pricing tier abaixo do MVP deles...
2. Posicionamento em vertical não atendida...
3. Velocidade de onboarding (24h vs 2 semanas)...
🔑 Conceitos-chave
Você dispara e segue a vida — push notification avisa quando termina
Hermes acessível do supermercado, do Uber, da cama — qualquer lugar com Telegram
A timeline do chat substitui logs — busca, scroll e contexto vêm de graça
Bot API do Telegram não tem custo, não tem rate limit aprático e é bem documentada
🤖 Configurando um bot Telegram para receber tarefas
Criar o bot leva 4 minutos. BotFather emite o token, você registra o webhook no Hermes, e o bot passa a encaminhar mensagens automaticamente.
O que é
Configurar um bot Telegram envolve três passos discretos: criar o bot via BotFather (obtendo o token), expor o endpoint webhook do Hermes em HTTPS público, e registrar esse endpoint no bot via setWebhook. A partir daí, toda mensagem ao bot chega como POST JSON no Hermes.
Criar o bot com @BotFather
No Telegram, conversa com @BotFather → /newbot → escolhe nome e username. Ele devolve o token.
/newbot Bot name: Hermes Triad Username: hermes_triad_bot Token: 7842931:AAEx9bF7-cQk2pL3mNx_vR8sT4yZ1uW0iJ
Expor o endpoint do Hermes em HTTPS
Telegram só aceita webhooks em HTTPS. Use Cloudflare Tunnel, ngrok ou um servidor com Caddy/Let's Encrypt.
hermes integrations add telegram --token=$TOKEN --webhook-port=8443 # Hermes sobe servidor TLS local em 0.0.0.0:8443/telegram/webhook
Registrar o webhook no Telegram
Uma chamada curl conecta o bot ao Hermes — daqui em diante, toda mensagem vira POST no endpoint.
curl -X POST https://api.telegram.org/bot$BOT_TOKEN/setWebhook \
-d url=$HERMES_WEBHOOK_URL
# resposta esperada
{"ok":true,"result":true,"description":"Webhook was set"}
Validar com mensagem de teste
Abra o chat com o bot e envie /start. O Hermes deve logar a entrada e responder com confirmação.
hermes logs --tail --filter=telegram [INFO] telegram webhook hit: chat_id=489231 text="/start" [INFO] reply sent: "Hermes online — envie sua tarefa"
📦 Payload recebido (formato Telegram)
{
"update_id": 487231,
"message": {
"message_id": 14,
"from": { "id": 489231, "first_name": "Nei" },
"chat": { "id": 489231, "type": "private" },
"date": 1747486920,
"text": "analise o concorrente xyz.com"
}
}
💡 Whitelist de chat_ids
Por padrão, qualquer um pode mandar mensagem ao bot — e disparar execução do Triad (caro). Sempre configure --allowed-chats=489231,512847 para limitar quem pode acionar o sistema. Mensagens fora da whitelist devem ser silenciosamente descartadas.
🔑 Conceitos-chave
O bot oficial que cria outros bots — emite token, configura comandos, ajusta privacidade
Telegram rejeita webhooks em HTTP puro — TLS via Caddy, Cloudflare ou ngrok
A chamada que conecta bot e endpoint — sem ela, as mensagens não chegam ao Hermes
Lista de IDs autorizados — única defesa contra terceiros disparando o Triad
🔧 N8N como orquestrador de automações
N8N é a peça central quando o canal não é o Telegram — email, Google Sheets, Notion, Stripe, qualquer SaaS. Você desenha o workflow visualmente, e o N8N traduz cada evento em uma chamada HTTP para o Hermes.
O que é
N8N é uma plataforma open-source de automação baseada em workflows visuais. Cada workflow é um grafo de nodes — trigger (o que começa), processing (transformações) e action (HTTP request, email, DB write). Self-hostável, com 400+ integrações nativas e suporte first-class a webhooks.
🧩 Anatomia de um workflow N8N
📂 Triggers comuns para acionar o Hermes
Email com subject "[triad]" vira tarefa — corpo do email é o briefing
Nova linha em "Tasks" dispara execução — colunas são parâmetros
Tarefas recorrentes — "todo domingo 22h, gere resumo da semana"
Qualquer sistema externo posta JSON — Stripe, Typeform, Calendly
🔑 Conceitos-chave
Grafo de nodes — você arrasta blocos em vez de escrever cola entre APIs
N8N self-hosted é grátis e roda em Docker — N8N cloud cobra por execução
Toda execução gravada com input/output por node — debug e replay instantâneos
Notion, Slack, Stripe, HubSpot, Postgres, S3 — sem escrever clients
🔌 Conectando Hermes ao N8N via webhook
O contrato é simples: N8N faz POST para o endpoint /api/jobs do Hermes com {task, context, callback_url}. Hermes responde 202 imediato, executa async, e bate de volta no callback quando termina.
O que é
A integração Hermes ↔ N8N usa dois webhooks: um do N8N para o Hermes (dispara o job) e um do Hermes para o N8N (callback com resultado). O modelo é assíncrono — N8N não fica esperando o Triad terminar, o que evita timeouts e libera worker slots.
📤 HTTP Request node (N8N → Hermes)
{
"method": "POST",
"url": "https://your-hermes-host:8443/api/jobs",
"authentication": "headerAuth",
"headers": {
"Authorization": "Bearer {{ $env.HERMES_API_KEY }}",
"Content-Type": "application/json"
},
"body": {
"task": "{{ $json.subject }}",
"context": "{{ $json.body }}",
"callback_url": "{{ $env.N8N_WEBHOOK_URL }}/hermes-callback",
"priority": "normal",
"metadata": { "source": "email", "from": "{{ $json.from }}" }
}
}
📥 Resposta imediata do Hermes (202)
HTTP/1.1 202 Accepted
Content-Type: application/json
{
"job_id": "j_8f2a91c0",
"status": "queued",
"estimated_duration_sec": 540,
"callback_url": "https://n8n.example.com/webhook/hermes-callback"
}
📞 Callback do Hermes (quando termina)
POST https://n8n.example.com/webhook/hermes-callback
Content-Type: application/json
X-Hermes-Signature: sha256=4a91...
{
"job_id": "j_8f2a91c0",
"status": "ship",
"duration_sec": 487,
"iterations": 2,
"result": {
"verdict": "SHIP",
"angles": [ "...", "...", "..." ],
"critic_notes": "Premissa de cada ângulo verificável"
},
"tokens_used": { "input": 42910, "output": 8741 }
}
🔐 Assinatura HMAC no callback
Como o callback do Hermes para o N8N é um POST público, sempre assine o payload com HMAC-SHA256 (header X-Hermes-Signature). No N8N, valide a assinatura em um Function node antes de processar — descarte o que não bater. Sem isso, qualquer um pode falsificar resultados.
🔑 Conceitos-chave
Resposta imediata "recebi e enfileirei" — separa entrega de execução
Para onde o Hermes manda o resultado — N8N escuta nesse endpoint
Garante que o callback veio do Hermes e não foi adulterado em trânsito
Campo livre que carrega contexto do canal — source, user, thread_id
⚡ Zapier para usuários não-técnicos
Zapier é a alternativa quando você não quer self-host nem escrever JSON. Setup em 5 minutos pelo navegador, sem servidor. Custa mais por execução e tem menos flexibilidade, mas para clientes ou times não-técnicos é o caminho mais curto.
O que é
Zapier é um SaaS de automação no-code. Cada automação é um "Zap" com um trigger e uma ou mais actions. Não precisa de servidor próprio, não precisa de Docker, não precisa de webhook handler — Zapier hospeda tudo e expõe uma UI de formulário para configurar.
✓ N8N — quando usar
- ✓Você sabe Docker / quer self-host
- ✓Volume alto (>1000 execuções/mês)
- ✓Precisa de Function nodes (JS custom)
- ✓Dados sensíveis não podem sair da rede
- ✓Workflow tem branching complexo
✓ Zapier — quando usar
- ✓Sem infra própria / time não-técnico
- ✓Volume baixo/médio (<500 exec/mês)
- ✓Apenas glue simples entre SaaS
- ✓Tempo de setup < 10 min é prioridade
- ✓Cliente quer editar os fluxos sozinho
⚙️ Zap mínimo: Email → Hermes → Reply
Step 1 — Trigger
App: Gmail
Event: New Email Matching Search
Search: subject:"[triad]" from:cliente@empresa.com
Step 2 — Action
App: Webhooks by Zapier
Event: POST
URL: https://hermes.example.com/api/jobs
Headers: Authorization: Bearer {{HERMES_API_KEY}}
Body (JSON):
task: {{1.Subject}}
context: {{1.BodyPlain}}
callback_url: https://hooks.zapier.com/hooks/catch/.../hermes
Step 3 — Action
App: Gmail
Event: Send Email Reply
To: {{1.FromEmail}}
Body: {{2.result.angles}}
💰 Custo por execução
Zapier cobra por task (cada action conta como 1 task). Um zap de 3 steps = 3 tasks por execução. Plano Starter dá 750 tasks/mês — se você roda 50 tarefas Hermes/mês, gasta 150 tasks só com Zapier. N8N self-hosted, no mesmo cenário, custa o servidor (US$ 5–10/mês fixo).
🔑 Conceitos-chave
Toda configuração em formulários — sem JSON, sem Docker, sem terminal
Cada action é 1 task — fluxos longos consomem mais que parecem
Action genérica que faz HTTP — é por aqui que você bate no Hermes
Quando o custo Zapier ultrapassa o custo de um VPS — geralmente em 6 meses
🔁 Criando um pipeline — Telegram → Hermes → Triad → resposta
Pipeline completo end-to-end: mensagem no Telegram chega, vira job, executa o Triad, e a resposta volta no mesmo chat — tudo async, sem você abrir o terminal. Esse é o caso de uso que justifica todo o capítulo.
O que é
Um pipeline integrado é o fluxo completo de dados desde o canal de entrada até a entrega do resultado — passando por orquestração (N8N), execução (Hermes + Triad) e devolução pelo callback. É o padrão arquitetural canônico de uma integração de produção.
Telegram recebe a mensagem do usuário
Bot recebe "analise o concorrente xyz.com" → POST para webhook do N8N com chat_id e text.
N8N valida chat_id e normaliza payload
IF node checa whitelist → Set node monta {task, context, callback_url, metadata.chat_id}.
N8N posta no Hermes — recebe job_id (202)
HTTP node faz POST em /api/jobs → resposta 202 com job_id → N8N termina a execução do trigger.
N8N responde ao Telegram com ACK imediato
"✅ Tarefa #842 recebida. Triad executando..." — usuário tem feedback em < 2s.
Hermes executa o Triad (5–15 min)
Condutor monta briefing → Worker gera ângulos → Crítico avalia. Loop até SHIP ou FUNDAMENTAL FLAW.
Hermes bate no callback do N8N com resultado
POST com X-Hermes-Signature → N8N valida HMAC → extrai metadata.chat_id → formata mensagem.
N8N envia resposta de volta ao Telegram
Telegram node usa sendMessage com o chat_id original → push notification no celular do usuário.
📋 Workflow N8N completo (export JSON resumido)
{
"name": "Telegram → Hermes → Telegram",
"nodes": [
{ "name": "Telegram Trigger", "type": "n8n-nodes-base.telegramTrigger",
"parameters": { "updates": ["message"] } },
{ "name": "Allowed Chats?", "type": "n8n-nodes-base.if",
"parameters": { "conditions": { "number": [
{ "value1": "={{$json.message.chat.id}}", "operation": "equal", "value2": 489231 }
] } } },
{ "name": "POST /api/jobs", "type": "n8n-nodes-base.httpRequest",
"parameters": {
"url": "https://hermes.example.com:8443/api/jobs",
"method": "POST", "jsonBody": true,
"body": {
"task": "={{$json.message.text}}",
"callback_url": "={{$env.N8N_URL}}/webhook/hermes-callback",
"metadata": { "chat_id": "={{$json.message.chat.id}}" }
}
} },
{ "name": "ACK Telegram", "type": "n8n-nodes-base.telegram",
"parameters": { "text": "✅ Tarefa #{{$json.job_id}} em execução" } },
{ "name": "Hermes Callback", "type": "n8n-nodes-base.webhook",
"parameters": { "path": "hermes-callback", "responseMode": "onReceived" } },
{ "name": "Verify HMAC", "type": "n8n-nodes-base.function" },
{ "name": "Reply Telegram", "type": "n8n-nodes-base.telegram",
"parameters": {
"chatId": "={{$json.metadata.chat_id}}",
"text": "🎯 {{$json.result.verdict}}\n\n{{$json.result.angles.join('\\n')}}"
} }
]
}
🎯 Por que o pipeline é assíncrono ponta-a-ponta
Se você tentasse rodar tudo síncrono, o Telegram daria timeout em 60s e o N8N em 5 min — bem antes do Triad terminar. Separar entrega de execução (POST 202 + callback) é a única arquitetura que escala para tarefas longas sem perder feedback ao usuário.
🔑 Conceitos-chave
Confirmação em < 2s mata a ansiedade do usuário — o resultado pode demorar
O fio que conecta callback à conversa original — sem ele, não há como responder
Única arquitetura viável para tarefas de 5–15 min sem hit em timeouts
Telegram não fala com Hermes direto — N8N é quem traduz formatos e roteia callbacks
✅ Resumo do Módulo
Próximo Módulo:
4.5 — Deploy do Hermes em produção