Multi-channel Intake

The authoritative specification for how the Sindh IT Portal — Facilitation Desk (SITP) turns any inbound contact from any channel into a tracked, routed, deduplicated, multilingual ticket — meeting companies and citizens where they already are.

1. Scope & Definitions

This document is the single source of truth for inbound intake across every channel the Portal supports. It defines what counts as a channel, how a message becomes a ticket (or appends to one), how the same complaint filed twice through two different channels is detected and merged, and how the system stays available even when an individual provider goes down.

The Portal's native web intake form and the partner Public REST API (POST /api/v1/tickets, see /specs/en/12-api-contract/) are the baseline intake paths and are fully specified in /specs/en/06-ticket-workflow/. This document covers the five multi-channel intake paths layered on top of that baseline, so the citizen never has to log in to a web form to be heard:

1. Email-to-ticket
2. SMS-to-ticket
3. WhatsApp-to-ticket
4. Toll-free IVR / voice
5. Walk-in / offline entry

Every channel converges on the same ticketing core, the same SLA/escalation engine, the same AI categorization, and the same audit log. Channel is an origin attribute, never a parallel workflow.

Glossary (short form; see _glossary.md):

All capabilities below are individually toggleable via the Feature Flag module (Q) and configurable per department per /specs/en/06-ticket-workflow/ §15.

2. Principle — Meet Companies Where They Are

The Portal's mandate is a single window for the IT industry to resolve problems with the Government of Sindh. A single window that only accepts submissions through a logged-in web form is not, in practice, a single window — it is a barrier. Pakistani IT companies, freelancers, and the citizens who interact with them do not live in a portal; they live in WhatsApp, SMS, email, and the phone. A field officer visiting a software park does not always have connectivity.

The Multi-channel Intake module therefore obeys four invariants:

These invariants are referenced by ID throughout this document and in the acceptance criteria in /specs/en/02-functional-reqs/ §MCI.

3. The Intake Pipeline

3.1 Overview

Regardless of channel, every inbound message traverses the same seven-stage pipeline before becoming a ticket or a comment. The pipeline is implemented as a BullMQ worker chain; each stage is idempotent, independently retryable, and emits an audit_events row. The stages are:

1. Ingest — receive the raw payload from the channel adapter (Mailjet inbound parse, SMS MO, WhatsApp Cloud API webhook, IVR recording callback, PWA sync batch).
2. Normalize — extract a canonical InboundMessage (sender identifiers, raw text, attachments, locale hints, channel-specific metadata) and drop or quarantine anything that fails structural validation.
3. PII detect & redact — run PII detection (FR-AI-009) on text and OCR-extracted attachment text; tokenize CNIC/phone/email before any cloud AI call; keep the redaction map on-prem.
4. Dedup check — run similarity detection (FR-AI-007, FR-MCI-005) against the sender's open tickets and recent resolved tickets; surface matches for the next stage.
5. AI categorize — classify and suggest routing (FR-AI-002, FR-AI-003); detect urgency/sentiment (FR-AI-004); detect language (§9).
6. Create or append — either create a new ticket (FR-TKT-001 tracking ID assigned) or append as a comment to the matched existing ticket (thread matching, §7). Channel of origin is stamped (FR-MCI-006).
7. Confirm to sender — send an acknowledgement carrying the tracking ID back through the originating channel, with cross-channel fallback (§12) if the originating channel is down.

3.2 Pipeline diagram

The diagram shows a single inbound message entering through any of the five channels and traversing the pipeline. The identity-linking and routing side-effects interact with the pipeline at the points shown. Provider outage (red dashed) triggers the fallback chain (§12) for confirmations only; ticket creation itself never depends on the originating provider.

3.3 Written description

A message arrives on any of the five channels and is delivered to the Inbound webhook receiver described in /specs/en/08-integrations-spec/ §9.2 — a single front door that verifies the provider's signature, rejects replays, and enqueues a normalized envelope to the intake queue. The rate-limit / anti-abuse gate (§10) is applied at the receiver, before any expensive work; floods from one sender are dropped or throttled before they reach the pipeline.

The ingest worker reads the envelope, records it (sensitive fields redacted) in int_call with direction inbound, and hands the raw payload to the normalize stage, which produces a canonical InboundMessage carrying: sender identifiers (email, MSISDN, WA-verified name, CNIC if disclosed, rep ID if matched), the raw subject/body, attachments (presigned refs into the staging bucket), locale hints (Accept-Language for email, device locale for WA, detected script for SMS, language declared by IVR caller), and channel-specific metadata (message ID, reply context, in-reply-to/References headers, IVR call ID, walk-in officer ID).

PII detection runs next (FR-AI-009): CNIC, phone, email, and any configured patterns are tokenized before any cloud AI call, and a redaction map is kept on-prem so the original can be restored in storage and re-masked at presentation. Attachments are AV-scanned by ClamAV (FR-FILE-003) at this stage and quarantined on detection.

