Project Overview

The project is isolated from the CRM application. It reads CRM data through Supabase credentials, writes only to the campaign Postgres database, and never changes the existing CRM API or frontend.

Page-By-Page Guide

End-To-End Campaign Flow

1. Open Audience, select a brand such as vaseline, and load the live Supabase preview.
2. Review compare states: new, updated, synced, invalid, and suppressed.
3. Import selected users or import all matching users into campaign Postgres.
4. Open Contacts and confirm imported totals, valid numbers, registered brands, and suppression status.
5. Upload/select media in Media Gallery if the message needs image, audio, video, or file content.
6. Create a draft in Campaign Builder using Simple composer or Advanced JSON.
7. Send a One-Time Preview to one active test user to see the current editor content on a phone.
8. Create Test Users and a Test List, then start a worker-based Test Run from Campaign Testing.
9. Review test logs, failures, WAHA message ids, worker events, and CSV/JSON reports.
10. Approve the campaign only after the test looks correct.
11. Build the real queue from imported Contacts.
12. Start Sending and monitor Running Campaigns, Worker Logs, Notifications, and Reports.

Audience And Contacts Management

Audience reads Supabase live. Contacts reads campaign Postgres only. Previewing does not write anything; importing writes or updates local campaign contacts.

Campaign Builder Guide

Campaign Builder is the draft workspace. Saving a draft keeps the editor loaded so you can continue testing and editing instead of losing your place.

Editing rule: DRAFT campaigns remain fully editable after One-Time Previews and worker Test Runs. Message content locks only after approval, real queue build, or real sending. If content is locked, duplicate the campaign to create a new editable draft.

Message Types And Templates

Simple mode is best for daily operators. Advanced JSON is for exact WAHA Plus payload control. Both modes render variables before sending.

Missing values render blank. Unknown variables are not a feature; keep templates to the supported variables above.

Simple text:
{{first_name}}, edit this {{brand}} message for {{city}} before sending.

Image caption:
{{first_name}}, edit this {{brand}} image caption for {{city}}.

Image + Text + Buttons:
Header: {{brand}} header
Body: {{first_name}}, edit this {{brand}} button message for {{city}}.
Button 1: Option 1
Button 2: Option 2
Fallback: {{first_name}}, edit this {{brand}} fallback text before sending.

Button fallback: WAHA may return 501 for buttons because the feature is deprecated/fragile. For One-Time Preview, test runs, and real worker sends, the app will automatically send the saved fallback text or poll when that specific 501 happens. Other WAHA errors still follow normal retry/failure handling.

Advanced JSON Templates

Advanced JSON is for exact control over a supported WAHA Plus payload while staying inside safe allowlisted endpoints. It does not execute arbitrary WAHA paths.

Choose Advanced JSON, select a grouped sample, click Load Sample, edit type and payload, then use Preview JSON and One-Time Preview before approving the campaign.

{
  "type": "poll",
  "payload": {
    "poll": {
      "name": "Edit this {{brand}} poll question for {{city}}",
      "options": ["Option 1", "Option 2"],
      "multipleAnswers": false
    }
  }
}

{
  "type": "location",
  "payload": {
    "latitude": 0,
    "longitude": 0,
    "title": "{{brand}} location title",
    "address": "{{city}}"
  }
}

{
  "type": "file",
  "payload": {
    "filename": "brochure-{{brand}}.pdf",
    "caption": "{{first_name}}, edit this {{brand}} file caption for {{city}}."
  }
}

{
  "type": "buttons",
  "experimental": true,
  "fallback": {
    "type": "text",
    "payload": { "text": "{{first_name}}, edit this {{brand}} fallback text before sending." }
  },
  "payload": {
    "button_mode": "message_buttons",
    "header": "{{brand}} header",
    "body": "{{first_name}}, edit this {{brand}} button message for {{city}}.",
    "footer": "Edit this footer or remove it.",
    "buttons": [
      { "type": "reply", "text": "Option 1" },
      { "type": "reply", "text": "Option 2" }
    ]
  }
}

{
  "type": "buttons",
  "experimental": true,
  "fallback": {
    "type": "text",
    "payload": { "text": "{{first_name}}, edit this {{brand}} fallback text before sending." }
  },
  "payload": {
    "button_mode": "image_buttons",
    "header": "{{brand}} header",
    "headerImage": {
      "mimetype": "image/jpeg",
      "filename": "{{brand}}-header.jpg",
      "url": "https://example.com/{{brand}}.jpg"
    },
    "body": "{{first_name}}, edit this {{brand}} button message for {{city}}.",
    "footer": "Edit this footer or remove it.",
    "buttons": [
      { "type": "reply", "text": "Option 1" },
      { "type": "url", "text": "Open link", "url": "https://example.com/{{brand}}" }
    ]
  }
}

