Interaction processing

Manual home · Role guides · Coverage · Gaps

Manual conventions and recovery apply to every workflow. Evidence level: code inspected; related tests were inspected, not executed.

flowchart TD
  A[Audio or completed conversation] --> B[Authenticate and validate]
  B --> C{Accepted?}
  C -->|No| D[Correct payload or retry eligible failure]
  C -->|Yes| E[Persist interaction and processing association]
  E --> F[Produce or validate redacted evidence]
  F --> G{Human transcription review required?}
  G -->|Yes| H[Correct and approve draft]
  G -->|No| I[Store available artifacts]
  H --> I
  I --> J[Analyse and allocate review]

INT-01 — Find and review an interaction

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: find and review an interaction.

Actors and access: qms:read; additional permissions govern actions.

Prerequisites: An ingested interaction in the current tenant.

Entry point: Interactions; global search.

1. Search or filter the interaction list by available channel, team, dates and status controls; continue pagination as needed.
2. Open the interaction and review redacted conversation/transcript, available audio, metadata, analysis and review status.
3. Follow evidence timestamps and linked review/journey records for deeper investigation.

Result: The interaction and its available evidence are inspected without modifying it.

Exceptions and recovery: Missing audio or expired artifacts can coexist with an interaction record. Check processing state and retention before treating absence as failure. Unavailable records remain tenant-isolated.

Source evidence: services/api/src/interactions/routes.ts; services/api/src/search/routes.ts; apps/web/src/features/interactions/interactions.tsx.

INT-02 — Upload call audio for transcription

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: upload call audio for transcription.

Actors and access: interactions:write; tenant-authenticated upload.

Prerequisites: Supported audio and configured transcription gateway; choose an available vocabulary profile if relevant.

Entry point: Interactions → audio upload; interaction transcription endpoint.

1. Select/drop call audio and confirm metadata. The web queue handles per-file progress and bounded concurrency.
2. Submit the upload. The API records the interaction/job association and snapshots effective transcription settings and the selected profile.
3. Monitor processing in Interactions or transcription jobs; open the completed interaction once redacted results are delivered.

Result: Accepted files continue server processing independently of later navigation.

Exceptions and recovery: Retry failed upload items individually; distinguish upload acceptance from transcription completion. Reload restores server processing state, but do not assume an unsent browser file is durably queued. Bulk drops accept up to 25 files.

Source evidence: services/api/src/transcription-jobs/upload-route.ts; apps/web/src/features/interactions/interactions.tsx; services/api/src/transcription-jobs/result-lifecycle.ts.

INT-03 — Ingest completed chat or email conversations

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: ingest completed chat or email conversations.

Actors and access: Channel-aware integration credential; tenant and channel resolved at the integration boundary.

Prerequisites: Configured defaults/attribution, retention policy, stable conversation ID and pre-redacted immutable payload.

Entry point: Integration delivery: live-chat/conversations, email/threads or generic conversations.

1. Deliver the completed channel-specific conversation with the integration credential and redaction declaration.
2. Inspect the response: an identical delivery replays, while a different payload under the same conversation ID conflicts.
3. Open the created interaction, stored conversation and redacted-transcript artifact; follow subsequent analysis/review.

Result: One tenant conversation creates the normal interaction/evidence pipeline.

Exceptions and recovery: Reject unredacted content, wrong channel or invalid attribution before retrying. A validation-only request in OPS-01 tests the payload without ingesting it. Never change content merely to force a replay.

Source evidence: services/api/src/conversations/routes.ts; services/api/src/conversations/ingest.ts; packages/contracts/src/conversations.ts.

INT-04 — Import conversation files and manage import profiles

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: import conversation files and manage import profiles.

Actors and access: interactions:write.

Prerequisites: Transcript retention is configured; source rows match supported conversation import fields.

Entry point: Interactions → Import.

1. Load the file and map source fields; select an existing profile or save/update one for repeat imports.
2. Review mapped rows and validation results, then submit the batch.
3. Inspect per-row outcomes and open successful interactions; delete an obsolete mapping profile if no longer needed.

