Attach audio or add metadata to a conversation
Attach an audio recording, or add metadata keys, to a conversation previously
submitted via POST /v1/conversations:submit.
When to attach audio
Use this endpoint when your recording URL is not available at the moment
the call ends (for example, Twilio Programmable Voice recordings that are
only fetchable after an asynchronous job completes ~60 seconds later).
Submit the transcript immediately at call end to get a conversation_id
for trace correlation, then PATCH the audio when the recording URL is
ready. Attaching audio triggers audio-dependent metrics as a second wave.
When to add metadata
Use this endpoint when a value you want to filter or segment on is only
known after the call was submitted (for example, an outcome produced by
post-call analysis). Once added, the key is immediately available as a
filter on the Conversations page and in the filter parameter of
GET /v1/conversations.
Two-wave metric timing
- Text-only metrics fire immediately after
POST /v1/conversations:submitand deliver their results via your configured webhook. - Audio-dependent metrics fire after an audio PATCH and deliver a separate, later webhook. Configure your consumer to expect both waves.
Adding metadata does not run or re-run any metric. If a metric depends
on a key you added, rerun it with POST /v1/simulations:rerunMetrics.
One-shot
Both patch targets are write-once. Audio can be attached only once per
conversation; a second PATCH on a conversation that already has audio
returns 409 ALREADY_EXISTS. Metadata is additive only; patching a key
that already has a value returns 409 ALREADY_EXISTS.
Body
Exactly one of audio, audio_url or metadata is required.
Authorizations
API key for authentication.
Path Parameters
Unique conversation identifier (22-26 characters)
22 - 26Body
Request to attach audio to, or add metadata to, an already-submitted conversation.
Exactly one of audio_url, audio or metadata must be provided.
Submitting more than one, or none, returns 400 INVALID_ARGUMENT. Audio
and metadata are patched in separate calls so a rejected metadata key can
never leave audio half-attached.
Idempotency: Audio can be attached only once per conversation. A
second PATCH on a conversation that already has audio returns
409 ALREADY_EXISTS. Conversations that were submitted with audio via
POST /v1/conversations:submit already have audio attached and cannot
be PATCHed. Metadata follows the same rule per key: adding a new key
succeeds, overwriting an existing one returns 409 ALREADY_EXISTS.
Presigned URL to the audio recording. Same validation rules as
audio_url on POST /v1/conversations:submit (WAV or MP3, 5 s to
60 min, 200 MB max). Supports AWS S3, GCP Cloud Storage, Azure Blob
Storage, or any public/presigned HTTPS URL. The s3://bucket/key
protocol form is also accepted.
"https://recordings.s3.amazonaws.com/calls/2025/11/call-4k2m9p.wav?X-Amz-Algorithm=..."
Base64-encoded audio bytes. Same format and size limits as audio_url.
Prefer audio_url for anything other than very small clips.
Metadata keys to add to the conversation, merged into any metadata sent at submit. Values may be strings, numbers, booleans, arrays or objects.
Additive only. A key that already holds a value returns
409 ALREADY_EXISTS, and keys that identify the conversation
(conversation_id, external_conversation_id, call_id, trace_id,
langfuse_trace_id, observation_id, langfuse_observation_id,
project_id, environment, occurred_at) return
400 INVALID_ARGUMENT.
At most 100 keys per request; key names are limited to 200 characters.
Response
Audio attached successfully; audio metrics queued
Conversation resource object.