@clickonsearch/whatsapp-agent 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +111 -101
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,121 +1,131 @@
|
|
|
1
1
|
# whatsapp-agent
|
|
2
2
|
|
|
3
|
-
A personal WhatsApp
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
that same chat.
|
|
8
|
-
- **From a browser chat UI** — an AG-UI protocol server (same pattern as
|
|
9
|
-
[`github-agent`](../github-agent)) with a bundled chat page, for when
|
|
10
|
-
typing in a web page is easier than typing on your phone, or you want to
|
|
11
|
-
embed it in your own tooling.
|
|
12
|
-
|
|
13
|
-
Both modes share the same underlying agent loop and the same WhatsApp MCP
|
|
14
|
-
tools, so "send Alex a message asking if she's free tomorrow" works
|
|
15
|
-
identically either way — it really sends it, through your linked account.
|
|
16
|
-
|
|
17
|
-
Requires [`@clickonsearch/whatsapp-mcp-server`](../../mcp-servers/whatsapp-mcp-server)
|
|
18
|
-
running first — that's the piece that actually holds your WhatsApp session.
|
|
19
|
-
This package is just the agent loop(s) on top of it.
|
|
20
|
-
|
|
21
|
-
## How it works: WhatsApp mode
|
|
22
|
-
|
|
23
|
-
Unlike `github-agent` (which only waits for an HTTP request), this mode is
|
|
24
|
-
push-driven:
|
|
25
|
-
|
|
26
|
-
1. Connects to `whatsapp-mcp-server`'s `/events` SSE stream and watches for
|
|
27
|
-
messages where `fromMe` is true and the chat is your own JID — i.e.
|
|
28
|
-
messages you sent to yourself.
|
|
29
|
-
2. Each one becomes the prompt for the normal provider tool-calling loop
|
|
30
|
-
(same `openai/claude/deepseek-remote-mcp-bridge` packages `github-agent`
|
|
31
|
-
uses), with the WhatsApp MCP tools (`send_message`, `list_chats`,
|
|
32
|
-
`get_recent_messages`, `search_contacts`) available — so "send Alex a
|
|
33
|
-
message asking if she's free tomorrow" or "summarize my last 20 messages
|
|
34
|
-
with Sam" both work as tool calls, not just chat.
|
|
35
|
-
3. The agent's final answer is sent back to you in the same self-chat via
|
|
36
|
-
`send_message`.
|
|
3
|
+
A personal assistant for your WhatsApp account. Message yourself to give it
|
|
4
|
+
instructions ("summarize my last chat with Sam", "send Alex a message
|
|
5
|
+
saying I'm running late"), or talk to it from a browser instead. Pick which
|
|
6
|
+
AI model does the thinking — OpenAI, Claude, or DeepSeek.
|
|
37
7
|
|
|
38
8
|
```
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
9
|
+
your WhatsApp message to yourself
|
|
10
|
+
│
|
|
11
|
+
▼
|
|
12
|
+
┌─────────────────────────────┐
|
|
13
|
+
│ whatsapp-agent │ reads the message
|
|
14
|
+
└──────────────┬──────────────┘
|
|
15
|
+
│
|
|
16
|
+
▼
|
|
17
|
+
┌─────────────────────────────┐
|
|
18
|
+
│ bridge │ openai / claude / deepseek — talks to the AI model
|
|
19
|
+
└──────────────┬──────────────┘
|
|
20
|
+
│
|
|
21
|
+
▼
|
|
22
|
+
┌─────────────────────────────┐
|
|
23
|
+
│ whatsapp-mcp-server │ acts on your account
|
|
24
|
+
└──────────────┬──────────────┘
|
|
25
|
+
│
|
|
26
|
+
▼
|
|
27
|
+
reply sent back on WhatsApp
|
|
46
28
|
```
|
|
47
29
|
|
|
48
|
-
##
|
|
30
|
+
## What you need
|
|
31
|
+
|
|
32
|
+
- Node.js 18+
|
|
33
|
+
- A WhatsApp account you can scan a QR code with (this links the agent as
|
|
34
|
+
a device on your account, same as WhatsApp Web)
|
|
35
|
+
- An API key for at least one of: OpenAI, Anthropic (Claude), DeepSeek
|
|
36
|
+
|
|
37
|
+
## Use it: over WhatsApp
|
|
38
|
+
|
|
39
|
+
**1. Start the WhatsApp connection** (own terminal, keep it running):
|
|
49
40
|
|
|
50
41
|
```bash
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
npm install && cp .env.example .env
|
|
54
|
-
npm run dev # scan the QR code it prints
|
|
42
|
+
npx @clickonsearch/whatsapp-mcp-server
|
|
43
|
+
```
|
|
55
44
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
45
|
+
Scan the QR code it prints with your phone (WhatsApp → Settings → Linked
|
|
46
|
+
devices → Link a device).
|
|
47
|
+
|
|
48
|
+
**2. Start the assistant** (second terminal):
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
ANTHROPIC_API_KEY=<your-key> npx @clickonsearch/whatsapp-agent
|
|
61
52
|
```
|
|
62
53
|
|
|
63
|
-
|
|
54
|
+
Now message **yourself** on WhatsApp ("Message yourself" in your contacts)
|
|
55
|
+
with something like "list my most recent chats" — the reply comes back in
|
|
56
|
+
that same conversation.
|
|
57
|
+
|
|
58
|
+
Swap in `OPENAI_API_KEY` + `PROVIDER=openai`, or `DEEPSEEK_API_KEY` +
|
|
59
|
+
`PROVIDER=deepseek`, to use a different model.
|
|
60
|
+
|
|
61
|
+
## Use it: browser chat
|
|
64
62
|
|
|
65
63
|
```bash
|
|
66
|
-
|
|
64
|
+
ANTHROPIC_API_KEY=<your-key> npx -p @clickonsearch/whatsapp-agent whatsapp-agent-serve
|
|
67
65
|
```
|
|
68
66
|
|
|
69
|
-
Then open
|
|
70
|
-
|
|
71
|
-
|
|
67
|
+
Then open `http://localhost:3100` and start chatting — pick your provider
|
|
68
|
+
from the dropdown. You can run this at the same time as WhatsApp mode; they
|
|
69
|
+
don't conflict.
|
|
70
|
+
|
|
71
|
+
## Use it: embedded in another tool
|
|
72
72
|
|
|
73
|
-
|
|
73
|
+
The browser chat server speaks the [AG-UI protocol](https://ag-ui.com)
|
|
74
|
+
(`POST /agent`, streaming SSE) — any AG-UI-compatible client can drive it
|
|
75
|
+
as a backend, not just the bundled page.
|
|
76
|
+
|
|
77
|
+
## Config reference
|
|
78
|
+
|
|
79
|
+
| Env var | Required | Default |
|
|
80
|
+
| -------------------- | -------------------- | -------------------------- |
|
|
81
|
+
| `PROVIDER` | no | `openai` |
|
|
82
|
+
| `OPENAI_API_KEY` | if using OpenAI | |
|
|
83
|
+
| `OPENAI_MODEL` | no | `gpt-4.1` |
|
|
84
|
+
| `ANTHROPIC_API_KEY` | if using Claude | |
|
|
85
|
+
| `ANTHROPIC_MODEL` | no | `claude-sonnet-5` |
|
|
86
|
+
| `DEEPSEEK_API_KEY` | if using DeepSeek | |
|
|
87
|
+
| `DEEPSEEK_MODEL` | no | `deepseek-chat` |
|
|
88
|
+
| `WHATSAPP_MCP_URL` | no | `http://localhost:4100` |
|
|
89
|
+
| `PORT` | no, browser chat only | `3100` |
|
|
90
|
+
|
|
91
|
+
## Good to know
|
|
92
|
+
|
|
93
|
+
- Only messages in your own "Message yourself" chat trigger the assistant
|
|
94
|
+
— nobody else can trigger it by messaging you.
|
|
95
|
+
- Each WhatsApp message is its own fresh instruction with no memory of
|
|
96
|
+
earlier ones. The browser chat remembers the conversation; WhatsApp mode
|
|
97
|
+
doesn't (yet).
|
|
98
|
+
- Chat history is only kept in memory while `whatsapp-mcp-server` is
|
|
99
|
+
running (up to 200 messages per chat) — it's not saved anywhere
|
|
100
|
+
permanent.
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
## For developers
|
|
105
|
+
|
|
106
|
+
**Running from source:**
|
|
74
107
|
|
|
75
108
|
```bash
|
|
76
|
-
|
|
77
|
-
|
|
109
|
+
# terminal 1
|
|
110
|
+
cd mcp-servers/whatsapp-mcp-server
|
|
111
|
+
npm install
|
|
112
|
+
cp .env.example .env
|
|
113
|
+
npm run dev
|
|
114
|
+
|
|
115
|
+
# terminal 2
|
|
116
|
+
cd agents/whatsapp-agent
|
|
117
|
+
npm install
|
|
118
|
+
cp .env.example .env # fill in a provider key
|
|
119
|
+
npm run dev # WhatsApp mode
|
|
120
|
+
npm run serve # or browser chat
|
|
78
121
|
```
|
|
79
122
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
-
|
|
88
|
-
|
|
89
|
-
You can run this alongside WhatsApp mode (`npm run dev` in one terminal,
|
|
90
|
-
`npm run serve` in another) — they're independent processes hitting the
|
|
91
|
-
same `whatsapp-mcp-server`, so either one can send/read messages at any
|
|
92
|
-
time.
|
|
93
|
-
|
|
94
|
-
## Config
|
|
95
|
-
|
|
96
|
-
| Env var | Required | Notes |
|
|
97
|
-
| -------------------- | ----------------------- | --------------------------------------------------- |
|
|
98
|
-
| `WHATSAPP_MCP_URL` | no (default `http://localhost:4100`) | where whatsapp-mcp-server is running |
|
|
99
|
-
| `PORT` | no (default `3100`) | browser chat UI / AG-UI server only |
|
|
100
|
-
| `PROVIDER` | no (default `openai`) | `openai`, `claude`, or `deepseek` |
|
|
101
|
-
| `OPENAI_API_KEY` | when provider=openai | |
|
|
102
|
-
| `OPENAI_MODEL` | no (default `gpt-4.1`) | |
|
|
103
|
-
| `ANTHROPIC_API_KEY` | when provider=claude | |
|
|
104
|
-
| `ANTHROPIC_MODEL` | no (default `claude-sonnet-5`) | |
|
|
105
|
-
| `DEEPSEEK_API_KEY` | when provider=deepseek | |
|
|
106
|
-
| `DEEPSEEK_MODEL` | no (default `deepseek-chat`) | |
|
|
107
|
-
|
|
108
|
-
## Known limitations (v1)
|
|
109
|
-
|
|
110
|
-
- WhatsApp mode is single-turn per instruction: each self-message is its
|
|
111
|
-
own fresh prompt, with no memory across separate instructions. The
|
|
112
|
-
browser chat UI (AG-UI mode) doesn't have this limitation — like
|
|
113
|
-
`github-agent`, it flattens prior turns in the conversation into a system
|
|
114
|
-
preamble, so follow-up questions in the same chat session work.
|
|
115
|
-
- Only your own "Message yourself" chat triggers the WhatsApp-mode
|
|
116
|
-
assistant. Any other incoming message is ignored by design, so it can't
|
|
117
|
-
be triggered by someone messaging you.
|
|
118
|
-
- `whatsapp-mcp-server`'s chat/message recall is in-memory only (not
|
|
119
|
-
persisted across restarts) and capped at the last 200 messages per chat —
|
|
120
|
-
it does get real history via WhatsApp's own backfill-on-connect, just not
|
|
121
|
-
unbounded history.
|
|
123
|
+
WhatsApp mode is push-driven, not request/response: it subscribes to
|
|
124
|
+
`whatsapp-mcp-server`'s `/events` stream, and any message you send yourself
|
|
125
|
+
becomes a prompt for the same provider tool-calling loop `github-agent`
|
|
126
|
+
uses, with WhatsApp's tools (`send_message`, `list_chats`,
|
|
127
|
+
`get_recent_messages`, `search_contacts`) available. The reply is sent back
|
|
128
|
+
via `send_message` once the model finishes.
|
|
129
|
+
|
|
130
|
+
The browser chat is an AG-UI protocol server, same shape as
|
|
131
|
+
`github-agent`'s (`POST /agent`, streaming SSE).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@clickonsearch/whatsapp-agent",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "Personal WhatsApp assistant, usable two ways: message yourself on WhatsApp to give it instructions, or drive it from a browser chat UI over the AG-UI protocol. Routed through OpenAI, Claude, or DeepSeek depending on preference.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -29,9 +29,9 @@
|
|
|
29
29
|
"dev:serve": "tsx src/server-cli.ts"
|
|
30
30
|
},
|
|
31
31
|
"dependencies": {
|
|
32
|
-
"@clickonsearch/openai-remote-mcp-bridge": "^0.
|
|
33
|
-
"@clickonsearch/claude-remote-mcp-bridge": "^0.
|
|
34
|
-
"@clickonsearch/deepseek-remote-mcp-bridge": "^0.
|
|
32
|
+
"@clickonsearch/openai-remote-mcp-bridge": "^0.2.0",
|
|
33
|
+
"@clickonsearch/claude-remote-mcp-bridge": "^0.2.0",
|
|
34
|
+
"@clickonsearch/deepseek-remote-mcp-bridge": "^0.2.0",
|
|
35
35
|
"openai": "^4.68.0",
|
|
36
36
|
"@anthropic-ai/sdk": "^0.32.1",
|
|
37
37
|
"@ag-ui/core": "^1.0.0",
|