bloby-bot 0.24.0 → 0.24.3
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/package.json
CHANGED
package/supervisor/index.ts
CHANGED
|
@@ -555,7 +555,29 @@ ${connected
|
|
|
555
555
|
: '<p class="loading">Starting WhatsApp...</p>'}
|
|
556
556
|
</div>
|
|
557
557
|
${!connected ? `<script>
|
|
558
|
-
|
|
558
|
+
// Poll for status changes instead of full page reload (avoids SW reinstall cycle)
|
|
559
|
+
let polling=true;
|
|
560
|
+
async function poll(){
|
|
561
|
+
if(!polling) return;
|
|
562
|
+
try{
|
|
563
|
+
const [statusRes,qrRes]=await Promise.all([
|
|
564
|
+
fetch('/api/channels/status'),
|
|
565
|
+
fetch('/api/channels/whatsapp/qr')
|
|
566
|
+
]);
|
|
567
|
+
const statuses=await statusRes.json();
|
|
568
|
+
const qrData=await qrRes.json();
|
|
569
|
+
const wa=Array.isArray(statuses)?statuses.find(s=>s.channel==='whatsapp'):null;
|
|
570
|
+
if(wa?.connected){location.reload();return}
|
|
571
|
+
if(qrData.qr){
|
|
572
|
+
const inner=document.querySelector('.qr-inner');
|
|
573
|
+
if(inner) inner.innerHTML=qrData.qr;
|
|
574
|
+
const loading=document.querySelector('.loading');
|
|
575
|
+
if(loading) loading.remove();
|
|
576
|
+
}
|
|
577
|
+
}catch{}
|
|
578
|
+
setTimeout(poll,3000);
|
|
579
|
+
}
|
|
580
|
+
setTimeout(poll,3000);
|
|
559
581
|
|
|
560
582
|
function togglePhoneForm(){
|
|
561
583
|
document.getElementById('phoneForm').classList.toggle('visible');
|
|
@@ -585,8 +607,7 @@ ${!connected ? `<script>
|
|
|
585
607
|
const errEl=document.getElementById('codeError');
|
|
586
608
|
if(!document.getElementById('codeDisplay').classList.contains('visible')){
|
|
587
609
|
const hint=document.querySelector('.phone-hint');
|
|
588
|
-
if(hint)
|
|
589
|
-
hint.style.color='#FB4072';
|
|
610
|
+
if(hint){hint.textContent=err.message;hint.style.color='#FB4072'}
|
|
590
611
|
}else{
|
|
591
612
|
errEl.textContent=err.message;
|
|
592
613
|
}
|
|
@@ -1,214 +0,0 @@
|
|
|
1
|
-
# WhatsApp
|
|
2
|
-
|
|
3
|
-
## What This Is
|
|
4
|
-
|
|
5
|
-
Gives your agent a WhatsApp number. Connect via QR code, send and receive messages, handle voice notes, and switch between personal (channel) and business modes. Built on Baileys — no Meta Business API needed.
|
|
6
|
-
|
|
7
|
-
## Dependencies
|
|
8
|
-
|
|
9
|
-
None.
|
|
10
|
-
|
|
11
|
-
---
|
|
12
|
-
|
|
13
|
-
## How Responses Work
|
|
14
|
-
|
|
15
|
-
**Your text response IS the WhatsApp reply.** When you receive a message tagged with `[WhatsApp | ...]`, the supervisor takes whatever you respond with and sends it directly to WhatsApp. You do NOT need to use curl or `/api/channels/send` to reply — just respond normally.
|
|
16
|
-
|
|
17
|
-
**Do NOT use `/api/channels/send` to reply to incoming WhatsApp messages.** That endpoint is ONLY for proactive messages (during pulse, cron, or when you want to initiate a conversation). If you use it to reply, the person will get duplicate messages.
|
|
18
|
-
|
|
19
|
-
**Adjust your style for WhatsApp:** Keep messages shorter and more conversational than chat. No markdown headers, no code blocks unless asked. Think texting, not email.
|
|
20
|
-
|
|
21
|
-
---
|
|
22
|
-
|
|
23
|
-
## How Messages Arrive
|
|
24
|
-
|
|
25
|
-
When a message arrives via WhatsApp, the supervisor wraps it with context:
|
|
26
|
-
|
|
27
|
-
```
|
|
28
|
-
[WhatsApp | 5511999888777 | customer | Alice]
|
|
29
|
-
Hi, I'd like to schedule an appointment.
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
The format is: `[WhatsApp | phone | role | name (optional)]`
|
|
33
|
-
|
|
34
|
-
- **role=admin**: This is your human or an authorized admin. Use your normal personality, full capabilities, main system prompt.
|
|
35
|
-
- **role=customer**: This is someone else messaging. Follow the instructions from the active skill's SCRIPT.md (loaded as your system prompt for that conversation).
|
|
36
|
-
|
|
37
|
-
---
|
|
38
|
-
|
|
39
|
-
## Channel Config
|
|
40
|
-
|
|
41
|
-
Your channel configuration is injected into your context (if any channels are configured). It comes from `~/.bloby/config.json` — a file OUTSIDE your workspace that the supervisor manages.
|
|
42
|
-
|
|
43
|
-
---
|
|
44
|
-
|
|
45
|
-
## Modes
|
|
46
|
-
|
|
47
|
-
**Channel Mode** (default): Your human's own WhatsApp number. Only self-chat (messages your human sends to themselves) triggers you — messages from other people are completely ignored. This is "just talk to me" mode.
|
|
48
|
-
|
|
49
|
-
**Business Mode**: Bloby has its own dedicated WhatsApp number. Numbers in the `admins` array get admin access (main system prompt). Everyone else is a customer and gets the support prompt from the active skill's SCRIPT.md.
|
|
50
|
-
|
|
51
|
-
---
|
|
52
|
-
|
|
53
|
-
## Setup
|
|
54
|
-
|
|
55
|
-
### 1. Connect WhatsApp
|
|
56
|
-
|
|
57
|
-
When your human asks to configure WhatsApp:
|
|
58
|
-
|
|
59
|
-
1. Start the connection:
|
|
60
|
-
```bash
|
|
61
|
-
curl -s -X POST http://localhost:7400/api/channels/whatsapp/connect
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
2. Tell them to open the QR page: `http://localhost:7400/api/channels/whatsapp/qr-page`
|
|
65
|
-
(Don't mention the URL until you are actually starting the connection)
|
|
66
|
-
|
|
67
|
-
3. They scan the QR with their WhatsApp app
|
|
68
|
-
|
|
69
|
-
4. The default mode is **channel** (self-chat only)
|
|
70
|
-
|
|
71
|
-
If the QR page doesn't load, make sure you initiated the connection first (step 1).
|
|
72
|
-
|
|
73
|
-
**On mobile?** The QR page also offers a "Link with phone number instead" option. The user enters their phone number, gets an 8-character code, and types it into WhatsApp (Settings > Linked Devices > Link a Device > "Link with phone number instead"). No camera needed.
|
|
74
|
-
|
|
75
|
-
### 2. Choose a Mode
|
|
76
|
-
|
|
77
|
-
**Channel mode** (default) — personal assistant. Only self-chat triggers the agent:
|
|
78
|
-
|
|
79
|
-
```bash
|
|
80
|
-
curl -s -X POST http://localhost:7400/api/channels/whatsapp/configure \
|
|
81
|
-
-H "Content-Type: application/json" \
|
|
82
|
-
-d '{"mode":"channel"}'
|
|
83
|
-
```
|
|
84
|
-
|
|
85
|
-
**Business mode** — customer-facing. The agent responds to incoming messages from customers using a skill's SCRIPT.md. Admin numbers get full agent access:
|
|
86
|
-
|
|
87
|
-
```bash
|
|
88
|
-
curl -s -X POST http://localhost:7400/api/channels/whatsapp/configure \
|
|
89
|
-
-H "Content-Type: application/json" \
|
|
90
|
-
-d '{"mode":"business","admins":["ADMIN_PHONE_1","ADMIN_PHONE_2"],"skill":"SKILL_FOLDER_NAME"}'
|
|
91
|
-
```
|
|
92
|
-
|
|
93
|
-
Replace `ADMIN_PHONE_1` with the human's phone number (digits only, with country code, e.g. `5511999887766`). Replace `SKILL_FOLDER_NAME` with the skill that should handle customer conversations (e.g. `whatsapp-clinic-secretary`).
|
|
94
|
-
|
|
95
|
-
### 3. Verify
|
|
96
|
-
|
|
97
|
-
```bash
|
|
98
|
-
curl -s http://localhost:7400/api/channels/status
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
Expected: `"channel":"whatsapp","connected":true`
|
|
102
|
-
|
|
103
|
-
---
|
|
104
|
-
|
|
105
|
-
## Business Mode — Active Skill
|
|
106
|
-
|
|
107
|
-
Only ONE skill can be active for customer-facing mode at a time. The active skill is set in the channel config (`channels.whatsapp.skill`). When your human asks to switch skills:
|
|
108
|
-
|
|
109
|
-
```bash
|
|
110
|
-
curl -s -X POST http://localhost:7400/api/channels/whatsapp/configure \
|
|
111
|
-
-H "Content-Type: application/json" -d '{"skill":"whatsapp-clinic"}'
|
|
112
|
-
```
|
|
113
|
-
|
|
114
|
-
The active skill should have:
|
|
115
|
-
- `SCRIPT.md` — the customer-facing system prompt (loaded automatically for customer conversations)
|
|
116
|
-
- Optionally a `customer_data/` directory — per-customer memory files (named by phone number, e.g. `5511999887766.md`)
|
|
117
|
-
|
|
118
|
-
---
|
|
119
|
-
|
|
120
|
-
## Sending Proactive Messages
|
|
121
|
-
|
|
122
|
-
To INITIATE a WhatsApp message (during pulse, cron, or when you want to reach out first):
|
|
123
|
-
|
|
124
|
-
```bash
|
|
125
|
-
curl -s -X POST http://localhost:7400/api/channels/send \
|
|
126
|
-
-H "Content-Type: application/json" \
|
|
127
|
-
-d '{"channel":"whatsapp","to":"5511999888777","text":"Your appointment is confirmed for tomorrow at 2pm."}'
|
|
128
|
-
```
|
|
129
|
-
|
|
130
|
-
Phone number format: digits with country code (e.g. `5511999887766`). The system normalizes to WhatsApp JID format automatically.
|
|
131
|
-
|
|
132
|
-
**Remember:** This is ONLY for starting new conversations or sending unprompted messages. When replying to an incoming message, just respond normally — the supervisor handles delivery.
|
|
133
|
-
|
|
134
|
-
---
|
|
135
|
-
|
|
136
|
-
## Customer Conversation Logs
|
|
137
|
-
|
|
138
|
-
When you finish a conversation with a **customer** via WhatsApp, save a summary to `whatsapp/{phone}.md`:
|
|
139
|
-
- Key details from the conversation
|
|
140
|
-
- Outcome (appointment scheduled, question answered, etc.)
|
|
141
|
-
- Any follow-ups needed
|
|
142
|
-
- Timestamp
|
|
143
|
-
|
|
144
|
-
This is your memory of that customer. Next time they message, read their file first.
|
|
145
|
-
|
|
146
|
-
---
|
|
147
|
-
|
|
148
|
-
## Voice Notes
|
|
149
|
-
|
|
150
|
-
Voice messages are automatically transcribed via Whisper and delivered as text. No extra setup needed if Whisper is configured on the supervisor.
|
|
151
|
-
|
|
152
|
-
## Typing Indicator
|
|
153
|
-
|
|
154
|
-
The agent automatically shows "typing..." to the recipient while composing a response. This is handled by the supervisor — no action needed from you.
|
|
155
|
-
|
|
156
|
-
## Message Buffering (Business Mode)
|
|
157
|
-
|
|
158
|
-
In business mode, rapid messages from the same customer are debounced (4-second window) and delivered together. The system maintains a 30-message conversation buffer per customer.
|
|
159
|
-
|
|
160
|
-
## Concurrent Conversations (Business Mode)
|
|
161
|
-
|
|
162
|
-
Up to 5 customer conversations can run in parallel. Additional messages queue automatically.
|
|
163
|
-
|
|
164
|
-
---
|
|
165
|
-
|
|
166
|
-
## Account Management
|
|
167
|
-
|
|
168
|
-
**Disconnect** (keep credentials for later):
|
|
169
|
-
```bash
|
|
170
|
-
curl -s -X POST http://localhost:7400/api/channels/whatsapp/disconnect
|
|
171
|
-
```
|
|
172
|
-
|
|
173
|
-
**Logout** (delete credentials, requires new QR scan):
|
|
174
|
-
```bash
|
|
175
|
-
curl -s -X POST http://localhost:7400/api/channels/whatsapp/logout
|
|
176
|
-
```
|
|
177
|
-
|
|
178
|
-
**Switch accounts** (relink): Use the "Relink" button on the QR page, or logout + connect again.
|
|
179
|
-
|
|
180
|
-
---
|
|
181
|
-
|
|
182
|
-
## Human Interaction
|
|
183
|
-
|
|
184
|
-
- The human must scan the QR code with their phone — this cannot be automated
|
|
185
|
-
- If WhatsApp disconnects (phone lost, account switched), the human needs to re-scan
|
|
186
|
-
- In business mode, explain to the human that admin numbers get full agent access while all other numbers get the customer-facing skill
|
|
187
|
-
- If the human asks about privacy: credentials are stored locally at `~/.bloby/channels/whatsapp/auth/`, never sent to external servers
|
|
188
|
-
|
|
189
|
-
---
|
|
190
|
-
|
|
191
|
-
## API Reference
|
|
192
|
-
|
|
193
|
-
| Endpoint | Method | Purpose |
|
|
194
|
-
|----------|--------|---------|
|
|
195
|
-
| `/api/channels/status` | GET | List all channel statuses |
|
|
196
|
-
| `/api/channels/whatsapp/qr` | GET | Get current QR code SVG |
|
|
197
|
-
| `/api/channels/whatsapp/qr-page` | GET | Standalone QR scanning page |
|
|
198
|
-
| `/api/channels/whatsapp/connect` | POST | Start WhatsApp (triggers QR if needed) |
|
|
199
|
-
| `/api/channels/whatsapp/disconnect` | POST | Disconnect WhatsApp |
|
|
200
|
-
| `/api/channels/whatsapp/logout` | POST | Disconnect + delete credentials |
|
|
201
|
-
| `/api/channels/whatsapp/configure` | POST | Set mode + admins + skill |
|
|
202
|
-
| `/api/channels/whatsapp/pairing-code` | POST | Get 8-char pairing code (mobile linking) |
|
|
203
|
-
| `/api/channels/send` | POST | Send proactive message via channel |
|
|
204
|
-
|
|
205
|
-
All endpoints are on `http://localhost:7400`.
|
|
206
|
-
|
|
207
|
-
---
|
|
208
|
-
|
|
209
|
-
## Technical Notes
|
|
210
|
-
|
|
211
|
-
- Baileys is a reverse-engineering of WhatsApp Web. It can break if WhatsApp changes their protocol. Reconnection is automatic on network drops.
|
|
212
|
-
- If you get error 401 (loggedOut), credentials were invalidated — the human needs to re-scan QR.
|
|
213
|
-
- If you get error 440 (connectionReplaced), another device/instance took over — do NOT auto-reconnect, ask the human.
|
|
214
|
-
- LID (Local ID) vs phone number: WhatsApp uses internal IDs. The system translates them automatically — use phone numbers in all your API calls.
|
|
@@ -1,11 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "whatsapp",
|
|
3
|
-
"version": "1.0.0",
|
|
4
|
-
"author": "newbot-official",
|
|
5
|
-
"description": "WhatsApp channel for your agent via Baileys. QR auth, messaging, voice transcription, channel and business modes.",
|
|
6
|
-
"depends": [],
|
|
7
|
-
"env_keys": [],
|
|
8
|
-
"size": "12KB",
|
|
9
|
-
"contains_binaries": false,
|
|
10
|
-
"tags": ["whatsapp", "channel", "messaging"]
|
|
11
|
-
}
|