Skip to content

Marketing Planning Requirements

Short description

This is a module that the team uses to plan the social marketing activities. It works in the following fashion: - The activities are divided in campaigns or projects. - Each project has a description with the goal of the project and the targeted approach. - Each project contains a set of activities with deadlines. The activities can be a Google ad, an Instagram reel or story / carrousel, a Facebook reel / story, a TikTok story, a Twitter (X) post, or a blog post. - Each activity can be assigned to one or more team members (the team members are managed in a separate table by the admin). - Each activity has a set of attributes - like a start and end date, type of activity, description, list of targeted audience segments, accompanying text (which is a rich text field), and a set of media items (video, graphics, images) with a link - these images can be stored locally or in a network location accessible via URL. - Media items can be uploaded directly to cloud storage (S3) or added via external URL. Uploaded media is stored with public read access and the URL is saved in the database. - Media items can be reused across multiple activities to avoid duplicate uploads. When adding media to an activity, users can select from existing media uploaded to other activities. - Activities also have a status - whether they are started, in progress, or done.

Workflow

  1. The team member creates the campaign as a project
  2. The team member can add the activities and assign them to other team members
  3. The team member can work with the activity - add media artefacts (by uploading files or providing URLs), descriptions, set due date, add story text (as rich or HTML formatted), add list of targeted audience segments
  4. Activity status can move from "Created" to "Assigned" (where it has to be assigned to a team member), "Work in progress", "Sent for review", "Approved", "Cancelled".
  5. Campaign status can move from "Created", over "Work in progress", "Completed and scheduled", "Started", "Ongoing", "Paused", "Ended".
  6. The team member can send any activity for approval. Once the activity is approved, it cannot be changed anymore, except if the admin changes the status back to "work in progress".
  7. The campaign can only be moved to "Completed and scheduled" if all the activities are approved.
  8. An activity can be revoked (its status changed back to "Work in progress") after which the campaign status automatically changes to "Work in progress"
  9. Each change to the campaign or the activity should be logged. Changes in status should send a whatsapp message to the user who created the campaign and user who created the activity.
  10. If an activity is sent for review, the user who is assigned to a review should get a whatsapp message. When the activity is approved or returned,the user who sent it for approval receives a whatsapp message.

Interface

The web page for marketing planning is a part of the tqweb-adm module and can be invoked from the left-hand menu. On the page, the campaigns (projects) are shown in a left-hand column, with a tree based sctructure. When expanding the project node, the activities are listed as items to the campaign. Clicking on a campaign opens its activities as tree items. Clicking on the activity opens an activity workplace where the team member can work with the campaign and the activity. The top of the workplace (about 20% of the page height) is dedicated to the campaign (name, short description, status) while the bottom 80% is dedicated to working with the selected activity. When a campaign is selected in the left-hand side tree, the campaign info is populated in the top area and the first activity (if any exists) is populated in the bottom area. If an activity is clicked / selected in the left-hand side tree, the activity info is populated in the bottom area. If an activity has been edited before, the system should ask if the changes should be saved or discarded. The workplace needs to have a description editor where the goals for the activity are described, a list of media artifacts, a list of audience segments, a rich text (or html) editor where the story text can be edited. The media artifacts section should support three modes: uploading files directly, entering external URLs, or selecting from existing media used in other activities.
The workplace will have a top menu with actions for activities (setting status, sending for review, sending a question to another team member, adding a new activity, setting a due date) and for campaigns (creating a campaign, changing status, scheduling). If the activity is sent for approval, there should be "approve" and "return" action. If the activity has been approved, there should be a clear indication that it is approved (returned activities do not need to be indicated - only the status will be changed to Work in Progress.) The page should be a part of the complete tqweb-adm setup (including the headers and footers).

Implementation

The module should be backed by corresponding database objects. Database implementation should follow the TQPro standard (field naming, sequences for IDs). The backend should be part of the tqapp module with the standard 2-tier entity management (database ORM entities doubling as native module-specific entities, and canonical entities returned by APIs). Entities should be configured and mapped in an appropriate XML file and this file should be included in tourlinq-config.xml The entities should be managed by services implemented through a facade and service factory (same as other functionalities). These services should be exposed as APIs in the tqapi module.

The web implementation should follow the same pattern as other tqweb-adm pages, using the same CSS scheme and same page configuration.

Media Upload Requirements

File Upload

  • Support direct file upload for images (JPG, PNG, GIF, WebP) and videos (MP4, WebM, MOV)
  • Maximum file size: 250MB
  • Files are uploaded to S3 cloud storage with public read access
  • Small files (<20MB) are uploaded through the API server for full validation
  • Large files (>=20MB) use pre-signed URLs for direct browser-to-S3 upload to avoid server resource issues
  • Upload progress is displayed to the user
  • Files are validated for type, size, and content before storage

Media Reuse

  • Media artifacts can be shared across multiple activities without re-uploading
  • When adding media, users can browse existing media from other activities
  • Filtering options: same campaign only or all campaigns, by media type
  • Media is linked to activities via a separate link table (many-to-many relationship)
  • Removing media from an activity only unlinks it; the file is preserved if used elsewhere
  • Media is only deleted from storage when no activities reference it

Storage

  • Media files are stored in an S3 bucket with public read access via bucket policy
  • Files are organized by date prefix and UUID to prevent naming conflicts
  • Public URLs are stored in the database for direct access
  • Configuration supports IAM role authentication (production) or access keys (development)

Broadcast Capability (TQ-109)

Activity Types

  • Two new activity types: WHATSAPP_BROADCAST and EMAIL_BROADCAST
  • Creating a broadcast activity auto-creates a linked broadcast configuration record

Recipient Resolution

  • Recipients come from system-wide Recipient Lists (TQ-113). See recipient-lists.md.
  • Recipient lists are curated outside the broadcast (populated from CRM, Excel, or manual edits) and reused across campaigns.
  • At compose time, an activity selects one or more lists; members are copied into the broadcast's recipient table with append-plus-dedupe semantics.
  • WhatsApp list population filters customers with phone/mobile numbers matching configurable country prefixes.
  • Email list population filters customers with valid email addresses where doNotEmail is not true.
  • Deduplication: within a list by contact value; across lists at copy time into a broadcast.
  • Opt-out register: not applied at list-population time (lists are snapshots). Opt-outs are re-checked when members are copied into a broadcast and at send time — opted-out contacts are inserted with deliveryStatus = OPTED_OUT so staff can see them.
  • The legacy metadata-only audience segments have been removed; recipient lists replace them.

Broadcast Workflow

  • Broadcast starts in DRAFT status; configure template, message body, and media
  • Add recipients by selecting one or more Recipient Lists ("Add from List"); broadcast moves to READY once recipients exist
  • Recipients remain individually editable after copy (add, edit, remove, clear, Excel round-trip)
  • Activity must be APPROVED through the existing review workflow before sending
  • Send is restricted to admin role only
  • Async send with configurable rate limiting (default 75ms for WhatsApp, 50ms for email)

Delivery Tracking

  • WhatsApp: Twilio status callbacks update per-recipient delivery status (queued/sent/delivered/read/failed)
  • Email: SMTP send success sets status to SENT (no delivery confirmation without transactional email service)
  • Aggregate stats (sent/delivered/read/failed counts) maintained on broadcast record

Opt-Out Compliance

  • WhatsApp: custom STOP keyword handler via inbound webhook (STOP/UNSUBSCRIBE/OPTOUT)
  • Email: RFC 8058 List-Unsubscribe header with one-click unsubscribe endpoint
  • Admin can manually add/remove opt-outs via API