> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zapbip.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hermes

> Write to Hermes on WhatsApp and have it answer, with no time limit.

## What works

Hermes keeps listening on your WhatsApp through a small zapbip plugin. You write first or answer a question later, and the message reaches the Hermes session.

WhatsApp: Hermes

### Messages you forward

A message you forwarded from someone else reaches Hermes with a label that says you did not write it, so Hermes does not treat it as your instruction.

## How it listens

Rung: Local. While a question is open, Hermes waits up to 50 seconds at a time. If you have not answered, the wait ends as pending and Hermes calls again, as many times as it takes, with no time limit.

The plugin holds one connection to zapbip open, with no time limit. If the network drops it reconnects by itself, waiting a little longer after each failed try (1 second at first, 30 seconds at most). Messages you send meanwhile wait in your zapbip inbox, and the plugin picks up every one that was not answered as soon as it is back.

### If the plugin cannot be installed

Hermes can poll instead. Add the MCP server from the setup and create a job every 1 minute that calls `check_inbox`. Your messages wait up to a minute, and the answer comes the same way.

## Set up from zero

### What you need

* Hermes with its gateway running.
* Your connection link, the same `https://.../c/<secret>/mcp` link your AI uses to talk to zapbip. Treat it like a password.

### Install the plugin

Install the package into the Python environment Hermes runs in:

```bash theme={null}
d=$(mktemp -d) && curl -fsSL https://mcp.zapbip.com/pkg/zapbip_platform-0.1.0-requirements.txt -o "$d/zapbip-requirements.txt" && python3 -c 'import hashlib,sys; sys.exit(hashlib.sha256(open(sys.argv[1],"rb").read()).hexdigest() != sys.argv[2])' "$d/zapbip-requirements.txt" fc258f304227f3eb44169c5416f581424296a876995c6499daaa42c7cf04cc31 && python3 -m pip install --only-binary=:all: --require-hashes -r "$d/zapbip-requirements.txt"
```

Then enable it in `~/.hermes/config.yaml`:

```yaml theme={null}
plugins:
  enabled:
    - zapbip-platform
```

Set the link and who may talk to Hermes in the environment the gateway runs in, never in a file you share:

```bash theme={null}
export ZAPBIP_CONNECTION_LINK='https://<host>/c/<secret>/mcp'
export ZAPBIP_ALLOWED_USERS=owner
```

The file that holds your connection link works like a password. Give it permission `600` so only your user can read it, and never share it or commit it:

```bash theme={null}
chmod 600 <file>
```

Restart the gateway.

Run only one listener per agent: the plugin or `npx zapbip@0.1.0 listen`, never both. A second listener replaces the first.

### How Hermes answers

Hermes sends its replies to your messages back through the plugin itself, with no extra setup.

Add zapbip as an MCP server so Hermes can also start a conversation with you, ask you a question with buttons and wait for the answer, and use the polling fallback below:

```yaml theme={null}
mcp_servers: { zapbip: { url: 'https://<host>/c/<secret>/mcp' } }
```

Then ask Hermes on WhatsApp to send `✅ installed`. If that message arrives, it works.

WhatsApp: zapbip

## Check it works

| You see | What it means |
| - | - |
| No answer to your message | The gateway is not running, or the plugin is not in `plugins.enabled`. |
| The plugin stops by itself | Another plugin or connector started for the same connection and replaced it. |
| Hermes cannot start a conversation or ask you | The `zapbip` MCP server is missing from `config.yaml`. |
| The plugin stops with an error | The link is unknown or the connection was revoked. Ask for a new one. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.