# WhatsApp Direct Integration

## Purpose

The platform can now receive WhatsApp Cloud API webhooks directly, persist conversations, link them to operational records, and send replies from the admin panel while keeping the existing Outbox/wa.me workflow as a fallback.

## Meta Configuration

- Webhook URL: `/webhooks/whatsapp`
- Verify method: `GET /webhooks/whatsapp`
- Events receiver: `POST /webhooks/whatsapp`
- Configure these values in Admin WhatsApp Settings:
  - Phone Number ID
  - WhatsApp Business Account ID
  - Access Token
  - Webhook Verify Token
  - App Secret
  - Mode: `outbox`, `cloud_api`, or `hybrid`

Sensitive settings are stored in `site_settings` using Laravel encryption and are not re-displayed after saving.

## Data Flow

1. Meta calls `GET /webhooks/whatsapp` with `hub.challenge`.
2. Meta sends incoming messages/statuses to `POST /webhooks/whatsapp`.
3. The controller validates the signature when an App Secret is configured.
4. The raw payload is saved in `whatsapp_webhook_events`.
5. `ProcessWhatsAppWebhookEventJob` processes the payload asynchronously.
6. The inbound service creates or updates:
   - `whatsapp_contacts`
   - `whatsapp_conversations`
   - `whatsapp_messages`
7. Known phone numbers are linked to registrations/enrollments, B2B leads, or organizations.

## Keyword Routing

The MVP uses deterministic keywords, not AI:

- Registration/course intent: `دورة`, `تسجيل`, `formation`, `inscription`
- B2B intent: `مؤسسة`, `شركة`, `عرض`, `devis`, `entreprise`
- Event intent: `فعالية`, `ويبينار`, `webinar`, `event`

B2B keywords can create a `B2bLead` automatically with source metadata `whatsapp_inbound`.

## Admin UI

- Inbox: `/admin/messaging/whatsapp/inbox`
- Conversation: `/admin/messaging/whatsapp/conversations/{conversation}`
- Settings: `/admin/messaging/whatsapp/settings`
- Templates: `/admin/messaging/whatsapp/templates`

Legacy short aliases under `/admin/whatsapp/*` still redirect to the canonical routes.

## Sending Modes

- `outbox`: creates a wa.me Outbox message.
- `cloud_api`: sends via Meta Cloud API directly.
- `hybrid`: tries Meta Cloud API first, then falls back to Outbox when sending fails.

Every admin reply is saved in `whatsapp_messages`; existing automation still uses `whatsapp_message_logs` and Outbox records.

## Permissions

- `whatsapp.inbox.view`
- `whatsapp.conversations.view`
- `whatsapp.conversations.reply`
- `whatsapp.conversations.assign`
- `whatsapp.settings.manage`
- `whatsapp.templates.manage`
- `whatsapp.link_entities`

Admin receives all permissions through the RBAC catalog. Support can view, reply, assign, and link entities when granted by role defaults.

## Security Notes

- Webhook POST is rate-limited with `whatsapp-webhook`.
- POST signature validation is enforced when `app_secret` is configured.
- Provider tokens are never logged.
- `provider_message_id` is unique in `whatsapp_messages` to prevent duplicate processing.
- Conversations are protected by policy; UI visibility is not the only guard.

## Limitations

- Media upload/download is not implemented in this phase.
- Message templates must still be approved in Meta before Cloud API template sending.
- WhatsApp Cloud API pricing and 24-hour messaging-window rules apply.
- No unofficial WhatsApp libraries are used.