Interactions & channels

An interaction is the operational and evidentiary record of communication. It is not interchangeable with a task, channel-provider event, call attempt, or free-form note.

Lifecycle

Inbound interactions start from a provider or operator event, link or create the appropriate case, and record verification level before sensitive account details are disclosed.

One contact, several records

For an outbound collection call:

1. A task tells a worker to attempt contact.
2. A compliance decision evaluates this debt, person, phone, reason, time, and channel.
3. The interaction records the attempted call and content context.
4. Provider events record dial, connect, recording, and completion.
5. The interaction outcome may complete the task, schedule follow-up, or create a promise action.

This separation makes provider retries and task reassignment harmless to the communication record.

Required context

Every outbound interaction names:

• caseId, customer, covered loans or debts, and task when applicable;
• direction, channel, and exact purpose;
• resolved recipient and verified contact point;
• content template/version or approved ad hoc content hash;
• originating worker type—human, deterministic automation, or AI session;
• the execution-time compliance decision; and
• delivery and business outcome.

POST /v1/servicing/cases/1001/scheduled-callbacks
Idempotency-Key: case-HBR-22dpd-callback-01

{
  "windowStart": "2027-05-01T17:00:00-07:00",
  "windowEnd": "2027-05-01T18:00:00-07:00",
  "contactPointRef": "cp_MAYA_MOBILE_1",
  "reasonCode": "COLLECTIONS_FOLLOW_UP",
  "summary": "Borrower asked for an afternoon call about the past-due installment."
}

Future contact is booked as a scheduled callback — a phone promise held as a task on the case, carrying the exact window the borrower was given. The callback’s start-call command owns the current-fact eligibility decision at dial time; the caller cannot supply an earlier decisionId to authorize the call. Scheduled email, SMS, and chat sends are deliberately not offered: a message composed now is sent now, under the at-send gate. POST /v1/servicing/calls/outbound starts a live human dial under the same owned gate — the interaction evidence is created before policy runs, and a blocked or failed attempt is returned as 201 with its decisionId and failureCode rather than discarded. POST /v1/servicing/interactions separately records an inbound, outbound, or externally completed interaction.

The interaction point read returns this evidence in place: GET /v1/servicing/interactions/{interactionId} embeds the latest linked compliance decision (complianceDecision with its outcome, hard-stop flag, and per-rule results) and, for phone work, the voiceCall summary with dial authorization, connection timestamps, and recording state — while the dialed number and provider references stay out of the projection.

Transcript and recording

Conversation content lives behind two dedicated reads rather than inside the interaction projection:

• GET /v1/servicing/interactions/{interactionId}/transcript
• GET /v1/servicing/interactions/{interactionId}/recording

Both require READ_SERVICING_INTERACTION and the separate sensitive authorization, and both audit the access. They return no-store, short-lived content:

{
  "interactionId": 3001,
  "content": "Redacted example transcript.",
  "contentType": "text/plain",
  "expiresAt": "2027-05-05T18:35:00Z"
}

The recording read returns an opaque short-lived downloadUrl with its contentType and expiresAt instead of inline content. Treat both as issued to one authorized reader at one moment: do not cache the payload alongside the interaction, and do not persist the URL as a durable reference. Requesting again is cheap, and it keeps the access record honest about who read what.

Keeping this content out of GET /v1/servicing/interactions/{interactionId} is deliberate. The interaction projection is what a workspace, report, or AI work packet can hold; the words spoken are a separately authorized, separately audited read.

Outcomes by channel

Provider-specific strings remain in raw evidence; reports use normalized outcomes.

Channel fallback

Fallback is a new interaction attempt with its own contact point and compliance decision. If voice is blocked because the local time is inconvenient, that result does not prove SMS or email is allowed. A workflow can recommend the next channel only after testing its own consent, opt-out, purpose, content, and timing rules.

If no route is eligible, the case moves to a named waiting or review state with the blocking reasons. It never reports “contact attempted” when execution stopped at the gate.

Inbound protected signals

Inbound communications can change controls immediately. A cease request, bankruptcy notice, dispute, identity-theft assertion, legal-representative notice, servicemember request, or payment-authorization revocation creates structured facts and specialist work. The interaction preserves the original words or artifact, but a reviewer confirms the structured status where policy requires.

Content and evidence

Template rendering stores the template and legal-content versions, merge facts with source times, final rendered hash, and delivery artifact. Voice stores script version, recording references and access policy, transcription provenance, and redaction status. Sensitive evidence is not embedded directly in webhook payloads or broad reports.