WHwhispa
calls

Retry Finalization

Retry finalization for a call, re-running AI jobs.

post/calls/{call_id}/retry

Request

  • Base URL
    https://dev.whispa.net (the document declares no server; this is the origin it was published from)
  • Auth
    • OAuth 2
      Password
      Token URL: auth/bearer/login
    • or API key in cookie access_token

Path parameters

call_idstring uuid required

Response

Successful Response

idstring uuid required
user_idstring uuid nullable required
team_idstring uuid nullable

Team snapshot for this call

user_emailstring nullable

Email of the agent who took the call

user_display_namestring nullable

Display name of the agent who took the call

call_mode'training' | 'production' | 'ai_agent'

Call mode enumeration.

call_source'live' | 'uploaded'

Call source enumeration.

scenariostring nullable required
agent_idstring nullable required
extensionstring nullable

Phone extension that handled the call

called_numberstring nullable

Inbound destination number reported by the provider, when available

telephony_call_idstring nullable

External telephony system call ID

provider_call_refobject nullable

Provider-native call reference (e.g. TCN call_sid/call_type, AWS Connect contact_id) when the provider hosts the call recording. Only some providers support minting a link via /calls/{call_id}/provider-recording-url (TCN today; the endpoint returns 404 for others). For awsconnect this is the stored reference plus instance_alias resolved from the current Connect integration config, which together address the Connect console's contact page — so the alias is whatever is configured now, not whatever was configured when the call happened

suspensionsobject[]

Park windows during the call (TCN payment-line transfers): [{suspended_at, resumed_at}] ISO timestamps; resumed_at is null when the call never resumed (grace expired)

timelineobject[]

Typed call lifecycle events in order: {type, at, detail?, source}. Types: ringing, connected, hold_start, hold_end, consult_start, consult_end, call_suspended, call_resumed, call_ended. Rendered as transcript markers and fed to the summary/coaching/QA prompts

customer_numberstring nullable

Phone number of the caller/customer

customer_namestring nullable

Name of the caller/customer if available

ring_duration_secondsnumber nullable

Time spent ringing before call was answered (seconds)

call_direction'incoming' | 'outgoing' | 'internal'

Direction of the call.

  • INCOMING: Customer called agent
  • OUTGOING: Agent called customer
  • INTERNAL: Extension-to-extension call
audio_chunks_receivedinteger nullable

Number of audio chunks received (0 = no audio captured)

audio_file_pathstring nullable

S3 path to the call recording, when one is archived

started_atstring date-time required
ended_atstring date-time nullable required
duration_secondsinteger nullable required
is_starredboolean

Whether this call has been saved for later review

transcriptobject[]

Transcript entries (populated from call_transcript_chunks table)

tool_eventsobject[]

Terminal tool-call events from the autonomous voice agent (persisted tool_call session events), in call order. Payload shape matches the SSE tool_call channel; interleaved into the transcript view behind a toggle.

summary_markdownstring nullable required
summaryobject nullable

Structured call summary (new format)

coachingobject nullable required
qa_scoreinteger nullable

Overall QA scorecard score (mirror of analyzer_artifacts['qa_scorecard']['overall_score']).

clientstring nullable

End-client the call collected for, classified against the scenario's configured client list ('Other' for an explicitly named unconfigured creditor; 'Unclear' for insufficient or ambiguous context; null when no classification result was produced). Full result with disposition, confidence, and evidence in analyzer_artifacts['client_classification'].

client_idstring uuid nullable

Stable client identity for the display-name snapshot

tts_voice_idstring nullable

Provider-qualified voice the autonomous agent spoke with, stamped at dispatch from the resolved fallback chain — not re-derived from the scenario, which may have been re-voiced since. Null on human calls. Resolve the display name against the voice catalog (GET /ai-calls/voices).

tts_model_idstring nullable

Provider-qualified TTS model the autonomous agent used, stamped at dispatch rather than re-derived from mutable scenario config.

analyzer_artifactsobject required
post_call_notesstring nullable required
status'ongoing' | 'completed' | 'unanswered' | 'error'

Call lifecycle state.

  • ONGOING: Call is currently in progress
  • COMPLETED: Call finished (regardless of whether it was answered)
  • ERROR: Technical error/exception during call processing
  • UNANSWERED: DEPRECATED - Use status=COMPLETED + telephony_result=NO_ANSWER instead. Kept for backwards compatibility with existing database records.
telephony_result'connected' | 'busy' | 'no_answer' | 'rejected' | 'failed'

Telephony-level call connection result.

Represents what happened at the telephony level before any conversation. This is typically provided by the PBX/telephony system, not AI-classified.

answered_by'human' | 'voicemail' | 'unclear'