{
  "type": "list",
  "experimental": true,
  "fallback": {
    "type": "poll",
    "payload": {
      "poll": {
        "name": "Edit this {{brand}} fallback poll question",
        "options": ["Option 1", "Option 2"]
      }
    }
  },
  "payload": {
    "message": {
      "title": "{{brand}} list title",
      "description": "{{first_name}}, edit this {{brand}} list description.",
      "button": "Open list",
      "sections": [
        {
          "title": "Options",
          "rows": [
            { "title": "Option 1", "rowId": "option_1" }
          ]
        }
      ]
    }
  }
}

Bad examples:
- {"endpoint": "/api/deleteSession"} is blocked because endpoints are not arbitrary.
- {"type": "button"} is blocked; the allowlisted type is "buttons".
- {"type": "buttons", "payload": {"body": "Hi", "buttons": [{"type": "payment"}]}} is blocked.
- {"type": "image", "payload": {"url": "promo.png"}} should be tested carefully; JPEG/JPG is preferred.

Test-first rule: Load Sample -> edit JSON -> Preview JSON -> One-Time Preview -> worker Test Run -> approve only if stable. Buttons and list are experimental, so poll or text is the recommended fallback for production campaigns.

Blocked in v1: arbitrary endpoints, operational endpoints such as edit/delete/star/reaction/forward/status/channel sends, and event messages. Event messages are reserved for appointment-style RSVP flows.

Media Gallery

Use Media Gallery for reusable image, audio, video, and document files. Uploads store metadata in media_assets and files in the Docker media volume.

For local development with remote WAHA, the dashboard URL may not be reachable from WAHA. In that case the base64 fallback is important: the worker sends the uploaded file data directly instead of asking WAHA to download a local URL.

Test Users, Test Lists, And Campaign Testing

One-Time Preview sends the current Campaign Builder editor content immediately to one active Test User. It can save first or send unsaved editor content. It does not create a test run and does not create real queue rows.

Worker Test Run starts from Campaign Testing. It snapshots a Test List into campaign_test_run_recipients and uses the same WAHA session, sending window, daily/hourly limits, delay, pause, max-attempt rules, worker logs, and reports as real sending.

Snapshot rule: editing a DRAFT after a test run does not change old test-run logs. Old logs keep the rendered payload that was sent at that time.

Reports are downloadable as CSV and JSON from campaign test-run history. Logs include message type, endpoint, status, attempts, WAHA message id, errors, timestamps, and payload summary.

Queue rendering: real campaigns and test runs store the rendered endpoint and rendered_payload. The worker sends that generic payload instead of branching only on text/image.

Real Campaign Sending

1. Approve confirms the message is ready and locks message content.
2. Build Queue snapshots eligible Contacts into campaign recipients and send queue rows.
3. Start Sending changes campaign status to running. The dashboard does not blast messages directly.
4. Worker sends slowly by claiming rows with database locking, applying limits, rendering media fallback, calling WAHA, and updating status.
5. Pause/Cancel/Archive stop new claims. Already sent rows remain auditable.

Real queue building excludes invalid, suppressed, opted-out, or duplicate contacts. Each contact receives one outbound marketing message per campaign unless a future reply flow is added.

Settings And Sending Limiters

Settings guide new campaigns and the Docker worker. Keep limits conservative for new WhatsApp sessions. No setting can guarantee that WhatsApp will not ban or restrict a session.

Worker, Queue, And Status Lifecycle

The dashboard changes campaign state; the Python worker performs actual background sending. No host cron is needed because the Docker worker loop replaces cron for v1.

Recipient rows may be PENDING, PAUSED, SENDING, SENT_API_ACCEPTED, DELIVERED, READ, FAILED, or SKIPPED. WAHA webhook acknowledgements update delivered/read states when available.

Reports, Logs, Notifications, And Admin Activity

Production / Docker Deployment Notes

1. Run the dashboard, Postgres, and Python worker with Docker Compose.
2. Set DASHBOARD_API_TOKEN, DATABASE_URL, SUPABASE_URL, Supabase service/import key, WAHA_BASE_URL, and WAHA_API_KEY in the project environment.
3. Keep PUBLIC_MEDIA_BASE_URL empty for local/remote mismatch so base64 fallback is used, or set it to a public HTTPS URL that WAHA can fetch.
4. Open Settings and copy the detected WAHA webhook URL. Configure WAHA webhooks to call /api/webhooks/waha with events message, message.any, and message.ack.
5. If Settings shows a local URL like localhost, remote WAHA cannot call it. Set PUBLIC_DASHBOARD_BASE_URL to the public HTTPS dashboard URL or use a tunnel for development.
6. Confirm WAHA sessions show as WORKING before real sending.
7. Start with low limits, run internal test lists, then launch real campaigns gradually.

Redis is not required for v1. Postgres is enough for 10,000 queued users because sending is intentionally slow and queue claiming is database-backed. Consider Redis later only for multiple API replicas, high-volume realtime pub/sub, or cross-process coordination that Postgres cannot handle comfortably.

Developer Reference

Maintainer: Vivek M, India, +917972495890

Troubleshooting