Builder Pattern: WhatsApp Group → OpenCode Session
Date: 2026-02-12
Context: OpenClaw-OpenCode integration using sibling worktree pattern
⚠️ NOTE: This document covers WhatsApp-specific implementation details. For the core session pattern (builder workspaces, lifecycle, message routing), see:
<<<<<<< HEAD 📄 opencode-session-pattern.md
f146a548fbab991798ce91719b88cbf1f064588a
Overview
This document covers WhatsApp-specific aspects of OpenCode integration:
- Group setup UX
- WhatsApp message routing
- Group management features
- WhatsApp-specific configuration
For builder workspace creation, OpenCode session lifecycle, and message routing strategies, see the shared pattern document above.
WhatsApp-Specific Features
1. Group Creation UX
Step 1: User creates WhatsApp group
- Group name: “API Team”
- Adds team members
- Adds OpenClaw bot number
Step 2: Initialize session (in group) <<<<<<< HEAD
@OpenClaw start OpenCode session for /workspace/repos/ai-dev
=======
<!-- The repos are in the 'use repos' part, wouldn't need to be repeated? -->
<!-- I think the session should also relate to a project from .ai/projects; either a category like 'ai-dev (.ai/projects/ai-dev) or a project (openclaw-opencode-bridge)-->
@OpenClaw start OpenCode session for repos/ai-dev
f146a548fbab991798ce91719b88cbf1f064588a
Use repos: ai-dev, domain-apis
**Step 3: OpenClaw responds**
✅ Creating builder workspace…
Builder: api-team-abc123 <<<<<<< HEAD Project: /workspace/repos/ai-dev
Project: repos/ai-dev
f146a548fbab991798ce91719b88cbf1f064588a Repos: ai-dev, domain-apis OpenCode URL: http://opencode.internal:8080/session/abc123
Everyone in this group can now chat with OpenCode. Just send messages — no @mention needed. 🚀
---
### 2. Natural Conversation Flow
**WhatsApp-specific UX choice: All messages → agent**
<<<<<<< HEAD
=======
<!-- I don't think this is the case - i think a slack channel and whatsapp group are analogous... -->
>>>>>>> f146a548fbab991798ce91719b88cbf1f064588a
Unlike shared channels (Slack, Discord), dedicated WhatsApp groups are typically:
- Small (2-10 people)
- Project-focused
- Created specifically for one task
**Result:** Every message goes to OpenCode for natural collaboration:
Alice: We need rate limiting Bob: 5 requests per minute? Alice: Yes
OpenCode: Got it, adding 5 req/min rate limit to /login…
**Agent has full context**, no need to @mention or repeat yourself.
---
### 3. WhatsApp Message Format
**Inbound (WhatsApp → OpenClaw):**
```json
{
"from": "+447466109114",
"group": "120363xxx@g.us",
"text": "Add rate limiting to /login",
"timestamp": 1644678400,
"message_id": "3A..."
}
Outbound (OpenClaw → WhatsApp):
{
"to": "120363xxx@g.us",
"text": "📂 Opened ai-dev/services/gateway/src/auth.ts\n✏️ Added express-rate-limit middleware",
"reply_to": "3A..." // Optional: thread replies
}4. WhatsApp-Specific Config
{
"session_id": "abc123",
<<<<<<< HEAD
"builder_path": "/workspace/.builders/api-team-abc123",
=======
"builder_path": ".builders/api-team-abc123",
>>>>>>> f146a548fbab991798ce91719b88cbf1f064588a
"opencode_url": "http://localhost:8080",
"platform": "whatsapp",
"channel_id": "120363xxx@g.us",
"channel_name": "API Team",
"trigger": "all_messages",
"repos": ["ai-dev", "domain-apis"],
"created_by": "+447403331966",
"created_at": "2026-02-12T08:00:00Z",
"whatsapp": {
"formatting": "plain", // WhatsApp doesn't support markdown well
"max_length": 4096, // WhatsApp message limit
"use_emojis": true, // Visual progress indicators
"batch_updates": true // Combine rapid events into one message
}
}WhatsApp Group Management
Admin Commands (via DM)
List All Sessions (DM with OpenClaw)
You (DM):
Show me all OpenCode sessions
<<<<<<< HEAD
f146a548fbab991798ce91719b88cbf1f064588a
OpenClaw:
📊 Active OpenCode Sessions:
1. api-team-abc123
Group: API Team (WhatsApp)
<<<<<<< HEAD
Repos: ai-dev, domain-apis
Status: Active (working on rate limiting)
Last activity: 2 min ago
Builder: /workspace/.builders/api-team-abc123
=======
<!-- Example: -->
Repos: ai-dev (feature/api-team-abc123, uncommitted changes), domain-apis (feature/api-team-abc123, PR awaiting https://github.com.../prs/7)
Status: Active (working on rate limiting)
Last activity: 2 min ago
Builder: .builders/api-team-abc123
>>>>>>> f146a548fbab991798ce91719b88cbf1f064588a
2. frontend-team-def456
Group: Frontend Team (WhatsApp)
Repos: dashboard
Status: Idle
Last activity: 15 min ago
<<<<<<< HEAD
Builder: /workspace/.builders/frontend-team-def456
=======
Builder: .builders/frontend-team-def456
>>>>>>> f146a548fbab991798ce91719b88cbf1f064588a
<<<<<<< HEAD
f146a548fbab991798ce91719b88cbf1f064588a
Pause/Resume Session
You (DM):
Pause frontend-team session
OpenClaw:
⏸️ Paused frontend-team-def456
Session will ignore new messages until resumed.
(Auto-message to Frontend Team group):
⏸️ OpenCode session paused by admin
Resume with: @OpenClaw resume
Terminate Session
You (DM):
Terminate api-team session
OpenClaw:
⚠️ This will:
- Stop OpenCode process
- Remove builder workspace
- Unbind from API Team group
Continue? [Yes] [No]
You: Yes
OpenClaw:
✅ Session terminated
Builder workspace cleaned up.
API Team group notified.
(Auto-message to API Team group):
🛑 OpenCode session terminated by admin
To start a new session: @OpenClaw start session for <project>
Implementation Notes
WhatsApp Adapter Layer:
- Receives messages via WhatsApp Business API webhooks
- Binding key: WhatsApp group JID (
120363xxx@g.us) - Sends via WhatsApp Business API
- No markdown support (use plain text + emojis)
- Batch rapid updates into single messages (WhatsApp rate limits)
For core implementation details (builder creation, message routing, session lifecycle), see:
<<<<<<< HEAD
📄 opencode-session-pattern.md
f146a548fbab991798ce91719b88cbf1f064588a
References
<<<<<<< HEAD
- Core Session Pattern:
/workspace/.ai/shared/opencode-session-pattern.md - Workspace Pattern V2:
/workspace/.ai/projects/ai-dev/opencode-slack-integration/workspace-pattern-v2.md======= - Core Session Pattern: opencode-session-pattern.md
- Workspace Pattern V2: workspace-pattern-v2.md
f146a548fbab991798ce91719b88cbf1f064588a
- OpenCode Slack Integration: Related implementation for Slack platform