transcribe

Record the call in the background and transcribe the recording after it stops. Recording starts when this instruction runs, so audio from earlier in the call isn’t included, and continues until you stop it with transcribe_stop or the call ends. Execution continues to the next instruction while the call proceeds.

Transcription runs after recording stops and completes asynchronously, so the transcript can arrive some time after the call ends. The recording is transcribed as U.S. English (en-US); there is no option to choose another language.

For real-time transcription delivered as the call happens, use live_transcribe instead. The transcribe calls guide compares the two.

Only one transcription can be active on a call at a time. Starting another while one is already running will fail.

Properties

objectRequired

An object that accepts the following properties.

transcribe.status_url

string

An HTTP or HTTPS URL that receives status callbacks for this transcription: recording events when recording starts and finishes, the transcript result, and possibly an error event if the transcription fails to start. Also accepts a SWML variable reference that resolves to an HTTP or HTTPS URL. Learn more about status callbacks.

Variables

transcribe_result

success | failed

Whether transcription started successfully.

transcribe_control_id

string

Identifier assigned to this transcription. transcribe_stop uses it to stop the right one.

StatusCallbacks

Status callbacks are advisory

Status callbacks are asynchronous, best-effort HTTP notifications: delivery can be delayed or fail silently — if your server is unreachable, the callback simply never arrives. Don’t gate time-critical or business-critical actions solely on receiving one. Confirm state via the REST API before acting, or use a transport with visible failure modes — see Status callback reliability.

When you set status_url, SignalWire POSTs several kinds of events to it. Check event_type to tell them apart:

calling.call.transcribe reports the recording behind the transcription. params.state is transcribing when recording starts and finished when it stops. A finished recording event doesn’t mean the transcript is ready.
calling.transcript.completed or calling.transcript.failed reports the transcript result, sent after recording finishes and the audio has been processed.
calling.error can be sent instead of the other events if the request to start transcription fails, with the error details in params.error.

Recording events

Each calling.call.transcribe event carries the standard event fields (event_type, event_channel, timestamp, project_id, space_id) and these fields in params:

params.call_id

string

The call ID.

params.node_id

string

The node handling the call.

params.segment_id

string

The segment ID for the call leg. Present when available.

params.tag

string

The tag associated with the call. Present when set.

params.control_id

string

The control ID of this transcription, the same value stored in transcribe_control_id.

params.state

string

The recording state. Valid values: transcribing, finished.

params.url

string

URL of the recording being transcribed. Present when available.

params.recording_id

string

ID of the recording being transcribed. Present when available.

params.status_url

string

The status_url this event was sent to.

params.size

integer

Recording file size in bytes. Present when state is finished.

params.duration

integer

Recording duration in seconds. Present when state is finished.

params.start_time

number

Unix timestamp (float) when the recording started. Present when state is finished and the time is known.

params.end_time

number

Unix timestamp (float) when the recording ended. Present when state is finished and the time is known.

Transcript events

calling.transcript.completed includes the transcribed text when speech was captured; calling.transcript.failed means the recording could not be transcribed.

Payload

{
  "event_type": "calling.transcript.completed",
  "timestamp": 1777565701.5623918,
  "project_id": "4d0d6f16-5881-4fcc-92a4-02c51a91954d",
  "space_id": "451ed9ff-e568-4222-8af9-4f9ab7428d09",
  "params": {
    "id": "0ec5a4da-46b9-4d2c-b724-151add8d4d08",
    "call_id": "2e1e66e5-5d07-413d-9668-55542992eec0",
    "segment_id": "2e1e66e5-5d07-413d-9668-55542992eec0"
  }
}

See the Transcript status callback webhook page for the full field reference.

Example

version: 1.0.0
sections:
  main:
    - transcribe:
        status_url: https://example.com/transcribe-status