> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Auto-chapters for call and video recordings

> Enable the org-wide Auto-chapters toggle, navigate chapters in recording playback, react to the recording.chapters.ready webhook, and read chapter themes in analytics.

# Auto-chapters for call and video recordings

When Auto-chapters is enabled for your organization, each transcribed call or video recording is split into titled chapters after the recording finishes. Chapters show up in the recording player as a clickable sidebar, and the themes that recur across your recordings feed the **Chapter insights** card on **Voice → Video → Sessions**.

This guide covers enabling the feature, using chapters in playback, reacting to chapters programmatically, reading chapter analytics, and the cost, privacy, and limit behaviour you should plan for.

## What chapters give you

Once a recording has chapters, the recording player in the dashboard renders:

* **A chapter sidebar** next to the player. Each entry carries the chapter's title and a one-line summary of what was discussed in that span.
* **Click-to-seek.** Clicking a chapter jumps playback to that chapter's start.
* **On-video chevrons** that step forward and back through chapter boundaries without leaving the player.

Call recordings and finished video recordings use the same playback surface, so a reviewer gets the same chapter navigation on a support call and on a recorded video session. Finished video recordings are chaptered once their transcript is ready, exactly like calls.

Chapters also roll up into the **Chapter insights** card on **Voice → Video → Sessions**, which ranks the themes that recur across your recent recordings, how often each appears, and how long it typically runs. Reading that card and the API behind it is covered in [Video engagement analytics](https://docs.orbit.devotel.io/guides/video-engagement-analytics.md).

## Enable auto-chapters for your organization

Auto-chapters is an organization-level opt-in. It is **off by default**, and only owners and admins can change it.

1. Go to **Settings → Voice**.
2. Open the **Auto-chapters** card.
3. Turn on **Generate chapters for new call and video recordings** and click **Save**.

The toggle writes `auto_chaptering.enabled` under the organization's voice settings:

```json theme={null}
{
  "voice": {
    "auto_chaptering": {
      "enabled": true
    }
  }
}
```

Chaptering applies from the moment you save: recordings made before that point are left as they are, and every new call or video recording is chaptered after its transcript completes. Turning the toggle off stops chaptering for new recordings; chapters that already exist remain on their recordings.

## Video recordings use the same toggle

There is no second switch for video. The same **Auto-chapters** toggle that covers call recordings also covers finished video recordings: once a video session's recording has been transcribed, it goes through the same chaptering pass, the same sidebar renders in playback, and the same **Chapter insights** card picks up its themes.

If you enabled Auto-chapters before video recordings were covered, you do not need to do anything again. New video recordings are chaptered as soon as they are transcribed; video recordings made before the toggle was on are not chaptered retroactively.

## React to chapters programmatically

When a recording finishes chaptering, Orbit emits the `recording.chapters.ready` webhook. It fires for call recordings and for video recordings, and the payload identifies which surface the recording belongs to:

```json theme={null}
{
  "type": "recording.chapters.ready",
  "data": {
    "call_id": "call_abc123",
    "recording_id": "rec_01J8ZC3NPA",
    "chapter_count": 5,
    "ready_at": "2026-03-08T12:10:00Z"
  }
}
```

The payload carries either `call_id` (call recordings) or `video_room_session_id` (video sessions) as the surface key, plus `recording_id` so you can tie the event to the exact recording in the session, and `chapter_count` so you can skip recordings that came back with no chapters. The full event reference lives in [Webhook events](https://docs.orbit.devotel.io/reference/webhook-events.md).

A minimal handler that queues follow-up work per recording:

```javascript theme={null}
app.post("/webhooks/orbit", (req, res) => {
  const { type, data } = req.body;
  if (type === "recording.chapters.ready" && data.chapter_count > 0) {
    queueChapterReview({
      recordingId: data.recording_id,
      chapters: data.chapter_count,
    });
  }
  res.sendStatus(200);
});
```

The recording's metadata carries the chapter array itself: each chapter is `{ start_ms, end_ms, title, summary }`. Use `start_ms` to build your own chapter navigation or to reference a moment in the recording from a ticket, a CRM note, or a QA scorecard. The recordings API reference documents the metadata read alongside share links and transcripts.

### Referencing a chapter in a shared recording

The public share player is a plain player that opens at the start of the recording; it does not render the chapter sidebar. To hand someone a specific moment:

1. Mint a share link for the recording as described in [Share a recording with the public player](https://docs.orbit.devotel.io/guides/video-recording-share-player.md).
2. Send the chapter title and its start time (from `start_ms`) with the link so the recipient can jump to it on the player timeline.

Recipients who have a dashboard seat get the full experience instead: opening the call or the video session in the dashboard shows the chapter sidebar with click-to-seek.

## Feed chapter analytics

Chapter themes aggregate into the chapter-analytics read:

```bash theme={null}
GET /api/v1/video/recordings/chapter-analytics?from=2026-08-01T00:00:00Z&to=2026-09-01T00:00:00Z
```

Each row is `{ theme, occurrence_count, avg_duration_ms, recordings_count }`: a normalised chapter title, how many chapters carry it, their average length, and how many distinct recordings contained it, most-frequent first. The window defaults to the last 30 days. The response also includes a `status` object — `auto_chapters_enabled`, `recordings_total`, `recordings_processing`, `recordings_unavailable`, and `recordings_chaptered` — so a consumer can tell an honest empty result from a switched-off pipeline.

How to read themes against the rest of the engagement feed (which topics are trends, which are one-offs, how chapter analytics pairs with session-level metrics) is covered in [Video engagement analytics, section 4](https://docs.orbit.devotel.io/guides/video-engagement-analytics.md).

## Cost and privacy

Chaptering is a post-recording AI pass: after a recording finishes and its transcript is ready, the transcript window is sent to a third-party AI processor that returns the chapter titles and summaries. Two consequences to plan for:

* **Cost.** Each chaptered recording consumes AI usage for your workspace, billed like your other AI features. Off-by-default means you only pay for it once you have decided the navigation and theme analytics are worth it.
* **Privacy.** Personal data such as phone numbers, email addresses, and card numbers is redacted from the transcript before it leaves your tenant, unless you have turned off LLM redaction in your privacy settings. The Auto-chapters card in **Settings → Voice** carries the same notice, so the person enabling it sees what leaves the workspace.

Chaptering also depends on the recording still existing when the pass runs. If your retention policy deletes a recording before its transcript completes, that recording stays unchaptered. Review your retention window in [Operate the post-call recordings pipeline](https://docs.orbit.devotel.io/guides/recording-lifecycle-operations.md) if you keep short windows.

## Limits

* **Not retroactive.** Recordings made before you enable Auto-chapters are never chaptered. There is no backfill for legacy recordings.
* **Transcript required.** A recording whose transcript is still processing, was skipped, or failed is not chaptered. The Sessions card reports these as pending or unavailable rather than silently omitting them.
* **Very short recordings may have no chapters.** Short recordings can come back with an empty chapter array; the player then hides the sidebar and the webhook reports `chapter_count: 0`.
* **Chapter insights empty states.** When the card has nothing to rank, it tells you which of four cases you are in: Auto-chapters are off (with a link to the setting), chapters are still being generated (with a pending count), chapters could not be generated (recordings waiting more than six hours or failed), or no chapter themes yet (on, nothing pending).

## See also

* [Share a recording with the public player](https://docs.orbit.devotel.io/guides/video-recording-share-player.md) — mint and revoke public playback links for finished video recordings.
* [Video engagement analytics](https://docs.orbit.devotel.io/guides/video-engagement-analytics.md) — session-level engagement plus chapter analytics across recordings.
* [Webhook events](https://docs.orbit.devotel.io/reference/webhook-events.md) — the `recording.chapters.ready` payload reference.
* [Operate the post-call recordings pipeline](https://docs.orbit.devotel.io/guides/recording-lifecycle-operations.md) — retention, legal holds, and transcript controls.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.