SMS — Command AI by Text | Easy Understand Hermes Agent

SMS — Comande a IA por Mensagem de Texto

Lembra da época antes dos smartphones, quando mandar mensagem de texto era a forma mais rápida de falar com alguém? Pois é, esse canal clássico continua vivo e funcionando — e agora virou uma forma completa de conversar com seu assistente de IA.

O Hermes agora se conecta a SMS via Twilio, então qualquer pessoa com um número de telefone pode mandar mensagem para o seu bot e receber respostas geradas por IA. Sem instalar app, sem QR code, sem curva de aprendizado. Apenas mensagens de texto à moda antiga.

O que Há de Novo Nesta Atualização

O gateway de SMS recebeu uma grande melhoria. Veja o que mudou:

SMS_WEBHOOK_URL agora é obrigatório — O Hermes valida as assinaturas de webhook do Twilio para manter impostores de fora. O gateway se recusa a iniciar sem isso.
Novas variáveis de ambiente — SMS_WEBHOOK_HOST, SMS_WEBHOOK_PORT, SMS_INSECURE_NO_SIGNATURE e SMS_ALLOW_ALL_USERS dão a você mais controle.
Padrões de segurança melhores — O gateway nega todos os usuários por padrão. Você precisa adicionar números de telefone explicitamente à lista de permissões.
Divisão de mensagens mais inteligente — Respostas longas agora são divididas em pontos naturais (quebras de linha, depois espaços) em vez de serem cortadas no meio da palavra.

Começando

Primeiro, você vai precisar de uma conta no Twilio e de um número de telefone com capacidade de SMS. O Twilio oferece um teste gratuito, então você pode testar tudo sem gastar nada.

Você também vai precisar de um servidor acessível publicamente. O Twilio envia webhooks para o seu servidor quando alguém manda mensagem para o seu número. Se você estiver rodando o Hermes localmente, ferramentas como cloudflared ou ngrok podem expor seu localhost para a internet.

Instale o extra de SMS com:

cd ~/.hermes/hermes-agent && uv pip install -e ".[sms]"

Passo 1: Pegue Suas Credenciais do Twilio

Vá para o Console do Twilio, copie seu Account SID e Auth Token do painel, e anote seu número de telefone no formato E.164 (como +15551234567).

Passo 2: Configure o Hermes

A forma mais fácil é pelo assistente interativo:

hermes gateway setup

Selecione SMS (Twilio) e siga as instruções.

Prefere configuração manual? Adicione isso ao ~/.hermes/.env:

TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=seu_auth_token_aqui
TWILIO_PHONE_NUMBER=+15551234567

# Segurança: restrinja a números de telefone específicos (recomendado)
SMS_ALLOWED_USERS=+15559876543,+15551112222

# Opcional: defina um canal principal para entrega de tarefas agendadas
SMS_HOME_CHANNEL=+15559876543

Passo 3: Configure o Webhook do Twilio

No Console do Twilio, vá para Phone Numbers → Manage → Active Numbers, clique no seu número e, em Messaging → A MESSAGE COMES IN, defina o webhook para:

https://seu-servidor:8080/webhooks/twilio

Defina o método HTTP como POST.

Importante: Defina SMS_WEBHOOK_URL com a mesma URL exata que você configurou no Twilio. Isso é necessário para a validação de assinatura:

SMS_WEBHOOK_URL=https://seu-servidor:8080/webhooks/twilio

A porta do webhook é 8080 por padrão, mas você pode alterá-la com SMS_WEBHOOK_PORT.

Passo 4: Inicie o Gateway

hermes gateway

Você deve ver algo como:

[sms] Servidor de webhook do Twilio ouvindo em 127.0.0.1:8080, de: +1555***4567

Agora envie uma mensagem para o seu número do Twilio — o Hermes vai responder via SMS.

Como o Comportamento do SMS Difere

SMS é um meio de texto puro, então o Hermes se adapta:

Sem Markdown — Ele é removido automaticamente, já que o SMS renderiza como caracteres literais
Limite de 1600 caracteres — Respostas mais longas são divididas em várias mensagens em pontos naturais
Prevenção de eco — Mensagens do seu próprio número do Twilio são ignoradas para evitar loops
Privacidade — Números de telefone são mascarados nos logs

Segurança é Importante

O Hermes valida que webhooks de entrada realmente vêm do Twilio verificando o cabeçalho X-Twilio-Signature (HMAC-SHA1). Isso bloqueia ataques que tentam injetar mensagens falsas.

O gateway nega todos os usuários por padrão. Você precisa configurar uma lista de permissões:

SMS_ALLOWED_USERS=+15559876543,+15551112222

Ou, se você estiver se sentindo imprudente (por favor, não faça isso):

SMS_ALLOW_ALL_USERS=true

Para desenvolvimento local sem URL pública, você pode desativar a validação de assinatura:

SMS_INSECURE_NO_SIGNATURE=true

Mas lembre-se — isso é apenas para desenvolvimento local, nunca para produção.

Um Último Aviso

SMS não tem criptografia embutida. Não use para operações sensíveis. Para qualquer coisa confidencial, fique com Signal ou Telegram.

Solução de Problemas

Mensagens não estão chegando? Verifique:

Se sua URL de webhook está correta e acessível publicamente
Se seu TWILIO_ACCOUNT_SID e TWILIO_AUTH_TOKEN estão corretos
O Console do Twilio → Monitor → Logs → Messaging para erros de entrega
Se seu número de telefone está em SMS_ALLOWED_USERS

É isso! Envie mensagem para o seu bot, receba respostas. Simples assim.