Add `appKey` to Message in BCG `/send` Request

Version Control

Version	Date	Who	What
0.1	5 Nov 2025	Saji Varghese	Accepted

Document Overview

Decision required	How to update BCG interface to accept appKey in request
Decision Outcome	Add appKey to the message body `preferredAppKey`
Owner	Saji Varghese
Current Status	Accepted
Decider(s)

1. Context

Service: BCG (Broadcast Gateway Service) delivers co-ordinated on-site messages (mobile/website).
BCG accepts a request containing message payload(s) and delivery preferences (e.g., on-site vs. queue-if-offline; display model TOAST or FULL_SCREEN).

Interface Type: REST API (OpenAPI 3.0, title “Broadcast Gateway”, version v2).

RTI Change Driver:
- On-board Real-Time Intervention (RTI) to send mandatory safety-tool messages (with links) to at-risk customers.
- Track message interaction via CBS (Customer Behavior Service).
- Target only clients that are correctly integrated (rendering + CBS).
- Callers supply a client identifier (appKey) to enable targeting/observability.

Consumers: Internal non-RTI senders and the RTI service.

Constraints:
- Maintain backward compatibility for existing senders/clients.
- appKey must be optional.
- BCG does not validate appKey.

2. Decision Driver

Enable RTI client targeting by carrying an appKey.
Preserve existing behaviour (no breaking changes).
Keep the change minimal while supporting multi-message requests.
Avoid per-preference duplication unless a real need emerges.

3. Considered Options

Add appKey to the existing /send body at the top level (outside delivery preferences).
Add appKey to each delivery preference (per-preference value).
(Chosen) Add appKey to each Message item in the request (per-message value).

4. Decision

Adopt: Add an optional appKey field to the Message schema (not top-level, not per-preference).

Rationale:
- Backward compatible (existing callers do not need to send appKey).
- Supports scenarios where a single /send contains multiple messages that may target different clients.
- Avoids redundancy and inconsistency that could arise by repeating appKey within every preferences[] entry.
- Meets current RTI requirements without expanding BCG’s remit to validate keys.

Illustrative schema change (using your OpenAPI)

🔧 Minimal OpenAPI patch (YAML)

components:
  schemas:
    Message:
      type: object
      required:
        - payload
      properties:
        # NEW: optional appKey at Message-level
        preferredAppKey:
          type: string
          description: >
            Optional client identifier for targeting/observability. BCG does not
            validate this value. Useful for RTI to target clients properly integrated
            with on-site rendering and CBS tracking.
        messageId:
          type: string
        expiryDate:
          type: string
          format: date-time
        payload:
          $ref: "#/components/schemas/MessagePayload"
        preferences:
          type: array
          items:
            $ref: "#/components/schemas/DeliveryPreference"
        priority:
          type: integer
          format: int32
          minimum: -99
          maximum: 99
          default: 0
        retriedCount:
          type: integer
          format: int32
          minimum: 0
          default: 0

📦 “Before” vs “After” request examples (JSON)

Before:

{
  "accountId": 79159068,
  "programme": "Retain",
  "initiative": "PRC_PROGRESS",
  "messages": [
    {
      "messageId": "3d771b65-9b61-4924-818c-0f6e5aad5559",
      "expiryDate": "2025-11-12T00:00:00Z",
      "payload": {
        "urn": "ppb:messaging:prcReward",
        "params": {
          "promoCode": "PPREWARDSCLUBLV1",
          "link": "https://example/tools/safety"
        }
      },
      "preferences": [
        {
          "channels": [
            { "channel": "ON_SITE", "displayType": "TOAST" }
          ]
        }
      ]
    }
  ]
}

After (with per-message appKey):

{
  "accountId": 79159068,
  "programme": "Retain",
  "initiative": "PRC_PROGRESS",
  "messages": [
    {
      "preferredAppKey": "client-key-web-v5",
      "messageId": "3d771b65-9b61-4924-818c-0f6e5aad5559",
      "expiryDate": "2025-11-12T00:00:00Z",
      "payload": {
        "urn": "ppb:messaging:rtiSafetyTools",
        "params": {
          "link": "https://example/tools/safety"
        }
      },
      "preferences": [
        {
          "channels": [
            { "channel": "ON_SITE", "displayType": "FULL_SCREEN" }
          ]
        }
      ]
    }
  ]
}

5. Consequences

Positive

Backward compatible: Existing integrations remain valid; appKey is optional.
Per-message targeting: Supports multi-message requests where each message can target a different client/app.
No preference duplication: Avoids repeating appKey across preferences[], reducing inconsistency risk.
Operational clarity: Easier correlation in logs/metrics and CBS between a specific message and its client target.
Contained scope: Meets RTI needs without introducing validation/authorisation responsibilities into BCG.

Nagative

No per-preference granularity: If a future use case requires different appKeys per delivery preference, another additive change (or version) will be needed.
Governance outside BCG: Without validation, incorrect or spoofed appKeys must be controlled by upstream policy, client registries, or observability checks.
Observability updates: Dashboards, traces, and audits must surface Message.appKey alongside delivery outcomes and CBS events.
Potential ambiguity for mixed audiences: If a single message is intended for multiple client types, additional routing logic outside BCG may still be necessary.

Add appKey to Message in BCG /send Request