(CODUX-225) Complete the WhatsApp connector

[numnx]

🧩 Task: Complete the WhatsApp connector

Automated task PR opened by Code UX for T03.

📋 Summary

Sprint: Sprint 225 · Chat connector completeness and verification · Task: T03

Complete and verify all six chat connectors through provider-specific profiles, correct authentication and session behavior, encrypted durable state, atomic routing and retries, REST/MCP/dashboard management, official-documentation evidence, deterministic contract coverage, and credential-gated checks limited to provider-controlled endpoints, with Discord prioritized.

🤖 Model & Provider

Provider	Codex CLI
Model	gpt-5.6-sol

⏱️ Timing

Started	2026-07-13 22:51:02 UTC
Finished	2026-07-13 23:03:55 UTC
Duration	12m 53s

📊 Token Usage

Metric	Value
Input tokens	150,794
Cached input tokens	3,718,400
Output tokens	27,597
Total tokens	3,896,791
Invocations	1
Tool calls	32
Active time	12m 4s

Included usage estimate (subscription/local login): $3.44

✅ QA Review

⏳ QA review runs after this PR is opened. Check the task card in the dashboard for the outcome once it lands.

📝 Full Task Prompt

## Objective
Complete the WhatsApp profile against Meta's Cloud API contract while retaining existing managed and generic webhook bridges for backward compatibility.

## Scope
- `src/domain/chat-connectors/providers/whatsapp.ts`
- Create `tests/backend/domain/chat-connectors/whatsapp.test.ts`
- `docs/settings/chat-connectors/whatsapp.md`
- `docs-web/architecture/chat-connectors/whatsapp.md`
- Official references: [WhatsApp Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api), [webhooks](https://developers.facebook.com/docs/graph-api/webhooks/getting-started), and [Meta's official Postman collection](https://www.postman.com/meta/whatsapp-business-platform/overview)

## Implementation Requirements
1. Add an `official_api` schema for Graph API version, phone-number ID, optional app metadata, and write-only access token, app secret, and webhook verify token; keep legacy bridge schemas readable without reinterpretation.
2. Implement the GET webhook subscription challenge using `hub.mode`, `hub.verify_token`, and `hub.challenge`, and verify POST `X-Hub-Signature-256` against the exact raw request body with the Meta app secret.
3. Normalize message webhooks separately from delivery/status webhooks, retain `wamid` as the idempotency key, bind the business phone-number ID as the external channel, and retain the sender WhatsApp ID as the outbound recipient identity.
4. Build outbound text and reply requests only for `https://graph.facebook.com/{version}/{phoneNumberId}/messages`, include `messaging_product: whatsapp`, parse returned message IDs, and classify Meta error payloads and retryable HTTP responses without leaking access tokens or recipient data.
5. Implement read-only connection verification against the configured test or registered phone-number resource; reserve actual sends for T13's separately opted-in Meta test-number path.
6. Cover challenge success/failure, raw-body signatures, text and caption payloads, status-event filtering, recipient selection, replies, Graph errors, timeouts, legacy bridge behavior, and redaction with deterministic fixtures and mocked fetch.

## Constraints
- Official mode must not accept arbitrary Graph API hosts or silently fall back to a custom webhook URL.
- Do not send a live WhatsApp message in normal tests or verification actions.
- Preserve existing managed and webhook connection records and never expose verify tokens, app secrets, or access tokens.
- Do not modify other provider modules or shared generated docs-web artifacts.

## Verification
- Run `pnpm run test:backend -- tests/backend/domain/chat-connectors/whatsapp.test.ts`.
- Run `pnpm run lint`.
- Confirm the tests prove signature validation uses raw bytes and outbound delivery targets the sender identity rather than the business phone-number channel ID.

🌿 Branch Info

Base: feature/CODUX-225-chat-connector-completeness-and-verification
Head: task/feature-codux-22-t03-codex-51b87a23-mrjtgem0

---

🤖 Generated by Code UX