Result: Valid conversations are ingested through the common ingestion boundary.

Exceptions and recovery: Partial results require retrying corrected failures, not blindly resubmitting changed successful conversations. Profile names must be unique; deleting a profile does not delete imported interactions.

Source evidence: services/api/src/interaction-imports/routes.ts; apps/web/src/features/interactions/interaction-import.tsx; packages/contracts/src/interaction-imports.ts.

INT-05 — Import phone transcripts and attach matching audio

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: import phone transcripts and attach matching audio.

Actors and access: interactions:write.

Prerequisites: Configured retention and a phone-call transcript batch; optional matching WAV media.

Entry point: Interactions → Import calls.

1. Map/import phone-call transcript records and inspect per-call results.
2. For retained playback, upload matching media against the imported transcript ID after the interaction exists.
3. Open each successful interaction and verify transcript/audio association.

Result: Imported calls have transcript evidence and, when accepted, compressed playback media.

Exceptions and recovery: Voice-media import specifically validates a WAV body and its 200 MB limit; this differs from direct call uploads. Missing transcript association, invalid WAV headers, encoding failure or different pre-existing audio require correction before retry.

Source evidence: services/api/src/interaction-imports/routes.ts; apps/web/src/features/interactions/phone-call-import.tsx.

INT-06 — Authorise, complete and read artifact uploads

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: authorise, complete and read artifact uploads.

Actors and access: artifacts:write for upload; qms:read for list/content.

Prerequisites: Existing interaction, declared MIME/size/SHA-256 and configured object storage.

Entry point: Interaction artifact API; interaction evidence UI.

1. Request a short-lived upload authorisation using a stable idempotency key.
2. Upload the exact bytes to the authorised target, then request completion.
3. The server verifies storage length/checksum and makes an accepted artifact available; list/read it through tenant-authenticated endpoints.

Result: A verified artifact is available for evidence and eligible downstream processing.

Exceptions and recovery: Missing objects can be retried after upload; integrity mismatches are quarantined. Do not mark completion using client-supplied metadata. Raw media access also depends on deployment policy and retention.

Source evidence: services/api/src/artifacts/routes.ts; services/api/src/artifacts/upload-authorization.ts.

INT-07 — Monitor transcription work and cancel eligible jobs

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: monitor transcription work and cancel eligible jobs.

Actors and access: transcriptions:manage for list/cancel; qms:read for associated job detail.

Prerequisites: A recorded tenant submission and reachable gateway.

Entry point: Transcription jobs; per-interaction job status.

1. Filter/list transcription jobs and inspect status, interaction link and settings snapshot.
2. Distinguish queued/running/failed/review states from completed redacted delivery.
3. Request cancellation when offered and refresh the status before deciding whether replacement work is needed.

Result: The server reports current gateway state or a cancellation result.

Exceptions and recovery: A missing/unavailable gateway is distinct from an unknown tenant submission. Cancellation follows gateway state rules; do not claim it removes already delivered evidence. Investigate failed work before creating duplicate submissions.

Source evidence: services/api/src/transcription-jobs/routes.ts; apps/web/src/features/transcription-jobs/transcription-jobs.tsx.

INT-08 — Review and approve a transcription draft

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: review and approve a transcription draft.

Actors and access: transcriptions:manage; service-authenticated callback creates the review draft.

Prerequisites: A callback tied to a valid upload submission and effective retention policy.

Entry point: Transcription review.

1. Open a pending review transcript and inspect text, speaker/channel assignments and redaction issues.
2. Correct the supported fields and explicitly approve the draft.
3. Confirm accepted results/artifacts on the interaction and downstream analysis state.

Result: Reviewed transcription results enter the final delivery lifecycle.

Exceptions and recovery: Invalid corrections or stale/conflicting delivery must be resolved against the current record. Callbacks derive tenant/interaction from the stored submission; they do not trust arbitrary client attribution. External worker internals remain separately unverified (GAP-04).

