# Dine360 Social Commerce Integration Guide
### Meta Commerce Catalog, Instagram Shopping & WhatsApp Cloud API for Odoo 17

This guide outlines the production configuration for the `dine360_meta_social` module on Odoo 17.

---

## 1. Architecture Overview

* **Odoo as Single Source of Truth**: Products, variants, prices, inventory/stock, customers, and orders are managed strictly in Odoo.
* **Meta Commerce Catalog**: Synchronized via Meta Graph API v19.0 batch calls (`POST /{catalog_id}/items_batch`) and scheduled automated XML/JSON feeds (`/social/meta/catalog_feed.xml`).
* **Instagram Shopping**: Powered directly by the Meta Commerce Catalog. Discovery on Instagram directs users to canonical Odoo eCommerce product pages for checkout.
* **WhatsApp Business Platform (Cloud API)**:
  * Customer inquiries from the website with pre-filled product details.
  * Real-time automated order status notifications (Confirmed, Being Prepared, Shipped, Delivered) using approved Meta templates.
  * Bi-directional webhook (`/social/whatsapp/webhook`) for automated status inquiries and message history logging.
  * Idempotency and deduplication engine preventing duplicate customer messages.
  * Non-blocking error handling: External API downtime never interrupts Odoo checkout or order creation.

---

## 2. Meta Developer & Commerce Manager Setup

### Step 2.1: Create a Meta App
1. Go to [Meta for Developers](https://developers.facebook.com/).
2. Click **My Apps** > **Create App**.
3. Select **Business** as the app type.
4. Set App Name to `Dine360 Social Commerce` and associate with your verified Meta Business Account.

### Step 2.2: Add Products to the Meta App
In the App Dashboard, add:
1. **WhatsApp** (Set up Cloud API).
2. **Commerce** / **Marketing API** (for catalog management).

### Step 2.3: Generate System User & Permanent Access Token
1. Open **Meta Business Settings** (`business.facebook.com/settings`).
2. Navigate to **Users** > **System Users**.
3. Click **Add**, name the user (e.g. `odoo_sync_bot`), role: **Admin**.
4. Click **Generate New Token**, select the App, and grant:
   - `catalog_management`
   - `business_management`
   - `whatsapp_business_messaging`
   - `whatsapp_business_management`
5. Copy the generated token immediately and store it securely.

### Step 2.4: Obtain Catalog ID
1. Open [Meta Commerce Manager](https://business.facebook.com/commerce).
2. Create or select your Catalog (Type: **E-commerce / Products**).
3. Go to **Catalog** > **Settings** > copy the numeric **Catalog ID**.

---

## 3. Instagram Shopping Configuration

1. In **Meta Business Manager**, go to **Accounts** > **Instagram Accounts** and link your Instagram Business Account.
2. In **Commerce Manager**, go to **Settings** > **Business Assets** > **Instagram**.
3. Link your Instagram account to the Meta Catalog created in Step 2.4.
4. In Instagram App: Go to **Settings** > **Creator/Business** > **Set Up Instagram Shopping**.
5. Once Meta reviews and approves your account for Instagram Shopping, products synced from Odoo will automatically be available for product tagging and the Instagram Shop tab.
6. When customers tap a tagged product on Instagram, they are routed to Odoo's product URL for checkout.

> [!NOTE]
> **Facebook Marketplace vs. Meta Commerce Catalog**:
> Direct API product listing to personal Facebook Marketplace accounts requires specialized Marketplace Partner approval. This module integrates with the official **Meta Commerce Catalog** and **Facebook Shop**, which is the approved, scalable path for businesses.

---

## 4. WhatsApp Cloud API Setup

### Step 4.1: Retrieve Phone Number ID & WABA ID
1. In Meta App Dashboard, navigate to **WhatsApp** > **API Setup**.
2. Copy:
   - **Phone Number ID** (e.g. `10987654321`)
   - **WhatsApp Business Account ID** (WABA ID)
   - **From Number** (for the public contact button)

### Step 4.2: Configure Webhook
1. In Meta App Dashboard, go to **WhatsApp** > **Configuration**.
2. In the **Webhook** section, click **Edit**:
   - **Callback URL**: `https://yourdomain.com/social/whatsapp/webhook`
   - **Verify Token**: Enter your custom token (e.g. set in Odoo Settings: `dine360_wa_token_secret`).
3. Click **Verify and Save**.
4. In **Webhook fields**, click **Manage** and subscribe to:
   - `messages` (inbound customer messages)
   - `message_template_status_update` (template approvals)

---

## 5. WhatsApp Template Setup (Meta Business Manager)

Meta requires pre-approved templates for proactive business-initiated notifications:

### Template 1: Order Confirmed
* **Name**: `order_confirmation_v1`
* **Category**: `UTILITY`
* **Language**: `en_US`
* **Body**:
  ```
  Hi {{2}}, your order {{1}} totaling {{3}} has been confirmed! We are preparing your order. Track progress here: {{4}}
  ```
* **Variables**:
  - `{{1}}`: Order Reference (e.g. SO1001)
  - `{{2}}`: Customer Name
  - `{{3}}`: Total Amount
  - `{{4}}`: Tracking URL

### Template 2: Order Shipped / Out for Delivery
* **Name**: `order_shipped_v1`
* **Category**: `UTILITY`
* **Language**: `en_US`
* **Body**:
  ```
  Hi {{2}}, your order {{1}} has shipped! Delivery reference: {{3}}. View details: {{4}}
  ```

---

## 6. Odoo Backend Configuration

1. Log in to Odoo as Administrator.
2. Navigate to **Social Commerce** > **Configuration** > **Settings** (or **Settings** > **Social Commerce**).
3. **Meta / Facebook Commerce**:
   - Check **Enable Meta Catalog Sync**.
   - Enter **Meta Catalog ID**, **Meta App ID**, **Meta App Secret**, and **Meta Access Token**.
   - Click **Test Meta Connection**. Verify green status badge.
   - Click **Sync All Published Products Now** to initialize the catalog.
4. **WhatsApp Business Platform**:
   - Check **Enable WhatsApp Integration**.
   - Enter **Phone Number ID**, **WhatsApp Business Account ID**, and **WhatsApp Access Token**.
   - Set **Webhook Verify Token** (must match Step 4.2).
   - Enter **WhatsApp Contact Number** (e.g. `15551234567` without `+` or spaces).
   - Enable **Show WhatsApp Button on Product Page** and **Show Floating WhatsApp Button**.
   - Click **Test WhatsApp Connection**. Verify green status badge.

---

## 7. Product Sync Lifecycle

* **Automatic Sync**: Whenever a product's price, stock, image, name, or publishing status changes, Odoo automatically enqueues the item in `Social Commerce > Meta & Instagram > Sync Queue`.
* **Scheduled Batch Sync**: The cron job `Dine360: Meta Commerce Catalog Synchronizer` runs every 15 minutes to process queued updates.
* **Automated Pull (Feed)**: In Meta Commerce Manager > **Data Sources** > **Add Data Feed**, enter your feed URL:
  `https://yourdomain.com/social/meta/catalog_feed.xml`
  Schedule automatic daily/hourly ingestion.

---

## 8. Order Tracking & Lifecycle Notifications

1. **Customer Checkout**: Customer places order on eCommerce website.
2. **Order Confirmed**: Upon confirming the Sale Order (or automatic online payment confirmation), Odoo triggers the `order_confirmed` WhatsApp template.
3. **Delivery Validation**: When warehouse/delivery staff validate the outgoing stock picking, Odoo triggers the `order_shipped` WhatsApp notification.
4. **Deduplication Safeguard**: Odoo tracks every dispatch in `social.whatsapp.notification`. If an order is re-saved or re-confirmed, duplicate notifications are automatically suppressed.
5. **Customer Inquiries**: When a customer replies on WhatsApp asking *"Where is my order SO1234?"*, Odoo matches the sender phone and order reference, logs the conversation under **Customer Inquiries**, and can auto-reply with the latest status.

---

## 9. Security & Error Handling

* **Token Protection**: Access tokens and app secrets are restricted to `Social Commerce / Administrator` and masked in all logs.
* **Non-Blocking Execution**: External API timeouts or network errors are caught, logged in `meta_sync_error` or `social.whatsapp.notification`, and retried asynchronously. They **never** break checkout, product saves, POS, or inventory movements.
* **Webhook Signature Validation**: Inbound webhooks are validated using HMAC-SHA256 (`X-Hub-Signature-256`) with the configured `meta_app_secret`.

---

## 10. Production Launch Checklist

Before launching to live traffic, complete and check off each item in this comprehensive 6-phase checklist:

### 10.1 Phase 1: Hosting, Reverse Proxy & SSL Configuration
- [ ] **Valid SSL/TLS Certificate**: Meta requires HTTPS signed by a recognized Certificate Authority (Let's Encrypt, Cloudflare, DigiCert). Self-signed certificates are rejected by Meta Cloud API and Commerce Manager.
- [ ] **Reverse Proxy (Nginx/Caddy) Headers**: Configure proxy headers so Odoo detects HTTPS correctly:
  ```nginx
  proxy_set_header Host $http_host;
  proxy_set_header X-Forwarded-Host $http_host;
  proxy_set_header X-Forwarded-Proto https;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  ```
- [ ] **Odoo Proxy Mode Enabled**: Ensure `proxy_mode = True` in `/etc/odoo/odoo.conf` so canonical product links in feeds and WhatsApp notifications generate with `https://`.
- [ ] **Multi-Worker Configuration**: In `odoo.conf`, set `workers = 2` (or more) so cron tasks (e.g. batch catalog sync) execute on dedicated worker threads without starving HTTP requests.
- [ ] **Docker DBFILTER**: Ensure `docker-compose.yml` has `DBFILTER: "^<production_db_name>$"` so unauthenticated webhook and feed requests resolve directly to the production database without triggering the database selector.
- [ ] **Public Endpoint Reachability**:
  - Verify Webhook route: `curl -I https://<domain>/social/whatsapp/webhook` returns HTTP 403 (Method Not Allowed / Forbidden without challenge parameters).
  - Verify Catalog Feed route: `curl -I https://<domain>/social/meta/catalog_feed.xml` returns HTTP 200 with `Content-Type: text/xml`.

### 10.2 Phase 2: Codebase & Dependency Verification
- [ ] **Core Dependencies Installed**: Ensure `stock_delivery` is installed (`odoo -d <db> -i stock_delivery --stop-after-init`) or pulled in via `dine360_meta_social` manifest.
- [ ] **Python Libraries**: Ensure `requests`, `cryptography`, and `phonenumbers` are installed in the container environment:
  ```bash
  docker exec -it odoo_client50 python3 -c "import requests, cryptography, phonenumbers; print('Dependencies OK')"
  ```
- [ ] **Background Cron Services Active**:
  - `Dine360: Meta Commerce Catalog Synchronizer` (Model: `social.meta.sync.queue`, Interval: 15 minutes, Active: Yes).
  - `Dine360: WhatsApp Notification Retry Service` (Model: `social.whatsapp.notification`, Interval: 5 minutes, Active: Yes).

### 10.3 Phase 3: Meta Commerce & Instagram Shopping Launch
- [ ] **Meta Business Portfolio Active**: Verified business account on Meta Business Suite (`business.facebook.com`).
- [ ] **Permanent System User Created**: In **Business Settings > Users > System Users**, create a System User (Admin role) and generate a permanent token with:
  - `catalog_management`
  - `business_management`
- [ ] **Catalog Assigned to System User**: In Meta Commerce Manager > **Settings > Permissions**, assign the System User as Catalog Admin.
- [ ] **Catalog Credentials in Odoo**:
  - In Odoo at **Social Commerce > Configuration > Settings**, enter:
    - `Meta App ID`
    - `Meta App Secret`
    - `Meta System User Access Token`
    - `Meta Commerce Catalog ID`
- [ ] **Test Meta Connection**: Click **Test Meta Connection** on the **Social Commerce Dashboard** and verify the green status.
- [ ] **Scheduled Data Feed in Meta**:
  - In Meta Commerce Manager > **Catalog > Data Sources > Data Feeds**, add scheduled pull:
    - URL: `https://<domain>/social/meta/catalog_feed.xml`
    - Frequency: Hourly or Daily
    - Currency: Matches Odoo company currency (e.g. USD, EUR, TRY)
- [ ] **Initial Catalog Population**: Click **Sync All Published Products Now** in Odoo Settings, and monitor **Sync Queue & Retries** until all items are in `done` state.
- [ ] **Instagram Business Account Connected**: Link Instagram Business Account to the Facebook Page and Commerce Catalog.
- [ ] **Domain Verification**: Verify your eCommerce domain under **Meta Business Settings > Brand Safety > Domains**.
- [ ] **Instagram Shopping Review**: Submit catalog for Instagram Shopping approval in Commerce Manager.

### 10.4 Phase 4: WhatsApp Business Platform (Cloud API) Launch
- [ ] **WABA & Phone Number Active**: Official WhatsApp Business Account registered and phone number verified in Meta Developer Portal.
- [ ] **Permanent Token Permissions**: System User Token granted:
  - `whatsapp_business_messaging`
  - `whatsapp_business_management`
- [ ] **WhatsApp Credentials in Odoo**:
  - Enter `WhatsApp Business Account ID (WABA ID)`, `Phone Number ID`, and `Webhook Verify Token` in Odoo Settings.
- [ ] **Meta Webhook Setup**:
  - In Meta Developer Portal > WhatsApp > Configuration:
    - Callback URL: `https://<domain>/social/whatsapp/webhook`
    - Verify Token: Matches `whatsapp_verify_token` in Odoo
    - Subscribed Fields: `messages`, `message_template_status_update`
- [ ] **Meta Message Templates Approved**: Submit and verify approval for all 4 transactional templates under category `UTILITY`:
  - `order_confirmation_v1` (Variables: Customer Name, Order Ref, Total Amount, Details URL)
  - `order_preparation_v1` (Variables: Customer Name, Order Ref)
  - `order_shipped_v1` (Variables: Customer Name, Order Ref, Carrier, Tracking Reference)
  - `order_delivered_v1` (Variables: Customer Name, Order Ref)
- [ ] **Template Mappings Verified in Odoo**:
  - Under **Social Commerce > WhatsApp > Template Mappings**, ensure template names and language codes (`en_US`, `en`, etc.) match Meta approvals exactly.
- [ ] **Test WhatsApp API**: Click **Test WhatsApp API** on the **Social Commerce Dashboard** and confirm green status.
- [ ] **Live Notification Dispatch Test**:
  - Place a test eCommerce order, confirm the order, validate delivery, and verify automated WhatsApp message delivery on a real mobile device.
- [ ] **Inbound Chat & Auto-Matching Test**:
  - Reply to the WhatsApp message from the mobile device; verify message is logged under **Social Commerce > WhatsApp > Customer Inquiries** and linked to the partner.

### 10.5 Phase 5: Frontend Storefront & User Experience
- [ ] **WhatsApp Contact Number**: Enter public customer support number in international format without `+` (e.g. `15551234567`) in Odoo Settings.
- [ ] **Floating Widget Verification**: Check that floating WhatsApp pulse button appears on all storefront pages (`/shop`, `/`, etc.) with responsive hover tooltip.
- [ ] **Product Page Button Verification**: Check that "Chat on WhatsApp" button appears near *Add to Cart* on single product pages.
- [ ] **Dynamic Variant & Quantity Tracking**: Verify that selecting variant attributes (size, options) or changing quantity updates the pre-filled WhatsApp message URL in real time.
- [ ] **Mobile Responsiveness**: Verify on iOS Safari and Android Chrome that clicking the button launches the native WhatsApp app seamlessly.

### 10.6 Phase 6: Monitoring, Security & Maintenance
- [ ] **Security Group Audit**: Verify that only system administrators belong to `Social Commerce / Administrator` (`group_social_manager`). Store operators should only belong to `Social Commerce / User` (`group_social_user`).
- [ ] **Token Masking Verified**: Verify that tokens and secrets are masked with `password="True"` in settings and never printed in standard Odoo logs.
- [ ] **Dead-Letter Queue Process**: Train store operations staff to review:
  - **Social Commerce > WhatsApp > Order Notifications** (Filter: `Failed`)
  - **Social Commerce > Meta & Instagram > Sync Queue & Retries** (Filter: `Failed`)
- [ ] **Automated Database Backups**: Confirm that regular PostgreSQL database dumps (`pg_dump`) and Odoo filestore backups are scheduled.

---

## 11. Troubleshooting & Known Issue Fixes

### 11.1 Owl Error: `"product.product"."hs_code" field is undefined"`
* **Symptom**: Opening a product variant form view (`product.product`) throws a JavaScript Owl lifecycle error: `Error: "product.product"."hs_code" field is undefined`.
* **Root Cause**: The standard Odoo module `stock_delivery` (which defines `hs_code` and `country_of_origin` for shipping and customs) has its XML view loaded in `ir.ui.view`, but the Python model extension had not been initialized in the active database.
* **Direct Database Fix**:
  ```bash
  docker exec -i <container_name> odoo -d <database_name> --db_host db --db_user odoo --db_password odoo -i stock_delivery --stop-after-init
  docker restart <container_name>
  ```
* **Architectural Fix**: Added `'stock_delivery'` to the `'depends'` list in `dine360_meta_social/__manifest__.py` so fresh installations automatically initialize all required shipping and customs fields.

### 11.2 Multi-Database Routing & Docker DBFILTER
* **Symptom**: External webhooks (Meta Graph API) or catalog feed pulls are intercepted by Odoo's database selector or return 404.
* **Root Cause**: `DBFILTER` in `docker-compose.yml` does not match the active database name.
* **Fix**: Update `DBFILTER: ".*"` or `DBFILTER: "^<database_name>$"` in `docker-compose.yml` and restart the Odoo container.

### 11.3 WhatsApp Webhook Verification 403 Forbidden
* **Symptom**: Meta Developer Portal displays *"The URL couldn't be validated. Callback verification failed."*
* **Root Cause**: The `hub.verify_token` sent by Meta does not match `whatsapp_verify_token` configured in Odoo.
* **Fix**: Go to **Social Commerce > Settings > WhatsApp**, copy the exact `Webhook Verify Token` value, and paste it into Meta Developer Portal.

### 11.4 WhatsApp Messages Not Sending / Template Does Not Exist
* **Symptom**: Notification is logged with status `failed` and error *"Template does not exist"*.
* **Root Cause**: The template name configured in **Social Commerce > WhatsApp > Template Mappings** does not match an approved template in your Meta WhatsApp Business Manager, or language code differs (`en_US` vs `en`).
* **Fix**: Create and submit the template for approval in Meta WhatsApp Manager first, then update the mapping name in Odoo to match exactly.

### 11.5 Consumable / Food Menu Products Exported as Out of Stock
* **Symptom**: Restaurant dishes and food items marked as Consumables show as "Out of stock" in Meta Catalog.
* **Root Cause**: Consumables have no tracked stock (`qty_available == 0`).
* **Fix**: Handled in `product_product.py` and `meta_feed.py` by checking `detailed_type in ('consu', 'service')` and automatically setting availability to `in stock`.