¶ Technical Documentation: Bank–SAMA Complaint Management Integration
¶ 1. Purpose
This document describes the integration between a bank's internal Complaint Management System (CMS) and the Saudi Central Bank's (SAMA) complaint platform. It covers the escalation workflow, actors, states, the Complaint Triage Agent (AI agent for detection/routing), and integration touchpoints required to implement the system.
¶ 2. Actors
| Actor | Description |
|---|---|
| Customer | Raises the complaint/inquiry/suggestion via bank channels |
| Complaint Triage Agent | AI agent that classifies, detects escalation triggers, and drafts handoff summaries (see Section 6) |
| Bank L1 | First-line agent/team handling the complaint |
| Bank L2 | Second-level / specialized team for unresolved or complex cases |
| SAMA (Ministry) | Central bank platform acting as regulator / final escalation point |
¶ 3. Case Types
- Inquiry — informational request, no dispute
- Suggestion — feedback, no dispute
- Complaint — dispute requiring resolution and possible escalation
Only Complaints follow the full escalation lifecycle described below. Inquiries and Suggestions are typically closed at L1 without escalation unless the customer explicitly disputes the response.
¶ 4. Case Lifecycle / Escalation Rules
| # | Rule | Trigger | Result |
|---|---|---|---|
| 1 | Direct closure | Simple inquiry/suggestion resolved by Bank L1 | Case Closed |
| 2 | Customer dissatisfaction | Customer rejects L1's response | Case Escalated (reopened) to L1 supervisor / re-review, or directly to L2 depending on bank policy |
| 3 | SLA breach at L1 | L1 does not resolve within configured SLA (e.g., X business days) | Auto-escalate to Bank L2 |
| 4 | L2 unable to resolve | L2 cannot resolve within its SLA, or determines it is outside its authority | Escalate to SAMA (Ministry) |
| 5 | Direct-to-SAMA categories | Case type is pre-flagged as "direct escalation eligible" (defined by SAMA category list) | L1 can escalate directly to SAMA, bypassing L2 |
¶ 4.1 State Diagram (textual)
[New]
→ (Inquiry/Suggestion, resolved) → [Closed]
→ (Complaint, resolved by L1) → [Pending Customer Confirmation]
→ (Customer satisfied) → [Closed]
→ (Customer dissatisfied) → [Escalated - L2]
→ (Complaint, L1 SLA breach) → [Escalated - L2] (auto)
→ (Complaint, direct-escalation category) → [Escalated - SAMA] (auto/manual by L1)
[Escalated - L2]
→ (Resolved by L2, customer satisfied) → [Closed]
→ (L2 SLA breach / unresolved) → [Escalated - SAMA]
[Escalated - SAMA]
→ (SAMA resolves / instructs bank) → [Closed] or [Reopened at Bank]¶ 4.2 SLA Configuration
SLA timers should be configurable per case category/severity, e.g.:
| Level | Default SLA | Escalation Trigger |
|---|---|---|
| L1 | 3–5 business days (configurable) | Timer expiry without closure |
| L2 | 5–10 business days (configurable) | Timer expiry without closure |
| SAMA direct-eligible types | Immediate (no SLA wait) | Category match |
¶ 5. High-Level Architecture
Customer
│
▼
Bank Channels (branch, app, call center, email)
│
▼
Bank CMS (case creation, SLA engine, workflow) ───► Bank L1 / L2 queues
│ ▲
│ │
▼ │
Complaint Triage Agent (classification, dissatisfaction/SLA/rule-5 detection,
escalation summaries — see Section 6)
│
│ (escalation event / status sync)
▼
SAMA Integration Layer (API Gateway / Adapter)
│
▼
SAMA Complaint PlatformThe Integration Layer is responsible for:
- Translating bank CMS case objects into SAMA's required schema
- Pushing escalation events to SAMA (create, update, escalate, close)
- Receiving status/resolution updates from SAMA and syncing them back to the bank CMS
- Logging every transaction for audit and regulatory reporting
¶ 6. AI Agent — Ticket Detection & Escalation Assistant
Rather than a single classification call, this is framed as an agent ("Complaint Triage Agent") that observes case events, reasons over them, and takes actions within defined tools/permissions — with humans approving anything that affects customer-facing outcomes.
¶ 6.1 Where it fits in the flow
Customer submits case (text/voice-transcript/email/chat)
│
▼
Complaint Triage Agent ◄── monitors: new case, customer reply, SLA timer events
│
│ reasons using: SAMA category taxonomy, escalation rules, case history,
│ similar past cases
│
│ acts via tools:
│ - classify_case() → type/category/subcategory/severity
│ - flag_direct_escalation() → rule 5 (direct L1→SAMA eligible)
│ - detect_dissatisfaction() → rule 2 (customer rejected response)
│ - check_sla_breach() → rule 3/4 triggers
│ - suggest_response() → draft for agent review
│ - summarize_case() → handoff summary for L2/SAMA escalation
│ - request_human_review() → fallback on low confidence
▼
Bank CMS (case created/updated/routed/escalated based on agent's action + human approval where required)¶ 6.2 Agent responsibilities (mapped to escalation rules)
| Rule | Agent behavior |
|---|---|
| 1 | Classifies inquiry/suggestion, confirms no dispute signal → routes for straightforward L1 closure |
| 2 | Monitors customer's reply after L1 response; on dissatisfaction/rejection signal, triggers escalation event |
| 3 | Watches SLA timer per case; on breach, auto-triggers escalation to L2 |
| 4 | On L2 SLA breach or explicit "unresolved" marker, triggers escalation to SAMA |
| 5 | Checks case content/category against direct-escalation list at intake; flags for immediate L1→SAMA path |
¶ 6.3 Agent design principles
- Tool-based, not free-form: the agent only acts through the defined tools above (classify, flag, detect, check, suggest, summarize, request review) — it does not directly close cases or send customer-facing messages itself.
- Human-in-the-loop for customer-impacting actions: case closure, final response wording, and SAMA submissions require agent-suggested → human-approved, not full autonomy, given the regulatory context.
- Deterministic guardrails around probabilistic reasoning: SLA breach checks and rule-5 category matching should be backed by hard rules/lookup tables, with the LLM used for the harder judgment calls (dissatisfaction sentiment, free-text classification, summarization) — don't let the LLM freehand a decision a simple rule can make reliably.
- State-aware: the agent has access to full case history (not just the latest message) so multi-turn reasoning (e.g., "customer already rejected once before") is possible.
- Auditable actions: every tool call the agent makes (classification, flag, escalation trigger) is logged against the case record with confidence score and rationale, since SAMA/compliance may need to see why a case was routed a certain way.
- Confidence thresholds: below a set confidence, the agent calls
request_human_review()instead of acting, so ambiguous cases don't get silently misrouted.
¶ 6.4 Architecture placement
- Runs as a service invoked by the Bank CMS at: case creation, customer reply received, and SLA timer events (event-driven, not purely on-demand).
- Sits as a component between the CMS event stream and the case workflow/state engine — it reads events, decides, and calls back into CMS APIs to change state or raise flags.
- Classification/decision output (category, confidence score, flags, rationale) is stored on the Case record for audit.
¶ 6.5 Data/model considerations
- Needs a labeled dataset or few-shot prompt aligned to SAMA's official complaint category taxonomy (see Open Items — request this taxonomy)
- PII handling: customer complaint text may contain sensitive data; if using a third-party/hosted LLM, confirm data residency and processing terms meet SAMA/Saudi data protection requirements — may require an in-country or on-prem model deployment
- Feedback loop: agent corrections to LLM classification should be logged and used to monitor/improve model accuracy over time
¶ 7. Integration Points (API-level)
| Operation | Direction | Description |
|---|---|---|
POST /cases |
Bank → SAMA | Create a new case record at SAMA when escalated (L1-direct or L2-failure) |
PUT /cases/{id}/status |
Bank → SAMA | Update SAMA on case status changes (e.g., closed at bank before SAMA involvement, if applicable) |
POST /cases/{id}/escalate |
Bank → SAMA | Formal escalation submission with case history and evidence |
GET /cases/{id} |
Bank ← SAMA | Poll/webhook for SAMA's resolution or status update |
POST /webhooks/sama-status |
SAMA → Bank | Push notification when SAMA updates the case (recommended over polling) |
Each payload should include:
- Case ID (bank-side) and SAMA reference ID (once assigned)
- Case category/type
- Full escalation history (timestamps, level, actions taken, responses given)
- Customer consent/data-sharing confirmation (regulatory requirement)
- Supporting documents/attachments references
¶ 8. Data Model (Core Entities)
Case
- case_id, customer_id, channel, category, subcategory
- status (New, In Progress, Pending Confirmation, Escalated-L2, Escalated-SAMA, Closed, Reopened)
- current_level (L1, L2, SAMA)
- created_at, sla_due_at, closed_at
Escalation Log
- escalation_id, case_id, from_level, to_level, reason (SLA breach / customer dissatisfaction / direct-eligible category / L2 unresolved), timestamp
SAMA Sync Record
- case_id, sama_reference_id, last_synced_at, sync_status, payload_snapshot
¶ 9. Notifications
- Customer notified at each transition (acknowledgment, L1 response, escalation, SAMA involvement, resolution)
- Internal alerts to L2/compliance team when a case nears SLA breach or is auto-escalated
- Audit trail retained for regulatory review (SAMA may require full history on request)
¶ 10. Non-Functional Considerations
- Auditability: every status change and escalation must be logged immutably
- SLA engine: configurable per case category, with automated escalation triggers (cron/scheduler or event-driven timers)
- Security: encrypted transport (TLS) and authentication (mutual TLS or OAuth2) with SAMA gateway; PII handling per SAMA data protection requirements
- Idempotency: escalation/status API calls must be idempotent to handle retries safely
- Reconciliation: periodic batch job to reconcile case statuses between bank CMS and SAMA in case of missed webhooks
¶ 11. Open Items for Clarification
- Exact SAMA API schema/spec version and authentication mechanism
- List of case categories eligible for direct L1 → SAMA escalation
- Configurable SLA durations per category (to confirm with business/compliance)
- Whether SAMA supports webhooks or requires polling
- SAMA's official complaint category taxonomy (needed to train/prompt the LLM classifier)
- Whether a hosted LLM API is acceptable or an in-country/on-prem deployment is required for data residency