Dedup (FR-MCI-005) compares the normalized message against the sender's open tickets and recently resolved tickets using the similarity service (FR-AI-007). Matches are returned with similarity scores, not silently merged — the create-or-append decision in stage 6 consumes them.

AI categorize (FR-AI-002, FR-AI-003, FR-AI-004) produces a summary, a category, a department/section/urgency suggestion with confidence, and a sentiment label. Language detection (§9) tags the message locale. If AI is unavailable or below the confidence threshold, the ticket enters the manual triage queue without blocking.

The create-or-append decision is the only branch in the pipeline:

• No confident dedup match (or only resolved matches) → create a new ticket with the canonical tracking ID (FR-TKT-001), stamp channel_of_origin (FR-MCI-006), attach the AI suggestions for the triage officer, and trigger channel-agnostic routing (§8) to the target department/section and SLA tier.
• Confident dedup match against an open ticket → append the inbound as a public comment on the matched ticket, re-using that ticket's existing routing; the dedup choice (proceed / link / merge) is surfaced to the triage officer and audit-logged per FR-MCI-005.
• Thread-matched reply (an inbound that explicitly references a tracking ID, e.g. a reply to a notification) → always appends, regardless of dedup score (§7).

Finally, confirmation is sent back to the sender on the originating channel — a new ticket gets its tracking ID; an appended reply gets an acknowledgement that the message was added. If the originating provider is unavailable, the fallback chain (§12) routes the confirmation through the next-best channel for that sender (e.g., SMS fallback if WhatsApp is down).

4. Channel Capabilities (matrix)

The five inbound channels differ in bandwidth, attachment support, two-way capability, and regulatory dependencies. The table below is the capability contract every channel adapter must satisfy; the per-channel details live in §5.

The web form (channel_of_origin = web) and Public API (channel_of_origin = api) are the baseline channels documented in /specs/en/06-ticket-workflow/ and /specs/en/12-api-contract/; they share the same pipeline once past ingest and are not re-specified here.

5. Per-channel Specification

Each channel is described against the integration template from /specs/en/08-integrations-spec/ §3 so contracts are comparable. Where the underlying transport is already specified in /specs/en/08-integrations-spec/ §5 (Mailjet, SMS, WhatsApp), this section covers only the intake-specific behaviour layered on top.

5.1 Email-to-ticket

5.2 SMS-to-ticket

5.3 WhatsApp-to-ticket

5.4 Toll-free IVR / Voice

5.5 Walk-in / Offline Entry

6. Inbound Message → Ticket Field Mapping

Every inbound message, regardless of channel, is mapped to the same canonical ticket model (see /specs/en/05-data-model/). The table below is the authoritative field map. Where a channel has no native value for a field, the pipeline fills it from AI (§3.3 stage 5) or leaves it for triage.

Tickets created from inbound channels are otherwise indistinguishable from web/API tickets in the data model; downstream SLA, escalation, proof-of-resolution, and analytics logic does not branch on channel_of_origin.

7. Identity Linking

Inbound messages rarely carry a logged-in session; they carry a channel identity (email address, MSISDN, WA-verified phone, caller ID, CNIC). The pipeline resolves that identity to an existing organization / representative, or creates a Provisional identity, before the ticket is created (MC-2).

7.1 Resolution order

The identity-linking service, invoked at the normalize stage, attempts resolution in this priority order:

1. Exact rep match — the inbound identifier matches a representative's registered email or phone (org_rep table).
2. Organization domain match — for email, the sender domain matches a registered organization's verified domain (file-first domain-email signal, _context.md §5).
3. CNIC match — the inbound discloses or carries a CNIC (IVR DTMF, walk-in officer entry, message body extracted via PII detect) that matches a representative's CNIC.
4. Provisional identity — no match found; a Provisional sender record is created with the channel identifier, marked unverified, and the ticket is attributed to it. The sender is invited to register; on successful registration, the provisional identity is merged into the new rep and the ticket is re-attributed.

7.2 Identity table

Identity linking is read/write against the identity tables only at the normalize stage; later stages read the resolved identity from the pipeline context. This keeps PII handling in one audited place.

8. Channel-agnostic Routing

Once a ticket is created, routing is identical regardless of channel (MC-4). The AI routing suggestion (FR-AI-003) and the department/category configuration drive the target department and section, exactly as for web tickets (see /specs/en/06-ticket-workflow/ §4–§5). The only channel-aware behaviour is fallback confirmation (§12).

Two guarantees apply:

