HCC Docs

Recording

The environment's recording policy, and the stop switch

GET /v1/recording-policy flows:read

Responses

  • 200

    Status

    Fields
    • data RecordingPolicyStatus required
      Fields
      • policy any required
      • suspendedAt string | null required

        When the workspace's stop switch was set; nothing records while it is on

      • suspendedBy string | null required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Register the recording policy

PUT /v1/recording-policy flows:write

Like PUT /v1/queues: hcc.serve reports it on startup (mode: "report" only activates a version never seen before) and hcc.recording.deploy activates it from CI. A redeploy does not clear the workspace's stop switch.

Body

  • policy object required
    Fields
    • mode "record" | "off" required
    • notice object

      Default {}.

      Fields
      • text string

        Default "This call may be recorded and transcribed.".

      • voice string
      • language string
    • retention object

      Default {}.

      Fields
      • audioDays integer

        Default 90. 1 to 3650.

      • transcriptDays integer

        Default 365. 1 to 3650.

    • transcribe false | object

      Default false.

      Fields
      object
      • language string
      • redact "pci" | "ssn"[]
  • mode "report" | "deploy"

    Default "report".

  • alsoTest boolean

    Live keys only: also register the same version in test Default false.

Responses

  • 200

    The registered version

    Fields
    • data RecordingPolicy required

      What defineRecordingPolicy declares. Off unless one is deployed.

      Fields
      • version string required
      • environment "live" | "test" required
      • definition object required
      • createdAt string required
      • activatedAt string required
      • lastSeenAt string required
    • test object

      With alsoTest: the version registered in test

      Fields
      • data RecordingPolicy required

        What defineRecordingPolicy declares. Off unless one is deployed.

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Clear the workspace's stop switch

DELETE /v1/recording-policy/suspension recording:manage

The dashboard can only stop recording. Starting it again is this deliberate call, with a live key that has the recording:manage scope, which only an owner or admin can grant. Calls already in progress stay unrecorded; new calls follow the policy.

Responses

  • 204

    Cleared

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Pause a call's recording

POST /v1/calls/{id}/recording/pause calls:write

What is said while paused is not in the file. 409 when nothing is being recorded yet.

Path

  • id string required

Responses

  • 202

    Applied

    Fields
    • data RecordingControlResult required
      Fields
      • phase string required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Resume a call's recording

POST /v1/calls/{id}/recording/resume calls:write

Picks up after a pause. 409 when nothing is being recorded.

Path

  • id string required

Responses

  • 202

    Applied

    Fields
    • data RecordingControlResult required
      Fields
      • phase string required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

A call's recordings

GET /v1/calls/{id}/recordings calls:read

Metadata only: start time, duration, channels, status and when it is deleted.

Path

  • id string required

Responses

  • 200

    Recordings

    Fields
    • data Recording[] required
      Fields
      • id string required
      • callId string required
      • status string required
      • source string required
      • channels integer | null required

        Channels in the file. Two channels do not promise one speaker per channel on calls with a rep.

      • durationSeconds integer | null required
      • startedAt string | null required
      • pauses object[] required
      • contentType string | null required
      • bytes integer | null required
      • deleteAfter string | null required
      • deletedAt string | null required
      • createdAt string required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Delete a call's recordings

DELETE /v1/calls/{id}/recordings calls:write

Stops one being made, then removes the audio from storage and from the provider, and the transcripts' text. The rows stay, saying there was a recording and when it went. The audio's removal runs in the background.

Path

  • id string required

Responses

  • 202

    Removal started

    Fields
    • data Recording[] required
      Fields
      • id string required
      • callId string required
      • status string required
      • source string required
      • channels integer | null required

        Channels in the file. Two channels do not promise one speaker per channel on calls with a rep.

      • durationSeconds integer | null required
      • startedAt string | null required
      • pauses object[] required
      • contentType string | null required
      • bytes integer | null required
      • deleteAfter string | null required
      • deletedAt string | null required
      • createdAt string required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

A call's rep transcripts

GET /v1/calls/{id}/transcripts calls:read

Without their text. AI agent conversations come as conversation.transcript.ready.

Path

  • id string required

Responses

  • 200

    Transcripts

    Fields
    • data CallTranscriptSummary[] required
      Fields
      • id string required
      • callId string required
      • recordingId string required
      • status "pending" | "processing" | "ready" | "partial" | "failed" | "deleted" required
      • failureReason "no_audio" | "provider_error" | "unsupported_audio" | "not_configured" | "billing" | "suspended" | null required
      • repIds string[] required
      • language string | null required
      • speakerSeparation "channels" | "diarized" | "none" | null required

        channels: speakers come from the file's channels, on a transcript that showed two separate voices. diarized: the provider estimated them, as unknown with a speakerTag. none: one voice, unlabeled.

      • segmentCount integer required
      • deleteAfter string | null required
      • deletedAt string | null required
      • createdAt string required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

One rep transcript, with its text

GET /v1/calls/{id}/transcripts/{transcriptId} calls:read

The transcriptId of call.transcript.ready, which carries no text itself.

Path

  • id string required
  • transcriptId string required

Responses

  • 200

    Transcript

    Fields
    • data CallTranscript required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code