Who answered the call (AI-classified from transcript).

This is the first stage of call classification - determining whether a human or voicemail answered the call.

conversation_outcome'engaged' | 'refused' | 'wrong_person' | 'other'

AI-classified judgement of what kind of conversation occurred.

Only applicable when answered_by=HUMAN. Runtime actions such as scheduling a callback or transferring the caller are recorded independently in WorkflowDisposition and must never overwrite this judgement.

workflow_disposition'none' | 'callback_scheduled' | 'transferred' | 'human_followup_required' | 'do_not_contact'

Deterministic action the autonomous workflow took before finalizing.

NONE is explicit for finalized autonomous calls with no special handoff/follow-up action. NULL means the dimension does not apply (human copilot, uploaded, or legacy calls), rather than overloading NULL with two meanings.

agent_end_reason'conversation_complete' | 'existing_arrangement_claimed' | 'customer_requested_human' | 'identity_verification_failed' | 'customer_declined_to_engage' | 'customer_unavailable' | 'wrong_person' | 'do_not_contact' | 'hardship_detected' | 'dispute_raised' | 'escalation' | 'voicemail' | 'no_answer' | 'caller_hung_up' | 'caller_abandoned' | 'answer_failed' | 'answer_timeout' | 'dial_failed' | 'transfer_failed' | 'screening_timeout' | 'idle_timeout' | 'max_duration' | 'api_hangup' | 'error' | 'other'

Normalized reason an autonomous call ended.

The raw runtime string remains in analyzer_artifacts for diagnostics. This enum is the stable operational projection: semantic reasons exposed to the voice model plus bounded technical termination categories. Novel runtime endings degrade to OTHER instead of failing finalization.

classification_finalboolean

Whether the call's terminal classification has been published (outcome_ready_at is set). The exact precondition for correcting answered_by / conversation_outcome — a call can be 'completed' while post-call facts are still finalizing, so clients must gate the correction UI on this rather than on status.

detected_scenariostring nullable

AI-detected scenario from transcript content

idv_outcome'verified' | 'partial' | 'incomplete'

Identity-verification outcome for a call, denormalized from the IDV analyzer.

Only set when IDV was required and a verdict was produced. A NULL column can mean IDV was not applicable, is still pending, or no verdict was available; API consumers use idv_required plus call status to distinguish those states. Derived from the terminal identity_verification_state["status"]:

  • VERIFIED: status complete — identity confirmed per the scenario's policy.
  • PARTIAL: at least one identity factor was confirmed, but the scenario's completion rule was never satisfied.
  • INCOMPLETE: required, and not a single factor was confirmed.

PARTIAL exists because "not verified" covers two operationally different calls: one where the customer engaged with verification and it ran out of road, and one where it never started. Only the second is a candidate for "the agent didn't try". Note this is tracking state, not an adherence grade — the leadership IDV rate deliberately reads the reviewed QA scorecard instead (see shared.idv), because a human reviewer can correct it and the analyzer cannot.

There is deliberately no skipped outcome. The live state machine still has a skipped terminal so the analyzer stops firing on a call that is not going to verify, but as a result it said nothing true that incomplete doesn't: verification was required and did not happen. It also read as a third, ambiguous colour on any report — neither pass nor fail — while the thing a reviewer actually needs to know (was skipping appropriate here?) is a transcript judgement the tracker never made.

idv_source'live' | 'post_call' | 'inherited'

Which mechanism produced the call's persisted IDV state.

  • LIVE: the in-call IDV analyzer's terminal state (the normal path).
  • POST_CALL: the post-call IDV judge — runs when the live analyzer never produced a state (e.g. no scenario reached the session) or the scenario was reclassified after the call, judging the full transcript against the resolved scenario's IDV rules.
  • INHERITED: the origin leg of a transfer verified the customer, and this recipient leg inherits that verdict — verification travels with the conversation, not the leg (see calls.idv_resolution). The verification exchange is on the origin leg's transcript, not this one's.
idv_requiredboolean nullable

Whether the call's resolved scenario requires identity verification. NULL when the scenario record is unavailable.

recording_disclosedboolean nullable

True when the IDV tracker positively captured the recording disclosure; otherwise NULL.

scenario_idstring uuid nullable

FK to configured scenario

was_transferredboolean

Whether this call was transferred to/from another call

transferred_from_call_idstring uuid nullable

If transferred, the call session this was transferred FROM

transferred_to_call_idstring uuid nullable

If transferred, the call session this was transferred TO

dashboard_open_percentagenumber nullable

Percentage of call duration with dashboard open (0-100)

created_atstring date-time required
updated_atstring date-time required

Changes

No recorded changes to this operation across all 1 revision of this API.