• A ticket created from a low-bandwidth channel (SMS, IVR) is not penalized in routing or SLA because it lacks a long description. The AI summary + officer triage enriches the description before routing is finalized; the FRT clock is not started until triage completes (consistent with the New → Triaged → Assigned model in /specs/en/06-ticket-workflow/ §2).
• A ticket created from a Provisional sender (§7) routes normally; verification status does not gate triage (file-first / verify-in-parallel, _context.md §5).

9. Multilingual Inbound

The Portal serves EN/UR/SD as locked languages (_context.md §2). Inbound messages arrive in any of these (and occasionally in mixed or transliterated forms). The pipeline handles this in three steps:

IVR adds a caller-declared language at the start of the call; the IVR prompts and STT engine use it as the primary language with auto-fallback. Walk-in officers select the form locale at the counter; if the visitor dictates in another language, the officer's recorded text is language-detected at sync.

10. Rate-limiting & Anti-abuse

Inbound intake is an open surface; it must resist spam, flooding, and abuse without blocking legitimate senders (FR-MCI-007, _context.md §6). Controls are layered:

Every rate-limit and anti-abuse decision is audit-logged with the rule that fired. Held/quarantined inbound appears in a review queue for the on-shift facilitator; releasing an item runs it through the rest of the pipeline from stage 3 onward.

11. Dedup & Merge across Channels

A complainant may file the same issue by email in the morning and by WhatsApp that afternoon; a colleague at the same company may SMS it an hour later. The system must detect this and suggest a merge, never auto-merge silently (FR-MCI-005, FR-TKT-015).

11.1 Detection signals

11.2 Merge decision

The dedup check (pipeline stage 4) returns candidate matches with similarity scores. The triage officer decides:

• Proceed as new — no merge; the choice is audit-logged.
• Link — create a typed relation (related to, duplicate of) per FR-TKT-017; both tickets remain independently tracked.
• Merge — fold the newer ticket into the older (or officer-chosen primary) per FR-TKT-015: secondary is locked, attachments/comments/watchers consolidate onto the primary, the filer is notified with the primary's tracking ID.

11.3 Dedup & merge flow

The diagram shows the dedup decision as a state machine driven by the triage officer.

12. Fallback Chain & Cross-channel Resilience

Each channel depends on a third-party provider (Mailjet, the SMS aggregator, Meta, the IVR/PSTN carrier, and — for walk-in — the officer's connectivity). No single provider is allowed to be a hard dependency for inbound intake, and confirmation delivery must always find a working path.

A channel being read-only down (inbound fine, outbound broken) is surfaced to the triage officer on the ticket so manual follow-up can happen via another channel.

13. Offline / Field Intake

Walk-in/offline entry (§5.5) is the most operationally demanding channel because the officer's device may be offline at the point of capture. The contract:

14. Channel Analytics

Channel of origin is a first-class analytics dimension (FR-MCI-006). The Analytics module (/specs/en/17-analytics-kpis/) produces the following channel-scoped metrics, sourced from the anl_mv_* materialized views and respecting RBAC + the public suppression rules (AP-3, AP-4).

All channel metrics share the same definitions and rounding rules as their channel-agnostic counterparts (AP-5); the only added dimension is channel_of_origin.

15. Data Model Touchpoints

This document does not redefine the data model (see /specs/en/05-data-model/) but records the multi-channel-specific fields and tables it relies on:

16. End-to-end Sequence (one inbound → one ticket)

The sequence below shows a single WhatsApp inbound becoming a new ticket, with confirmation. The same shape applies to every channel; only the receiver and confirmation adapter change.

The receiver verifies the signature and applies the rate-limit gate before any pipeline work (steps 2–3). PII redaction runs before any cloud AI call (step 5). Identity and dedup run in parallel with categorization where data dependencies allow. Confirmation is the last step, with cross-channel fallback (§12) so a WhatsApp outage at confirmation time does not strand the sender.

17. Non-functional Requirements (MCI-specific)

These NFRs refine the system-wide NFRs (03-non-functional-requirements/en.md) and the integration NFRs (/specs/en/08-integrations-spec/ §11) for the multi-channel intake surface.

18. FR Traceability

This document is the detailed expansion of the MCI module FRs in /specs/en/02-functional-reqs/ §MCI.

Cross-cutting FRs relied upon: FR-TKT-001 (tracking IDs), FR-TKT-006 (anonymous status lookup, used by IVR), FR-TKT-007/FR-TKT-008 (SLA + escalation, channel-agnostic), FR-TKT-015/FR-TKT-017 (merge + link), FR-FILE-003/FR-FILE-004 (AV + encrypted storage), FR-AI-002/FR-AI-003/FR-AI-004/FR-AI-006/FR-AI-007/FR-AI-009 (AI capabilities), FR-ORG-009 (step-up for sensitive walk-in), FR-NOT-001/FR-NOT-003 (notifications + inbound reply append).

19. Open Questions / TBD

End of document.