Documentation

Transcription webhooks

When a recording is transcribed, Ruut Voice notifies your transcribeCallback URL with the transcript — including speaker-labeled segments when diarization was used.

Configure

Enable transcription with <Record transcribe="true" transcribeCallback="…">, or via the account's default STT provider:

TwiMLxml

Payload

Parameter	Type	Description
`TranscriptionSid` optional	`string`	Unique identifier for the transcription.
`TranscriptionStatus` optional	`string`	`completed` or `failed`.
`TranscriptionText` optional	`string`	The full transcript text (newline-separated per segment).
`TranscriptionSegments` optional	`string`	JSON array of speaker-labeled segments (when diarized).
`TranscriptionUrl` optional	`string`	URL of the transcription resource.
`RecordingSid` optional	`string`	The recording that was transcribed.
`RecordingUrl` optional	`string`	URL of the source recording.
`CallSid` optional	`string`	The call that was recorded.
`AccountSid` optional	`string`	Your account SID.
`From` optional	`string`	Caller ID.
`To` optional	`string`	Destination.
`CallStatus` optional	`string`	Call status at transcription time.
`Direction` optional	`string`	Call direction.

Speaker segments

TranscriptionSegments is a JSON array:

Responsejson


[
  {
    "speaker": "customer",
    "text": "Hello, I'd like to open an account.",
    "start_time": 0.0,
    "end_time": 3.2
  },
  {
    "speaker": "agent",
    "text": "Of course, let me help you with that.",
    "start_time": 3.4,
    "end_time": 6.1
  }
]

Speakers are agent / customer for dual-channel recordings (deterministic), or SPEAKER_00/01 for mono diarization.

Handle it with the SDK

Examplets


import { isTranscriptionWebhook, parseTranscriptionSegments } from "@ruut/voice-sdk";

const payload = parseWebhook(req.body);
if (!isTranscriptionWebhook(payload)) return;

console.log(payload.TranscriptionStatus);       // "completed"
const segments = parseTranscriptionSegments(payload);
for (const seg of segments) {
  console.log(`${seg.speaker}: ${seg.text} (${seg.start_time}–${seg.end_time}s)`);
}

Failed transcriptions

If transcription fails, TranscriptionStatus is failed and no segments are included. Check the platform logs or retry by re-running the recording's transcription.

See Record & transcribe calls for the full workflow.