Source evidence: services/api/src/transcription-jobs/routes-review.ts; services/api/src/transcription-jobs/result-lifecycle.ts; apps/web/src/features/transcription-jobs/transcription-review.tsx.

INT-09 — Assign or unassign an interaction

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: assign or unassign an interaction.

Actors and access: audits:manage; assignee must be an active tenant member.

Prerequisites: Existing interaction and a valid directory selection.

Entry point: Interactions → assignment controls.

1. Select an interaction and choose an assignee from the active directory.
2. Submit assignment, or unassign an existing assignment.
3. Refresh filters/details and check the recorded assignee and audit activity.

Result: Interaction ownership metadata changes; this is separate from assigning an audit reviewer.

Exceptions and recovery: Inactive or foreign-tenant assignees are rejected. Use QMS-01 to allocate an actual review; an interaction assignee alone does not grant reviewer ownership.

Source evidence: services/api/src/interactions/routes.ts; services/api/src/identity/assignee.ts; apps/web/src/features/interactions/interactions.tsx.

INT-10 — Archive, restore, delete or correct processing status

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: archive, restore, delete or correct processing status.

Actors and access: interactions:write; privileged bulk actions additionally check audits:manage.

Prerequisites: Identify the exact records and review their dependencies before destructive actions.

Entry point: Interaction row/bulk actions; interaction API.

1. Choose the supported archive/restore/delete action and inspect confirmation and selection.
2. Inspect every bulk result and refresh the list, including archive filters.
3. Use processing/failed status correction only where the API supports it; investigate actual jobs separately.

Result: Successful records change visibility/status or are removed with their associated stored data.

Exceptions and recovery: Deletion is blocked when reviews reference the interaction and can fail if stored-object cleanup fails. Partial bulk success is possible. There is no documented undo for permanent deletion; retry only verified failures.

Source evidence: services/api/src/interactions/routes.ts; services/api/src/interactions/repository.ts; apps/web/src/features/interactions/interactions.tsx.

INT-11 — Inspect analysis and request bounded reanalysis

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: inspect analysis and request bounded reanalysis.

Actors and access: qms:read for analysis; audits:manage for operations/reanalysis.

Prerequisites: Existing redacted evidence, configured processing and explicitly selected tenant/date/channel scope.

Entry point: Interaction detail; interaction-analyses operations/reanalysis API.

1. Inspect the stored analysis, source/configuration versions and processing status.
2. Preview the operations selection and choose the supported bounded reanalysis criteria.
3. Submit reanalysis, inspect queued/skipped results, and monitor new jobs before comparing results.

Result: Eligible interactions are queued for analysis under the selected configuration.

Exceptions and recovery: Historical reanalysis is a deliberate operator action governed by the journey rollout runbook. Missing artifacts, unchanged versions or busy jobs may be skipped/rejected; do not broaden scope just to increase results.

Source evidence: services/api/src/interaction-analyses/routes.ts; services/api/src/interaction-analyses/reanalysis.ts; docs/journey-intelligence-runbook.md.

INT-12 — Create interaction metadata through the ingestion API

Status: Implemented. Verification: code inspected; no runtime completion claim.

Purpose: create interaction metadata through the ingestion API.

Actors and access: interactions:write.

Prerequisites: A stable external ID and payload matching the interaction contract.

Entry point: POST /api/v1/interactions.

1. Submit tenant interaction metadata using the supported ingestion contract.
2. Inspect created versus replayed response and the stored tenant interaction ID.
3. Attach/upload evidence through INT-02/06 or deliver a completed conversation through INT-03 before expecting analysis/review evidence.

Result: An idempotent interaction record exists; creating metadata alone does not establish completed transcription or analysis.

Exceptions and recovery: The same external ID with different content conflicts. Correct source identity/payload rather than assigning new IDs to conceal duplicates. Without artifacts or conversation delivery, evidence-dependent downstream workflows may remain unavailable.

Source evidence: services/api/src/interactions/routes.ts; packages/contracts/src/interactions.ts.