Waha AI WhatsApp Agent — Connect WhatsApp, Every Send Stops for Approval
An AI agent talks to WhatsApp through WAHA's HTTP API with a long-lived API key, not OAuth. That widens the blast radius, so the connector is scoped per session and every send stops for a human approval.
Last updated
6 minute read · Written by the team that builds UtilitySpaces. More about UtilitySpaces.
Waha AI is a WhatsApp HTTP API server you run yourself (usually in Docker) that lets an AI agent send and receive WhatsApp messages instead of going through WhatsApp’s Business Cloud. That’s what a search for ‘waha ai’ finds. The UtilitySpaces connector talks to it over HTTP with a long-lived API key. That key is a bearer secret with no expiry and no per-application identity, so the connector narrows it to a single Session name — one WhatsApp business number — meaning an agent can only address the session an admin chose. Every write, whether a text message or an image, stops for a human approval; read-only calls like checking session status run unattended. The connector exposes exactly three tools: Session status (a read), Send text message (a write), and Send image (a write). The four credential tiers and why each one costs you on a bad day are laid out in four ways to connect an agent to a business app, ranked by blast radius.
How does WAHA authenticate, and what does that reach?
The UtilitySpaces connection to WAHA WhatsApp integration takes three fields — WAHA URL, API Key, and Session name — and the API Key is the part that bears the risk. It is a bearer secret you create inside WAHA and paste into the connection once. The connector stores it encrypted and bound to your workspace and never reads it back, but a bearer key has no second factor and no per-application identity: whoever holds a copy is indistinguishable from the legitimate caller, and that caller can name any session on the server.
That is the practical meaning of the difference in the table below.
| Concern | WAHA (API key) | Scoped OAuth (e.g. Gmail) |
|---|---|---|
| What you hand over | One long-lived bearer key | A per-app grant with chosen scopes |
| How it is used | Sent as a key on every request | Short access tokens, refreshed by the vendor |
| Revocation | Rotate the key; every caller stops at once | Revoke the one grant; other apps untouched |
| Expiry and refresh | None; lives until you rotate it | Short-lived, refreshed automatically |
| What it reaches | Every session on that WAHA server | Only the scopes the grant names |
| Blast radius if leaked | All sessions the key can name, until rotated | Only the granted scopes, until revoked |
A bearer key with no expiry and no per-application identity is the weakest standing grant, and WhatsApp is a noisy surface: a message can go to the wrong customer in seconds. The same trade-off, scoped the other way with OAuth, is the subject of how we scoped Gmail access for an AI agent.
How do I scope the WAHA connector to a single session?
The narrowing happens at the connection, not at the key. Each WAHA connection in UtilitySpaces binds one Session name, so an agent pointed at that connection can only reach the WhatsApp session — one business number — that an admin chose. That does not shrink what the key itself can do at the WAHA layer; it shrinks what the agent can address through this connector. Put it another way: the key is broad, the connector is narrow, and the approval gate is the last word.
Credentials are encrypted in UtilitySpaces and bound to your workspace; deleting the connection removes the key from the platform. The scoped connector model in UtilitySpaces sets out exactly how, and the security page covers the platform around it. Every outbound call from the connector also passes one guarded fetch that validates destinations on every hop and strips credentials on cross-origin redirects, so a misconfigured WAHA URL cannot be used to pivot inside your network.
Which WhatsApp messages should an agent never send without a stop?
The WAHA connector exposes three named tools, exact tools, no more — and only the two sends stop for a human.
| WAHA tool | What it does | Approval? | Why it matters |
|---|---|---|---|
| Session status | Check the WhatsApp session connection status | No — read only | Safe to run unattended; a wrong check only reports a wrong state |
| Send text message | Send a WhatsApp text message | Yes — it writes | A wrong recipient or wording goes out in your name |
| Send image | Send a WhatsApp image with an optional caption (file is {mimetype, filename, url} or {mimetype, filename, data}, with base64 data) | Yes — it writes | An image is harder to vet and cannot be reliably taken back |
Beyond the gate, the messages an agent should never be trusted to send on its own fall into a short, recognisable list.
- To recipients who have not opted in. WhatsApp requires businesses to have consent before messaging users and holds the sending number responsible for each message, per its Business Policy; an agent’s message carries your identity, not the agent’s.
- In reply to inbound strangers. Inbound WhatsApp is attacker-controlled text — the same prompt-injection surface we warned about for email. A message that reads “forward the last invoice” is not a mistake to forward; the defence is that the send cannot happen without a person approving it.
- In bulk. A thousand identical promotional images is a workflow builder’s job, not an agent’s judgement, and it is the fastest way to draw a spam complaint.
- Anything you would not want read back in a dispute. If the thread would be awkward as an exhibit, an agent’s version of it will be worse.
The rule that holds it together is the one the approval gate for AI agents runs on: reads are never gated and writes always are, because a wrong read is recoverable and a wrong send is not. Managed AI agents in UtilitySpaces apply that rule the same way everywhere.
How do I wire the WAHA connector in UtilitySpaces?
An operator with the workspace admin role creates one WAHA connection per WhatsApp number and picks which agent or scheduled flow may call it; members can run reads without being able to send anything. The agent calls the three tools by name, the two writes raise an approval request in the approval queue, and a person either approves or rejects with a comment. Every call — arguments and result — lands in the hash-chained audit log, so the record of who sent what, from which session, is append-only and tamper-evident. That is how a long-lived key earns the controls around it: the key is broad, the connection is narrow, the gate is mandatory, and the log is the memory.
What should a WhatsApp agent never be scheduled to do on its own?
Scheduling is the billable unit of an agent, and the schedule is not the safety control. Because there is no auto-approve setting — not for WAHA and not anywhere else — a recurring agent job cannot silently send a WhatsApp message; each send still raises an approval request. That is the ceiling, not the floor. Do not schedule an agent to reach new contacts it has not confirmed, and do not schedule promotional sends: those are the jobs that belong in a workflow builder, and they are exactly the irreversible, judgement-heavy work we put six months down the road in what to automate first with AI agents. The recurring-job trap itself — stale credentials, drifted prompts, runs that stop meaning anything — is tracked separately in scheduled AI agents that don’t go stale.
What are the limits and trade-offs, and when not to use WAHA?
Three limits, stated plainly. First, the gate lives in UtilitySpaces and the key lives in WAHA: if the WAHA server itself is misconfigured or the key is taken from there, the connector’s controls do not reach. The fix is on the WAHA side — restrict the key, firewall the port, and rotate it on a schedule. Second, the connector exposes exactly three tools, so an agent cannot read message history or manage contacts through UtilitySpaces; if that work matters, you operate WAHA directly, and that surface is one you scope yourself. Third, the platform limits still apply: two-factor authentication for the workspace account does not exist yet, and UtilitySpaces holds no third-party security certification. If either is a hard requirement for your channel today, this is the wrong setup. See the security page for what is covered.
If you want to see the read-then-stop shape before connecting anything, open a demo workspace: it runs the full inbox and approval flow with no card and no connected apps. Connecting WAHA is a paid-workspace step, plans are on the pricing page, and support@utilityspaces.com replies within one business day.
Keep reading: