MetatroncubeSoftwareSolutions/dine360-social-commerce
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
dine360-social-commerce/SOCIAL_COMMERCE_SETUP.md

18 KiB
Raw Blame History

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.
  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.
  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: 
    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: 
    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: 
    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.