Upload a recording or transcript

Every way a call can enter VoiceLens: dashboard upload, transcript analysis, the ingest API and provider callbacks, and what metadata to attach.

Calls enter VoiceLens through four doors. All of them end in the same place: a conversation attached to a channel, graded with that channel's rubric.

Method	Best for	Auth
Dashboard upload	Trying things out, one-off reviews	Signed-in Member or above
Transcript analysis	Calls you already transcribed with Deepgram	Signed-in Member or above
Ingest API	Production integrations from your own systems	Channel ingest token (`vk_`)
Twilio recording callback	Calls that run on Twilio	Configured in the channel

Dashboard upload

Choose Upload, pick a channel (or leave the workspace default), and drop one or more files. Accepted formats are mp3, wav, m4a, ogg/oga, webm and flac, up to 500 MB per file. Stereo recordings with one party per channel give the best speaker attribution; mono recordings are diarized automatically.

Give the call a title if you want to find it later; otherwise the file name is used.

Spoken language defaults to whatever the channel says, and you can override it for the files you are about to drop. Worth setting for a one-off recording, or for a call in a language the channel does not usually handle: automatic detection recognises fewer languages than transcription supports, and it labels the rest as the nearest language it knows rather than as unknown.

Transcript analysis

If your platform already transcribes with Deepgram, you can skip audio entirely: paste or upload the raw Deepgram JSON response under Upload, then Analyse transcript. VoiceLens grades it exactly like an uploaded recording, with two differences:

Line quality is not measured (there is no audio to measure).
Audio playback is not available on the scorecard or on shared links.

Ingest API

For production, send each call as it ends. Three variants exist, all authenticated with a channel ingest token:

Multipart upload: one POST with the file and metadata fields.
From URL: give VoiceLens an https URL and it downloads the file (up to 500 MB, five-minute timeout).
Pre-signed upload: request a short-lived upload URL, PUT the bytes to it, then confirm. Best for very large files or clients that cannot hold the file in memory.

Every variant accepts the same metadata and returns a conversation id you can correlate with webhooks later. The reference has request and response shapes for each.

Twilio recording callback

Set the channel's provider to Twilio, enter the Account SID and Auth Token, and configure https://voicelens.app/api/ingest/{channelId}/twilio/recording-status as the recording status callback for the completed event. VoiceLens verifies the X-Twilio-Signature, downloads the recording and grades it. The Twilio CallSid becomes the call's externalCallId, so repeated callbacks for the same recording are deduplicated.

Metadata worth attaching

Metadata is optional, but three fields make the analytics dramatically more useful:

Field	Why it matters
`agentId` (and `agentName`)	Powers the per-agent analytics and lets you compare bot versions or team members. Use a stable identifier such as `bot-v12` or an employee id.
`agentType`	`ai` or `human`. Lets you filter and compare the two populations.
`externalCallId`	Your carrier or CRM call id. Used to deduplicate re-sent recordings and to correlate webhook events with your own records.
`language`	A BCP-47 tag for this recording, overriding the channel's. Send it whenever the channel handles more than one language, and always for languages automatic detection cannot identify.

You can also pass callerNumber, calledNumber, calledAtUtc, a durationHintSec and up to 50 free-form custom keys (32 KB total). Custom keys are returned untouched in the API and in webhook payloads.

Idempotency

Sending the same call twice does not grade it twice. VoiceLens deduplicates on:

the Idempotency-Key header, if you send one (up to 200 characters, scoped to the channel);
the (channelId, externalCallId) pair, if externalCallId is set;
for Twilio, the RecordingSid.

A replayed request returns the original conversation with reused: true.

What happens next

The call appears in the list immediately with status Pending (or PendingUpload for the pre-signed flow), then moves through Transcribing and Analyzing to Completed. If transcription or analysis fails, the status becomes Failed with a processingError you can read in the call view, in the API and in the conversation.failed webhook.