# WhatsApp Direct Integration Audit

## Current State

- The platform already has an outbound WhatsApp module based on templates, flows, outbox messages, logs, and optional Meta Cloud sending.
- Existing admin routes live under `/admin/messaging/whatsapp/*`, with legacy redirects under `/admin/whatsapp/*`.
- Existing provider support is outbound-only through `MetaCloudClient` and `WhatsAppDispatchService`.
- Existing settings are stored in `site_settings`; sensitive values can be encrypted by the messaging settings layer, but the WhatsApp-specific settings class did not yet expose Cloud API credentials or webhook secrets.
- There is no direct inbound webhook endpoint, no conversation inbox, and no canonical contact/conversation/message timeline tables.

## Gaps Found

- Missing `/webhooks/whatsapp` GET verification and POST receiver.
- Missing raw webhook event persistence and async processing.
- Missing idempotency protection for inbound Meta message IDs.
- Missing inbound contact matching against registrations/enrollments, B2B leads, and organizations.
- Missing admin inbox and conversation timeline.
- Missing direct Cloud API provider methods for templates and timeline logging.
- Missing direct WhatsApp permissions requested by the integration scope.

## Reuse Decisions

- Keep the current Outbox module intact for low-cost/manual sending and as the fallback path.
- Keep `/admin/messaging/whatsapp/*` as canonical WhatsApp operations routes and add direct inbox routes under both canonical and short aliases where needed.
- Use `site_settings` for WhatsApp settings with encrypted storage for access token, webhook verify token, and app secret.
- Reuse `PhoneNormalizer` for Algerian phone normalization.
- Reuse B2B lead records for institution-intent conversations.

## Implementation Plan

1. Add direct WhatsApp tables: contacts, conversations, messages, and webhook events.
2. Extend WhatsApp settings for Cloud API and webhook secrets.
3. Add webhook controller with GET verification, POST signature validation, raw event storage, and queued processing.
4. Add inbound processing service with phone matching, keyword routing, B2B lead creation, message idempotency, and status updates.
5. Add Cloud API provider for text/template sending with timeline logging support.
6. Add admin inbox/conversation pages with reply, assign, resolve, and create/link B2B lead actions.
7. Add permissions, translations, tests, and operational documentation.

## Non-Goals

- No unofficial WhatsApp Web automation.
- No AI-based intent detection in this phase.
- No media upload workflow beyond schema readiness and provider extension points.