Pular para o conteúdo principal

Documentação oficial desta página · v0.20.6

SMS (Twilio)

O Hermes se conecta a SMS pela API da Twilio. As pessoas mandam mensagem para o seu número da Twilio e recebem respostas do agente — mesma experiência de conversa do Telegram ou do Discord, mas por mensagem de texto comum.

Credenciais compartilhadas

O gateway de SMS compartilha credenciais com a skill opcional de telefonia. Se você já configurou a Twilio para chamadas de voz ou SMS avulsos, o gateway funciona com os mesmos TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN e TWILIO_PHONE_NUMBER.

Pré-requisitos​

  • Conta na Twilio — cadastre em twilio.com (há teste gratuito)
  • Um número da Twilio com capacidade de SMS
  • Um servidor acessível pela internet — a Twilio manda webhooks para o seu servidor quando chega SMS
  • aiohttp — cd ~/.hermes/hermes-agent && uv pip install -e ".[sms]"

Passo 1: pegue suas credenciais​

  1. Entre no console da Twilio
  2. Copie o Account SID e o Auth Token do painel
  3. Vá em Phone Numbers → Manage → Active Numbers — anote o número no formato E.164 (por exemplo, +5511999999999)

Passo 2: configure o Hermes​

hermes gateway setup

Escolha SMS (Twilio) na lista de plataformas. O assistente pede as credenciais.

Configuração manual​

Acrescente em ~/.hermes/.env:

TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=seu_auth_token
TWILIO_PHONE_NUMBER=+5511999999999

# Segurança: restrinja a números específicos (recomendado)
SMS_ALLOWED_USERS=+5511988887777,+5511977776666

# Opcional: canal principal, para entrega de tarefas de cron
SMS_HOME_CHANNEL=+5511988887777

Passo 3: configure o webhook na Twilio​

A Twilio precisa saber para onde mandar as mensagens que chegam. No console da Twilio:

  1. Vá em Phone Numbers → Manage → Active Numbers
  2. Clique no seu número
  3. Em Messaging → A MESSAGE COMES IN, defina:
    • Webhook: https://seu-servidor:8080/webhooks/twilio
    • HTTP Method: POST
Expor o webhook

Se você roda o Hermes localmente, use um túnel para expor o webhook:

# com cloudflared
cloudflared tunnel --url http://localhost:8080

# com ngrok
ngrok http 8080

Use a URL pública resultante como webhook na Twilio.

Defina o SMS_WEBHOOK_URL com a mesma URL que você configurou na Twilio. Isso é obrigatório para a validação de assinatura — o adaptador se recusa a subir sem essa variável:

# Precisa bater com a URL do webhook no console da Twilio
SMS_WEBHOOK_URL=https://seu-servidor:8080/webhooks/twilio

A porta do webhook é 8080 por padrão. Troque com:

SMS_WEBHOOK_PORT=3000

Passo 4: suba o gateway​

hermes gateway

Você deve ver:

[sms] Twilio webhook server listening on 127.0.0.1:8080, from: +1555***4567

Se aparecer Refusing to start: SMS_WEBHOOK_URL is required, defina o SMS_WEBHOOK_URL com a URL pública configurada no console da Twilio (passo 3).

Mande uma mensagem para o seu número da Twilio — o Hermes responde por SMS.

Variáveis de ambiente​

VariávelObrigatóriaDescrição
TWILIO_ACCOUNT_SIDSimAccount SID da Twilio (começa com AC)
TWILIO_AUTH_TOKENSimAuth Token (usado também na validação de assinatura)
TWILIO_PHONE_NUMBERSimSeu número da Twilio (formato E.164)
SMS_WEBHOOK_URLSimURL pública, para a validação de assinatura — precisa bater com a do console
SMS_WEBHOOK_PORTNãoPorta do webhook (padrão: 8080)
SMS_WEBHOOK_HOSTNãoEndereço em que escuta (padrão: 127.0.0.1)
SMS_INSECURE_NO_SIGNATURENãotrue desliga a validação de assinatura (só desenvolvimento local — nunca em produção)
SMS_ALLOWED_USERSNãoNúmeros E.164 autorizados, separados por vírgula
SMS_ALLOW_ALL_USERSNãotrue libera qualquer pessoa (não recomendado)
SMS_HOME_CHANNELNãoNúmero para entrega de cron e notificações
SMS_HOME_CHANNEL_NAMENãoNome de exibição do canal principal (padrão: Home)

Comportamento específico do SMS​

  • Só texto puro — o markdown é removido, porque o SMS o mostraria como caracteres literais
  • Limite de 1600 caracteres — respostas maiores são divididas em várias mensagens, em pontos naturais (quebras de linha, depois espaços)
  • Prevenção de eco — mensagens vindas do seu próprio número da Twilio são ignoradas, para evitar laços
  • Números ocultos nos logs — os números de telefone são mascarados, por privacidade

Segurança​

Validação de assinatura​

O Hermes confere que os webhooks vêm mesmo da Twilio, verificando o cabeçalho X-Twilio-Signature (HMAC-SHA1). Isso impede que um atacante injete mensagens forjadas.

O SMS_WEBHOOK_URL é obrigatório. Defina com a URL pública do console da Twilio. O adaptador se recusa a subir sem ela.

Para desenvolvimento local, sem URL pública, dá para desligar a validação:

# Só desenvolvimento local — NÃO use em produção
SMS_INSECURE_NO_SIGNATURE=true

Listas de permissão​

O gateway nega todos os usuários por padrão. Configure uma lista:

# Recomendado: restringir a números específicos
SMS_ALLOWED_USERS=+5511988887777,+5511977776666

# Ou liberar todo mundo (NÃO recomendado com bots que têm acesso ao terminal)
SMS_ALLOW_ALL_USERS=true
aviso

SMS não tem criptografia embutida. Não use SMS para operações sensíveis, a menos que você entenda as implicações. Para casos sensíveis, prefira Signal ou Telegram.

Resolução de problemas​

Mensagens não chegam​

  1. Confira se a URL do webhook está certa e acessível pela internet
  2. Confirme o TWILIO_ACCOUNT_SID e o TWILIO_AUTH_TOKEN
  3. Olhe o console da Twilio em Monitor → Logs → Messaging, atrás de erros de entrega
  4. Garanta que o seu número está no SMS_ALLOWED_USERS (ou use SMS_ALLOW_ALL_USERS=true)

Respostas não são enviadas​

  1. Confira o TWILIO_PHONE_NUMBER (formato E.164, com +)
  2. Confirme que sua conta na Twilio tem números com capacidade de SMS
  3. Procure erros da API da Twilio nos logs do gateway

Conflito de porta do webhook​

Se a porta 8080 já está em uso, troque:

SMS_WEBHOOK_PORT=3001

Atualize a URL do webhook no console da Twilio.