Connect a Hermes Agent to WhatsApp and Telegram

A Hermes agent running on your machine can do powerful work, but it is only as useful as your ability to reach it. Running a script or checking a terminal window breaks the flow of your day. The most natural interface for an always-on assistant is a messaging app: send a message, get a reply, move on.

This post shows you how to connect your Hermes agent to both Telegram and WhatsApp so you can interact with it from your phone, receive proactive notifications, and trigger tasks without touching your laptop.

The Architecture: Webhooks All the Way Down

Both Telegram and WhatsApp deliver messages to your agent via webhooks. When you send a message, the platform makes an HTTP POST request to a URL you register. Hermes listens on that URL, receives the message, passes it to the agent, and sends the reply back through the platform's API.

For local development, you need a tunneling tool like ngrok to expose your local Hermes webhook port to the internet. For production, deploy Hermes on a small VPS or home server with a public IP and a domain name. The agent itself still runs locally; only the webhook receiver needs a public endpoint.

# Start a public tunnel to your local Hermes webhook port
ngrok http 7654

# Hermes will listen on port 7654 for incoming webhooks
# ngrok gives you a public URL like: https://abc123.ngrok-free.app

# Tell Hermes which port to use for the webhook receiver
hermes config set webhook.port 7654

Setting Up a Telegram Bot

Telegram is the easier integration. Create a bot using BotFather (search for it in the Telegram app), get your bot token, and register a webhook URL pointing to your Hermes instance. The whole process takes about five minutes.

# Register your webhook with the Telegram Bot API
curl -X POST "https://api.telegram.org/botYOUR_BOT_TOKEN/setWebhook"   -H "Content-Type: application/json"   -d '{"url": "https://abc123.ngrok-free.app/webhooks/telegram"}'

# Confirm registration was successful
curl "https://api.telegram.org/botYOUR_BOT_TOKEN/getWebhookInfo"

Now add the Telegram channel to your Hermes agent config:

# ~/my-agents/agents/personal-assistant.yaml
name: personal-assistant
description: Personal assistant reachable via Telegram and WhatsApp

trigger:
  type: webhook
  port: 7654
  path: /webhooks/telegram
  method: POST

channels:
  telegram:
    enabled: true
    bot_token: 'YOUR_TELEGRAM_BOT_TOKEN'
    allowed_user_ids:
      - 123456789

  whatsapp:
    enabled: true
    provider: twilio
    account_sid: 'YOUR_TWILIO_ACCOUNT_SID'
    auth_token: 'YOUR_TWILIO_AUTH_TOKEN'
    from_number: 'whatsapp:+14155238886'
    allowed_numbers:
      - '+1234567890'

tools:
  - name: read_file
    type: builtin
  - name: shell_command
    type: builtin
    allowed_commands:
      - ls
      - cat
      - grep
      - date

Connecting WhatsApp via Twilio

WhatsApp requires going through an approved business API provider. Twilio is the most developer-friendly option. Sign up for a Twilio account, enable the WhatsApp sandbox in the Twilio console, and point the incoming message webhook URL to your Hermes instance. Twilio will relay every incoming WhatsApp message to your agent as an HTTP POST.

Testing and Hardening Your Integration

Test each channel in isolation before enabling both. Send a message on Telegram first and confirm the agent replies correctly. Then test WhatsApp. Once both work individually, test switching between them to confirm the agent maintains context correctly across channels.

For a production setup, add rate limiting, log every incoming message to a local file for debugging, and configure a health-check endpoint your monitoring can ping to confirm Hermes is still running. The most common failure mode is the tunnel expiring: use a persistent domain or a proper VPS rather than a development ngrok tunnel for anything you rely on daily.