Recap: full transcripts and post-call notes

Recap runs after a call ends. It keeps the speaker-labelled transcript and adds the notes people need to act on the call: a short headline, a detailed summary, decisions, action items, next steps, important moments, call signals, and structured fields. Recap is an add-on to a call transcript. It does not transcribe audio itself. Use Hear async jobs or Hear streaming to produce the transcript, then read the Recap by call_id.

Enable Recap

You need recap:configure to change the organization setting and recap:read to list or read results. A sandbox key includes both and mints with Recap already enabled.

curl -X PUT https://api.pyai.com/v1/recap/config \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "default_pack_id": "sales_outbound"
  }'

Create a Recap from an async transcription job

Add a stable call_id to the job. The other Recap fields are optional. language controls the language of the notes, not speech recognition. Hear transcription remains English-only.

curl -X POST https://api.pyai.com/v1/transcription/jobs \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: call-481-transcription" \
  -d '{
    "audio_url": "https://recordings.example.com/call-481.wav",
    "channel": true,
    "call_id": "call_481",
    "call_direction": "outbound",
    "customer_name": "Acme",
    "pack_id": "sales_outbound"
  }'

When transcription completes, PyAI sends the complete segment list to Recap. The Recap record moves through pending, processing, and complete, or failed if processing cannot finish.

Create a Recap from Hear streaming

For a Recap-enabled organization, the streaming adapter submits committed utterances when the socket closes. Pass a stable call_id so the result can be joined to your own call record:

wss://api.pyai.com/v1/audio/transcriptions/stream
  ?protocol=pyai-hear-v1
  &call_id=call_481
  &pack_id=sales_outbound
  &call_direction=inbound

Keep sending audio frames through pauses so turn detection can observe silence. Only committed utterances become part of the retained transcript.

Submit an existing transcript

If you already have speaker-labelled utterances, trigger Recap directly:

curl -X POST https://api.pyai.com/v1/recap/calls/call_481 \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "call_direction": "outbound",
    "customer_name": "Acme",
    "utterances": [
      {
        "speaker_role": "agent",
        "text": "I will send the pricing sheet today.",
        "offset_s": 12.4,
        "duration_s": 3.1
      },
      {
        "speaker_role": "customer",
        "text": "Please include the annual option.",
        "offset_s": 16.1,
        "duration_s": 2.3
      }
    ]
  }'

Read the call detail

curl https://api.pyai.com/v1/recap/calls/call_481 \
  -H "Authorization: Bearer $PYAI_API_KEY"

A completed response includes two separate artifacts:

transcript: the full retained utterance list with speaker roles and timing.
record: typed intelligence (recap.record.v1). tldr is the one-line headline; summary is the detailed notes. action_items, next_steps, talk_ratio, signals, and fields are always present (null or empty when unknown).

{
  "object": "recap.call",
  "call_id": "call_481",
  "status": "complete",
  "headline": "Acme requested annual pricing and agreed to review it this week.",
  "transcript": {
    "format": "utterances.v1",
    "utterances": [
      {
        "speaker_role": "agent",
        "text": "I will send the pricing sheet today.",
        "offset_s": 12.4,
        "duration_s": 3.1
      }
    ]
  },
  "record": {
    "format": "recap.record.v1",
    "tldr": "Acme requested annual pricing and agreed to review it this week.",
    "summary": "The call focused on pricing structure and the next review step.",
    "action_items": [
      {
        "owner": "agent",
        "task": "Send annual pricing",
        "due": "today"
      }
    ],
    "disposition": null,
    "next_steps": "Email the annual option.",
    "talk_ratio": { "agent": 0.55, "customer": 0.45 },
    "signals": [],
    "fields": {}
  }
}

Review in the console

The Recap call view keeps processing and failed calls visible. A completed call has separate Summary, Insights, Transcript, and Ops views. The Transcript view contains every retained utterance and can be copied with timestamps. Recap rows, including their transcript and generated intelligence, are retained for 90 days. Input audio follows the retention policy of the Hear surface that created the transcript. See Security and data handling.

Troubleshooting

Symptom	What to check
Call remains `pending`	Confirm Recap is enabled and retry the source job or transcript submission.
Only a one-line headline appears	Read `record.summary` or `record.summary_draft`; `tldr` is intentionally brief.
Transcript is missing	The record predates transcript retention or the trigger did not contain committed utterances.
Speaker roles are wrong	Use `channel: true` for stereo recordings or `diarize: true` for mono recordings.
Summary language is wrong	Set the job or manual-trigger `language`; it changes Recap output only.

Get started

Omni

Guides

Frameworks

Integrations

Use cases

Reference

Recap: full transcripts and post-call notes

Enable Recap

Create a Recap from an async transcription job

Create a Recap from Hear streaming

Submit an existing transcript

Read the call detail

Review in the console

Troubleshooting

​Enable Recap

​Create a Recap from an async transcription job

​Create a Recap from Hear streaming

​Submit an existing transcript

​Read the call detail

​Review in the console

​Troubleshooting

Enable Recap

Create a Recap from an async transcription job

Create a Recap from Hear streaming

Submit an existing transcript

Read the call detail

Review in the console

Troubleshooting