[PRD] CEBE | Marketing Event Source: Broadcast & Ads — Phase 1 (SUPPORT: Broadcast Squad)
HEADER BLOCK
| Field | Value |
|---|---|
| PM | Zhelia Alifa |
| PRD Version | 1.4 |
| Status | READY |
| PRD Type | SUPPORT |
| Epic | TF-3302 — shared Phase-1 Epic (Owning Squad: Broadcast) |
| Squad | Broadcast Squad |
| Owning Squad | Broadcast |
| RFC Link | N/A — follows the core RFC; no separate RFC unless ads-platform sync warrants |
| Figma Master | N/A — no UI changes |
| Anchor | No — contributing squad. ANCHOR: Customer Event-Based Engine (CEBE) — ANCHOR |
| Parent Phase | Core Infrastructure & CDP Customer Event — Phase 1 (TECH) |
| Labels | epic:cdp | module:broadcast | feature:cebe-marketing-events |
| Last Updated | 2026-06-26 |
SUPPORT PRDs never carry the Anchor flag. Graceful degradation is mandatory — this squad's emission must never block the core ingestion or any Broadcast/Ads user flow.
CONDITIONAL BLOCK: SUPPORT CONTEXT
| Field | Detail |
|---|---|
| Anchor PRD | Customer Event-Based Engine (CEBE) — ANCHOR |
| Lead Squad Phase PRD | Core Infrastructure & CDP Customer Event — Phase 1 (TECH) |
| Phase | Phase 1 of 3 (Q3 2026) |
| Lead Squad | CDP Squad (+ BI/Data) |
| Contributing Squad | Broadcast Squad |
| This squad contributes | Emit standardized Marketing events into CEBE for BOTH outbound Broadcast and paid Ads (event list: anchor → 4. Campaign Module). Keyed on qontak_customer_id, so CEBE can derive marketing metrics (reply rate, ads conversion, CPL/CPA/ROAS) and attribution. |
| Lead squad owns | The event schema, ContactResolver/identity resolution, Event Adapter, Central DB, retriever/metrics layer, and query approach. Broadcast squad does NOT build any of these — it publishes to them. |
| Integration point | Broadcast publishes to the standardized ingestion contract defined in the lead Phase PRD §14 Behavior 1 using the standard event envelope. |
| Handoff contract | Lead squad delivers the event schema + adapter in staging by [date in RFC]. Broadcast cannot finalize emission until available. Broadcast delivers Broadcast + Ads emission (incl. 12-month backfill) by end of Q3 2026. |
| Coordination | Weekly CDP + Broadcast sync. Schema changes via the Epic comment thread (TF-3302). Ads-platform sync details (Meta/Google/TikTok) aligned with BI/Data. |
1. One-liner + Problem
One-liner: Broadcast Squad emits standardized Broadcast and Ads events into CEBE so marketing engagement, conversion, and attribution become reusable across Qontak.
Problem: Marketing engagement lives only inside the Broadcast/Ads tooling, so CEBE cannot compute reply rate, ads conversion, or attribution centrally. For full problem context, see the Anchor PRD.
2. Target Users + Persona Context
Personas inherited from the lead Phase PRD: Core Infrastructure & CDP Customer Event — Phase 1 (TECH).
Nuance: the direct beneficiary is the Marketing Owner who needs unified Broadcast + Ads metrics and attribution for segmentation and marketing automation.
3. Non-Goals
- Does not build the event schema, adapter, Central DB, retriever, or query layer — all owned by the lead CDP/BI-Data PRD.
- Does not build segmentation or marketing-automation features — those consume CEBE downstream.
- Does not change existing Broadcast/Ads user-facing behavior — emission is additive and background.
- Does not own identity resolution — uses the lead squad's
qontak_customer_id/ ContactResolver. - Does not connect non-marketing modules (Chat, Ticket, etc.) — out of scope for this squad.
4. Scope Changes
Engineering surfaces this PRD touches (controlled vocab). Kept in sync with the scope_changes frontmatter above.
- Backend — Broadcast/Ads service (
repo TBD — Broadcast squad): emit the standardizedcampaign.*(Broadcast) andad.*(Ads) events to the lead adapter contract keyed onqontak_customer_id; ad-platform sync (Meta/Google/TikTok) forad.impression/ad.clicked/ad.spend_recorded; buffer + retry for graceful degradation; 12-month backfill of marketing events on first connect. Event list: anchor → 4. Campaign Module. - Data — marketing metric semantics aligned with the retriever (owned by lead): reply rate,
% ads conversion, CPL/CPA, ROAS — this squad supplies source events + definitions; the lead materializes them. - Frontend / Mobile / Design — None (background emission only; no UI surface).
5. Constraints
| Constraint | Detail |
|---|---|
| Platform | Backend emission from Broadcast/Ads services. No UI surface. |
| Performance | Emit events such that CEBE propagation stays < 5s p99 (lead SLA). |
| API dependency | Lead squad's standardized event schema + Event Adapter (must be stable in staging first). |
| Plan / tier | N/A — emission is platform-internal; no plan/tier gating on this contribution. |
| Feature flag | Uses lead flag scope: cebe_event_ingestion (source: marketing) | default: OFF. |
| Fallback behavior | If the adapter is unavailable, emission is buffered/retried; Broadcast & Ads user flows (sending, reporting) continue normally — never blocked. |
| Data handling | Publish-only (write events). No reads from CEBE by this squad in this phase. |
| Ads sync | Ads metrics (impression/click/spend) synced from ad platforms (Meta/Google/TikTok) may be near-real-time or periodic per platform API limits — documented in RFC. |
6. Rollout
| Aspect | Detail |
|---|---|
| Feature flag | cebe_event_ingestion (marketing source) — derived from lead squad flag. |
| Rollout dependency | Follows lead squad. Lead must ship schema + adapter in staging before emission goes to canary. |
| Rollout | Stage 1 → Staging: emit synthetic Broadcast + Ads events; validate envelope + <5s Stage 2 → Canary: real events from N pilot accounts GA → All accounts; 12-month backfill loaded; metrics available via retriever |
| Backward compat | No change to existing Broadcast/Ads behavior. |
| Migration | Backfill last 12 months of Broadcast + Ads events on first connect. |
7. Observability
For initiative-level events, see lead Phase PRD §8 Observability: Core Infra TECH PRD.
Events specific to this squad's contribution
| Event Name | Trigger | Properties |
|---|---|---|
marketing_event_emitted | Broadcast/Ads event published to adapter | event_name, channel/ad_platform, qontak_customer_id, timestamp |
marketing_event_emit_failed | Emission to adapter fails | event_name, reason, retry state |
ads_spend_sync_completed | Periodic ad-spend sync from platform | ad_platform, records, period |
Dashboard & Alerts
| Aspect | Detail |
|---|---|
| Dashboard owner | Broadcast Squad (emission health). Initiative dashboard: BI/Data Squad. |
| Alerts | • marketing_event_emit_failed rate > 2% in 10 min → Broadcast on-call• Ads spend sync missing for > 24h → Broadcast + BI/Data |
8. Success Metrics
Initiative-level metrics are defined in the lead Phase PRD §9 Success Metrics: Core Infra TECH PRD.
Component-specific
| Category | Metric | Definition | Baseline | Target |
|---|---|---|---|---|
| Enablement | Marketing source coverage on CEBE | % of Broadcast + Ads events successfully emitted to CEBE | 0 | Broadcast + Ads live with ≥ 99% emission success by end of Q3 2026 |
9. Dependencies
| Dependency | Owning Team | Deliverable Needed | Blocking? |
|---|---|---|---|
| Standardized event schema + Event Adapter | CDP Squad | Schema + adapter stable in staging by RFC date | YES |
qontak_customer_id / ContactResolver | CDP Squad | Identity key resolvable for marketing contacts | YES |
| Retriever/metrics layer | CDP + BI/Data | Reply rate / ads-conversion metric definitions | NO (parallel) |
| Ad platform APIs (Meta/Google/TikTok) | External + Broadcast | Access to impression/click/spend data | YES (for Ads events) |
10. Key Decisions + Alternatives Rejected
10a — Decisions Made
| Date | Decision | Rationale |
|---|---|---|
| 2026-06-26 | Emit BOTH Broadcast and Ads events (not Broadcast only) | Ads attribution (CPL/CPA/ROAS, % ads conversion) is core to the marketing use-case |
| 2026-06-26 | Publish-only integration; no reads from CEBE this phase | Keeps boundary clean; lead squad owns read/query path |
| 2026-06-26 | Reuse lead squad schema + ContactResolver; build nothing shared | Prevents overlap; Broadcast owns only emission |
10b — Alternatives Rejected
| Alternative | Why Rejected | Date |
|---|---|---|
| Broadcast builds its own marketing data store | Re-creates CEBE; defeats unified-layer goal | 2026-06-26 |
| Ship Broadcast events now, defer Ads to later phase | Misses paid-acquisition attribution the Primary use-case requires | 2026-06-26 |
11. Open Questions
| # | Type | Question | Owner | Deadline |
|---|---|---|---|---|
| 1 | Open Question | Contact-resolution rate for ad-sourced users (anonymous → qontak_customer_id)? | Broadcast + CDP | 2026-08-15 |
| 2 | Open Question | Ads spend sync cadence per platform given API rate limits (real-time vs daily)? | Broadcast + BI/Data | 2026-07-31 |
| 3 | Assumption | Lead squad's schema + adapter stable in staging ≥ 2 weeks before our canary | Both PMs | 2026-08-15 |
| 4 | Risk | If lead Phase 1 slips, marketing emission cannot ship in Q3 — no independent deliverable. Mitigation: stage synthetic emission against schema contract early | CDP PM | 2026-09-15 |
12. System Flow + User Stories + ACs
12.1 System Flow
Flow: Marketing (Broadcast + Ads) event emission into CEBE (Broadcast squad contribution) · Type: Integration Flow
- A Broadcast/Ads action occurs (message sent/replied/clicked, ad impression/click/conversion, or periodic spend sync).
- Broadcast service builds the standardized event envelope, keyed on
qontak_customer_idvia ContactResolver. - Broadcast publishes the event to the lead squad's Event Adapter ingestion contract (lead PRD §14 Behavior 1).
- (Lead) Adapter resolves identity, validates the schema, and dedups via the idempotency key.
- (Lead) Adapter writes the event to the Central DB (PII masked); the retriever recomputes marketing metrics.
- Marketing metrics (reply rate, ads conversion, ROAS) become queryable for segmentation / marketing automation.
- Failure: if the adapter or an ad-platform API is unavailable, the event is buffered + retried with zero loss, AND the Broadcast/Ads user flow continues normally (graceful degradation).
Architecture & ingestion diagram: see the anchor — 5. Architecture.
12.2 User Stories
| User Story | Importance | Mockup | Technical Notes | Acceptance Criteria |
|---|---|---|---|---|
| [CEBE-MKT-SUP-S01] — Emit Broadcast engagement events into CEBE As a Marketing Owner, I want Broadcast engagement captured in CEBE, so that reply rate, opt-in/out, and campaign attribution are reusable for segmentation and automation. | Must Have | — (no UI) | Data Fields: • Broadcast event list ( campaign.sent/replied/clicked/bounced/opted_in/opted_out) — see anchor → 4. Campaign Module §4a (not duplicated)• qontak_customer_id (string, required) — ContactResolver (lead)• campaign_id/template_id, channel, event_name — Broadcast• Flag: cebe_event_ingestion (marketing source, default OFF)Before-After Behavior: Before — broadcast engagement lives only in Broadcast tooling; CEBE has no marketing data. After — each engagement publishes a standardized event to CEBE in <5s, enabling central reply-rate and opt-status metrics; no change to the Broadcast UX. | — Happy Path — • AC-1: Given the marketing ingestion flag is ON, when a broadcast is sent/replied/clicked/opted-in/opted-out, then a standardized event (keyed on qontak_customer_id) reaches CEBE in <5s.• AC-2: Given a customer cannot be resolved to a qontak_customer_id, when the event is built, then it is emitted with available identifiers AND flagged for resolution (not dropped silently).• AC-3: Given the same event is retried, when re-published, then idempotency (lead) ensures no duplicate in CEBE. — Error / Unhappy Path — • ERR-1: Given the Event Adapter is unavailable/times out, when a broadcast event is emitted, then it is buffered + retried until acknowledged (zero loss), AND the Broadcast send/report flow is NOT blocked, AND marketing_event_emit_failed is logged.• ERR-2: Given a broadcast event fails schema validation at the adapter, when rejected, then the rejection is surfaced to the Broadcast service for correction (not dropped silently), AND logged for reconciliation. — Permission Model — • CAN: Broadcast service (system emission) • CANNOT: end users trigger emission • Unauthorized: N/A — backend emission — UI States — • N/A — no UI; Broadcast/Ads screens unchanged |
| [CEBE-MKT-SUP-S02] — Emit Ads events (impression, click, lead, conversion, spend) into CEBE As a Marketing Owner, I want Ads impressions, clicks, leads, conversions, and spend captured in CEBE, so that ads conversion and ROAS are measurable and ad-sourced customers are attributable. | Must Have | — (no UI) | Data Fields: • Ads event list ( ad.impression/clicked/lead_captured/converted/spend_recorded) — see anchor → 4. Campaign Module §4b (not duplicated)• ad_id/campaign_id, ad_platform (meta/google/tiktok) — Ad platform• conversion_value/ad_spend (number, conditional) — Ad platform• qontak_customer_id — ContactResolver (when resolvable)Before-After Behavior: Before — ads performance lives in ad platforms; CEBE has no ads data. After — ads events emitted/synced into CEBE, enabling % ads conversion, CPL/CPA, ROAS, and ad-attributed journeys; no change to Ads UX. | — Happy Path — • AC-1: Given the marketing ingestion flag is ON, when an ad impression/click/lead_captured/converted occurs, then a standardized ad event (with ad_platform, campaign_id, qontak_customer_id where resolvable) reaches CEBE in <5s of receipt.• AC-2: Given periodic ad-spend data from a platform, when the spend sync runs, then ad.spend_recorded events are emitted for the period AND ads_spend_sync_completed is logged.• AC-3: Given an ad event for an unresolved/anonymous user, when emitted, then it is captured with platform identifiers and reconciled to qontak_customer_id when later resolved (e.g. on CTWA conversation start) — not dropped.— Error / Unhappy Path — • ERR-1: Given an ad-platform API is unavailable during spend sync, when the sync runs, then it is retried next cycle with no duplicate spend (idempotent), AND ads_spend_sync_completed is NOT logged until success, AND a gap alert fires if spend missing > 24h.• ERR-2: Given the Event Adapter is unavailable, when an ad event is emitted, then it is buffered + retried (zero loss), AND no Ads management flow is blocked, AND marketing_event_emit_failed is logged.— Permission Model — • CAN: Broadcast/Ads service (system emission + platform sync) • CANNOT: end users • Unauthorized: N/A — backend emission — UI States — • N/A — no UI |
| [CEBE-MKT-SUP-S01-NEG] — Identity resolution stays with the lead adapter (Guard Rail — from Non-Goals) As the Broadcast service, when an unresolved marketing event arrives, then this squad does not implement dedup/merge logic. | Guard Rail | — | Boundary from Non-Goal #4 (identity resolution owned by lead). | • NEG-1: Given identity resolution (qontak_customer_id) is the lead squad's responsibility, when an unresolved marketing event arrives, then this squad does not implement dedup/merge logic — it defers to the lead adapter. |
| [CEBE-MKT-SUP-S02-NEG] — Downstream reads stay with the lead retriever (Guard Rail — from Non-Goals) As a segmentation / marketing-automation consumer, when querying marketing metrics, then this squad's component is not involved. | Guard Rail | — | Boundary from Non-Goal #2 (no downstream/read features). | • NEG-1: Given segmentation/marketing-automation consumption, when downstream features query marketing metrics, then this squad's component is not involved — the lead retriever/query layer governs reads. |
Dependencies: Lead schema + adapter (staging); ad-platform API access (for S02).
PRD CHANGELOG
| Version | Date | By | Section | Type | Summary |
|---|---|---|---|---|---|
| 1.0 | 2026-06-26 | Claude | All | CREATED | SUPPORT PRD for Broadcast Squad contribution to CEBE Phase 1: emit standardized Broadcast + Ads events into CEBE. |
| 1.1 | 2026-06-26 | Claude | S4, S12 | MODIFIED | Expanded flow; added Error/Unhappy Path blocks; Unauthorized line on S02; N/A plan/tier. |
| 1.2 | 2026-06-26 | Claude | Header, CB-S | MODIFIED | Linked shared Epic TF-3302; Status DRAFT → READY. |
| 1.3 | 2026-06-26 | Claude | All | MODIFIED | Newest write-prd skill: added Scope Changes; 5-column story table; linked event lists to anchor. |
| 1.4 | 2026-06-26 | Claude | CB-S, S5, S6, S7, S8, S12 | MODIFIED | Converted fenced code-block sections to tables/lists per skill. Committed to documents repo as .md. |