Hermes Agent Integration

Kirimdev’s Hermes Agent integration lets owners chat with an AI on WhatsApp: message your business number from a personal phone, the agent replies and runs commands through the Public API — same surface as REST and MCP. The official kirimdev-hermes plugin receives webhooks from Kirimdev; you host the Hermes gateway and LLM on your VPS.

Not a customer-facing bot

This integration is for owners and trusted internal numbers — not end-customer AI support. Customer chats stay in the Kirimdev inbox, n8n workflows, or your own API integrations. Unknown senders are blocked from the agent by default (unknown tier).

Webhook in, API out

Kirimdev holds Meta credentials, message storage, and delivery. You run the Hermes gateway on your VPS — the plugin bridges webhook in and Public API out.

Same API key

Reuse kdv_live_… keys and webhook secrets from the dashboard. No second signup — Hermes is infra you operate.

Owner access control

KIRIMDEV_OWNER_USERS and optional KIRIMDEV_ALLOWED_USERS for internal numbers. Everyone else stays on the normal inbox path.

24/7 gateway

A small VPS runs hermes gateway run behind nginx. Chat works even when your laptop is closed.

How it fits together

Owner (personal WhatsApp)
       │  messages business line (on Kirimdev)
       ▼
  Kirimdev Cloud API
       │  POST message.received  (X-Kirim-Signature)
       ▼
  Your HTTPS endpoint  ──►  Hermes gateway (:8646)
       │                         │
       │                         ├── LLM (Anthropic, OpenAI, …)
       │                         └── POST /v1/{phone_number_id}/messages
       ▼
  Owner sees reply + typing indicator on WhatsApp

Kirimdev handles Meta credentials, message storage, and delivery receipts. Hermes handles reasoning, tool use, and orchestration. The plugin verifies X-Kirim-Signature on every inbound delivery and forwards only payloads for phone numbers listed in KIRIMDEV_ENABLED_NUMBERS.

MCP vs Hermes — both access Kirimdev

Both are Kirimdev integrations for operators, not customers:

	MCP server	Hermes + kirimdev-hermes
Chat via	AI agent / MCP client (Claude, ChatGPT, Cursor, custom agents, …)	WhatsApp — to your business number
Runtime	When the MCP client is in use	Always-on gateway on your VPS
Inbound	You pull via MCP tools	Kirimdev pushes message.received webhooks
Outbound	Model calls send_message in your session	Agent replies in the owner’s chat thread
Best for	Test API, debug, ad-hoc tasks via AI	Owner: send templates, check inbox on the go
Setup	MCP Setup — ~5 minutes	Hermes Setup — VPS + DNS

They compose

Many teams use both: MCP at the desk, Hermes on the go. Same API keys, same phone numbers — different chat surfaces into Kirimdev.

What owners can do

Chat-driven Kirimdev ops

Put your mobile number in KIRIMDEV_OWNER_USERS. Message the business line and ask in plain language — Hermes calls kirimdev_* tools against your Kirimdev account:

“List approved templates on the store number.”

“Send template order_shipped to 628123456789 with tracking JNE123.”

“How many open conversations today?”

Customers only receive messages you ask the agent to send — they do not chat with Hermes directly.

Set KIRIMDEV_OWNER_FULL_AGENT=false if owners should only use Kirimdev messaging tools (no shell/web).

Internal team numbers

Add co-founders or ops leads to KIRIMDEV_ALLOWED_USERS so they can use the same agent from their phones. Numbers not on either list hit the unknown tier and do not engage the agent — their messages flow to the normal Kirimdev inbox instead.

Scheduled digests to the owner

Set KIRIMDEV_HOME_CHANNEL to a composite id ({phone_number_id}:{owner_phone}) or an owner phone with KIRIMDEV_DEFAULT_PHONE_NUMBER_ID. Hermes cron jobs can push daily summaries to that channel — open ticket counts, reminders, etc. Mass campaigns still belong in Kirimdev Broadcasts.

What the plugin exposes

Surface	Details
Webhook	POST /webhook — subscribe via /v1/webhook_subscriptions with event message.received
Health	GET /health → {"status":"ok","platform":"kirimdev",…}
Tools	kirimdev_* namespace on toolset hermes-kirimdev (send, templates, …)
CLI send	hermes send --to kirimdev:{phone_number_id}:{customer} "Halo"

The plugin defaults to https://api.kirimdev.com/v1 — no manual API URL configuration for normal Kirimdev accounts.

Full deploy steps (nginx, SSL, systemd) live in the plugin repo’s DEPLOY.md.

Limits & expectations

• Self-hosted — you provision the VPS, LLM API keys, and Hermes upgrades. Kirimdev does not run Hermes for you.
• One webhook URL per gateway — typical pattern is one dedicated subdomain (e.g. hermes-webhooks.example.com) per environment.
• Typing indicator — requires plugin v1.0.0+ and Kirimdev API support for typing on read (see Mark as read).
• Not a BSP — Meta bills WhatsApp usage to your WABA; Kirimdev bills platform usage per your plan. Hermes + LLM inference are your infra cost.

Where to next

Setup guide

MCP server (AI agent access)

Plugin source (GitHub)