Workflow recordings

Upload reusable audio, transcribe it, and select it in a voice workflow.

Workflow recordings are reusable audio clips for workflow prompts. They are different from a run recording, which is media produced by one execution; see Calls, runs, and results.

Add recordings in the dashboard or through the authenticated API, then select library items in the workflow editor. For API examples, set ATHENA_BASE_URL and ATHENA_API_KEY as described in the API quickstart.

Upload in the dashboard

Open Recordings → Uploaded recordings → Upload Recording. Choose an audio file up to 5 MiB, select its language or leave Multilingual (Auto-detect), and wait for transcription. Review and edit the transcript, then choose Upload 1 Recording (the count changes for multiple files).

The saved entry shows its recording ID, filename, and transcript. Use Edit ID to give the clip a useful descriptive ID. The separate TTS cache tab is distinct from your uploaded library and from recordings produced by individual runs.

The dialog also offers Record for microphone capture. Allow microphone access before using that control. File upload and automatic transcription were verified separately from microphone recording.

Prepare and transcribe a clip

Record or export an audio file before uploading it. The upload API accepts up to 20 files per request, with each file at most 5,242,880 bytes (5 MiB). The transcript is required when creating a recording. You can transcribe the file with Athena or provide and review the transcript yourself.

curl --fail-with-body "$ATHENA_BASE_URL/api/v1/workflow-recordings/transcribe" \
  -H "X-API-Key: $ATHENA_API_KEY" \
  -F "file=@welcome.wav" \
  -F "language=en"

Review the returned transcript before using it. Correct names, numbers, pronunciation, and punctuation so the transcript matches the audio. This endpoint returns transcription output; it does not add the file to the library.

Upload and create a library item

The upload uses two separate requests: first ask Athena for a short-lived storage URL, then send the file bytes directly to that URL. Creating the metadata record is a third request.

1. Request a presigned upload URL. Set file_size to the file’s actual size in bytes.

   curl --fail-with-body "$ATHENA_BASE_URL/api/v1/workflow-recordings/upload-url" \
     -H "X-API-Key: $ATHENA_API_KEY" \
     -H "Content-Type: application/json" \
     --data '{
       "files": [{
         "filename": "welcome.wav",
         "mime_type": "audio/wav",
         "file_size": 123456
       }]
     }'
   

   Copy the returned upload_url, recording_id, and storage_key. The signed URL expires after 30 minutes. Treat it as temporary access and do not log or share it.

2. Upload the exact file bytes with PUT. Keep the Content-Type consistent with the MIME type used in the URL request.

   curl --fail-with-body -X PUT "$UPLOAD_URL" \
     -H "Content-Type: audio/wav" \
     --data-binary @welcome.wav
   

3. Create the library record after the PUT succeeds. Use the short recording_id and storage_key returned in step 1. transcript is required; the TTS fields are optional in the API.

   curl --fail-with-body "$ATHENA_BASE_URL/api/v1/workflow-recordings/" \
     -H "X-API-Key: $ATHENA_API_KEY" \
     -H "Content-Type: application/json" \
     --data '{
       "recordings": [{
         "recording_id": "<SHORT_ID_FROM_UPLOAD_RESPONSE>",
         "transcript": "Welcome to Example Support.",
         "storage_key": "<STORAGE_KEY_FROM_UPLOAD_RESPONSE>",
         "tts_provider": null,
         "tts_model": null,
         "tts_voice_id": null,
         "metadata": {
           "original_filename": "welcome.wav",
           "file_size_bytes": 123456,
           "mime_type": "audio/wav",
           "language": "en"
         }
       }]
     }'
   

Replace the angle-bracket values and example transcript and file size with the values for your clip. The TTS fields are optional; if you include them, use the configuration selected for your workflow.

List and select recordings

List the active recordings available to your organization:

curl --fail-with-body "$ATHENA_BASE_URL/api/v1/workflow-recordings/" \
  -H "X-API-Key: $ATHENA_API_KEY"

The response includes a numeric id, a descriptive recording_id, the transcript, and metadata. Optional query filters include workflow_id, tts_provider, tts_model, and tts_voice_id.

In the workflow editor, select an existing recording in the relevant field:

• Edit the Start Call node and set its greeting type to Pre-recorded Audio.
• Set a transition’s speech type to Audio to play a clip before moving to the next node.
• Use a recording selector in a node property or in Settings → Voicemail & Screening.
• In prompt fields that support recording mentions, type @ and choose a library item. The editor inserts a RECORDING_ID: <id> [ transcript ] marker.

The selectors search the library ID, transcript, and filename; they also offer a preview. A selector stores the numeric database id in its workflow field, even where the field name ends in recording_id. Prompt markers instead use the descriptive recording_id string. Keep these identifier forms distinct when editing workflow JSON or calling APIs directly.

Value	Meaning	Used for
id	Immutable numeric primary key returned by the library API	Editor selections and recording_pk fields
recording_id	Organization-unique descriptive string returned by the API	RECORDING_ID: prompt markers and library rename/delete routes
Run recording URL	Media artifact for one workflow run	Previewing or downloading that run in the Runs view; it is not a library item

Rename or deactivate a recording

Rename the descriptive string by passing the numeric id in the URL:

curl --fail-with-body -X PATCH "$ATHENA_BASE_URL/api/v1/workflow-recordings/123" \
  -H "X-API-Key: $ATHENA_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"recording_id":"welcome_message"}'

The new ID may contain letters, numbers, hyphens, or underscores, up to 64 characters. The rename route updates matching RECORDING_ID: old-id markers in non-legacy workflow definitions. Numeric editor references keep pointing to the same recording.

Deactivate a library item using its descriptive recording_id string, not its numeric id:

curl --fail-with-body -X DELETE \
  "$ATHENA_BASE_URL/api/v1/workflow-recordings/welcome_message" \
  -H "X-API-Key: $ATHENA_API_KEY"

This is a soft delete: it marks the record inactive. The route does not delete the stored object or remove references from workflows. Inactive items no longer appear in active library lists and may not resolve when a workflow tries to play them. Update or remove those workflow references before deactivating a clip that is still in use.

Voicemail and screening messages

In Settings → Voicemail & Screening, the workflow editor can select a text or recording for the screening message and, when Leave a message is selected, the voicemail message. The screening message introduces the caller and waits for the person to respond; the UI offers a 1–60 second wait, defaulting to 30 seconds. Leaving the screening message empty ends screened calls. A voicemail message is played and the call then disconnects.

These settings are intended for workflows using separate speech and language models. The UI states that they do not apply to realtime speech-to-speech models. Library-audio playback in native realtime sessions has not been verified; use text greetings and messages for those models. A successful library upload does not establish playback compatibility.

The Start Call node’s Delayed Start setting controls the initial listening window for a silent answer; the default is 1.2 seconds. A brief human greeting can end the wait sooner. Delayed Start is distinct from the post-screening wait.

Manage generated speech separately

Use Recordings → TTS cache for generated MiniMax speech, rather than the Uploaded recordings library. Follow Speech caching to enable it, interpret usage counts, preview entries, and invalidate cached audio. Deleting a cache entry does not deactivate a library recording.