14 KiB
14 KiB
phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, must_haves
| phase | plan | type | wave | depends_on | files_modified | autonomous | requirements | must_haves | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 02-agent-features | 03 | execute | 1 |
|
true |
|
|
Purpose: Adds the second messaging channel, enabling SMBs to deploy their AI employee on WhatsApp -- the most common business communication channel globally. Output: WhatsApp adapter, media model extension, business-function scoping, passing tests.
Note: Outbound wiring in orchestrator tasks.py (channel-aware response routing) and multimodal LLM interpretation of media are handled in Plan 02-05 to avoid file conflicts with Plans 02-01 and 02-02 which also modify tasks.py.
<execution_context> @/home/adelorenzo/.claude/get-shit-done/workflows/execute-plan.md @/home/adelorenzo/.claude/get-shit-done/templates/summary.md </execution_context>
@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md @.planning/phases/02-agent-features/02-CONTEXT.md @.planning/phases/02-agent-features/02-RESEARCH.md@packages/gateway/gateway/channels/slack.py @packages/gateway/gateway/normalize.py @packages/gateway/gateway/main.py @packages/shared/shared/models/message.py @packages/shared/shared/config.py @packages/router/router/tenant.py @packages/router/router/ratelimit.py @packages/router/router/idempotency.py
Channel adapter sequence (from Phase 1):
- Receive webhook -> verify signature
- Normalize to KonstructMessage
- resolve_tenant(workspace_id) -> tenant_id
- check_rate_limit(tenant_id, channel)
- is_duplicate(message_id) -> skip if True
- Post placeholder / typing indicator
- handle_message.delay(msg_payload)
From packages/shared/shared/models/message.py:
- KonstructMessage: id, tenant_id, channel, channel_metadata, sender, content, timestamp, thread_id, reply_to, context
- MessageContent: text, html, attachments (list[dict]), mentions (list[str])
- SenderInfo: user_id, display_name, role
- ChannelType: slack (needs 'whatsapp' added)
From packages/router/router/tenant.py:
- resolve_tenant(workspace_id: str, session) -> str (tenant_id)
- workspace_id for WhatsApp = phone_number_id from channel_connections
From packages/shared/shared/config.py:
- Settings class with pydantic-settings
- Need to add: whatsapp_app_secret, whatsapp_verify_token
2. Extend `packages/shared/shared/config.py`:
- Add whatsapp_app_secret: str = "" and whatsapp_verify_token: str = "" to Settings
3. Create `normalize_whatsapp_event()` in normalize.py:
- Takes: parsed webhook JSON body (dict)
- Extracts: entry[0].changes[0].value -- this is the Meta Cloud API v20.0 structure
- Maps: messages[0].from -> sender.user_id, messages[0].text.body -> content.text
- For media messages (type=image/document): extract media_id, set MediaAttachment with media_type and a placeholder URL (actual download happens in the adapter)
- Sets channel='whatsapp', thread_id=sender_wa_id (WhatsApp conversations are per-phone-number, not threaded)
- Sets channel_metadata with phone_number_id, message_id from webhook
4. Write tests:
- test_whatsapp_verify.py: Valid signature passes, invalid signature raises 403, timing-safe comparison used
- test_whatsapp_normalize.py: Text message normalizes correctly, image message normalizes with MediaAttachment, correct field mapping for sender/channel/metadata
Note: Use `hmac.new()` not `hmac.HMAC()` for signature verification. Read raw body via `await request.body()` BEFORE any JSON parsing (Pitfall 5 from research).
2. Business-function scoping (two-tier gate per user decision):
- Tier 1: is_clearly_off_topic(text, allowed_functions) -- simple keyword overlap check. If zero overlap with any allowed function keywords, return True. Agent's allowed_functions come from Agent model (add `allowed_functions: list[str] = []` field if not present, or use agent.tools as proxy).
- If clearly off-topic: send canned redirect via send_whatsapp_message: "{agent.name} is here to help with {', '.join(allowed_functions)}. How can I assist you with one of those?"
- Tier 2: Borderline messages pass to the LLM. The scoping is enforced via the system prompt (which already contains the agent's role and persona). Add to system prompt builder: if channel == 'whatsapp', append "You only handle: {allowed_functions}. If a request is outside these areas, politely redirect the user."
3. Outbound message delivery (used by the adapter for direct responses like off-topic canned replies):
- async send_whatsapp_message(phone_number_id, access_token, recipient_wa_id, text) -> None
- POST to https://graph.facebook.com/v20.0/{phone_number_id}/messages with messaging_product="whatsapp", to=recipient_wa_id, type="text", text={"body": text}
- async send_whatsapp_media(phone_number_id, access_token, recipient_wa_id, media_url, media_type) for outbound media
4. Install boto3 for MinIO: `uv add boto3` in gateway package. Use endpoint_url=settings.minio_endpoint for S3-compatible MinIO access.
5. Register whatsapp_router in gateway main.py: `app.include_router(whatsapp_router)`
6. Write test_whatsapp_scoping.py:
- Test is_clearly_off_topic with matching keywords -> False
- Test is_clearly_off_topic with zero overlap -> True
- Test canned redirect message format includes agent name and allowed functions
- Test borderline message passes through (not rejected by tier 1)
Note: The orchestrator-side wiring (channel-aware outbound routing in tasks.py) is deferred to Plan 02-05 to avoid file conflicts with Plans 02-01 and 02-02. The WhatsApp adapter can handle direct responses (off-topic canned replies, webhook verification) independently. LLM-generated responses routed back through WhatsApp will be wired in Plan 02-05.
<success_criteria>
- WhatsApp messages are normalized to KonstructMessage and dispatched through the existing pipeline
- Webhook signature verification prevents unauthorized requests
- Business-function scoping enforces Meta 2026 policy (tier 1 keyword gate + tier 2 LLM scoping)
- Media attachments are downloaded, stored in MinIO, and available for downstream processing
- Per-tenant phone number isolation via phone_number_id in channel_connections </success_criteria>