Una trascrizione distingue le voci ma non può sapere quale sia quella dell'operatore. Salva ogni operatore una volta, da una sua chiamata, e ogni chiamata successiva torna con l'operatore indicato per nome, un riassunto in cima e un foglio di calcolo pronto per il controllo qualità.
Un responsabile qualità che controlla le chiamate dell'assistenza ascoltandole ne smaltisce una manciata al giorno, e una chiamata di sette minuti dura sette minuti per quanto velocemente tu clicchi. Letta come testo, la stessa chiamata è di circa mille parole, una pagina, e una pagina si può scorrere, cercare e incollare in un ticket. La trascrizione delle chiamate del servizio clienti trasforma in pagine di questo tipo le registrazioni che il tuo sistema telefonico già conserva. Tre cose decidono se quelle pagine servono a qualcosa: se ogni riga dice chi ha parlato, operatore o cliente; se la chiamata arriva con un breve riassunto di ciò che è stato chiesto e di ciò che è stato concordato; e se il risultato finisce dove lavora il team, in una nota del CRM o in un foglio di calcolo per il controllo qualità.
Questo articolo percorre quel flusso di lavoro con VocalStack: chiamate registrate inviate tramite l'API, l'operatore riconosciuto per nome, un riassunto scritto per ogni chiamata ed esportazioni in JSON ed Excel. Dice anche con chiarezza che cosa VocalStack non fa per un team di assistenza, perché alcune cose contano prima ancora di caricare la prima chiamata.
La maggior parte dei sistemi telefonici e dei contact center può esportare le registrazioni delle chiamate come file audio, o dare per ciascuna un link di download. Va bene l'uno o l'altro. POST /v1/transcriptions accetta un file come caricamento multipart, oppure un corpo JSON con un url che il server scarica da sé. Il tutorial sui file descrive la chiamata nel dettaglio; per le chiamate telefoniche contano queste impostazioni, tutte dentro settings:
speakerLabels: impostalo su on, così ogni riga di una chiamata a due porta un parlante. L'impostazione predefinita, When Needed (auto), etichetta le righe solo quando si sente un secondo parlante, il che si adatta a una conferenza più che a una chiamata.summary e title: entrambi sono disattivati se non li richiedi. Con entrambi attivi, una volta trascritta la chiamata vengono scritti un titolo e un breve riassunto.spokenLanguage: indicala quando la conosci, come in una coda che accetta chiamate in una sola lingua. Se la ometti, la lingua viene rilevata tra 100.Il caricamento risponde subito con un id di trascrizione; le parole arrivano poco dopo. Invia un Idempotency-Key con ogni caricamento: un nuovo tentativo con la stessa chiave e lo stesso corpo entro 24 ore restituisce la prima trascrizione invece di crearne, e fatturarne, una seconda. L'id della chiamata nel tuo sistema telefonico è una chiave naturale.
import { VocalStack } from '@vocalstack/js-sdk';
const vs = new VocalStack({ baseUrl: '{{api}}', apiKey: process.env.VOCALSTACK_API_KEY });
const tx = await vs.transcriptions.create(
{
file: './calls/48213.mp3',
name: 'Ticket 48213',
settings: { speakerLabels: 'on', summary: true, title: true },
},
{ idempotencyKey: 'call-48213' },
);
const job = await vs.transcriptions.waitForJob(tx.id, { intervalMs: 5000 });
if (job.state !== 'done') throw new Error(`call 48213: ${job.state} ${job.error ?? ''}`);
Le registrazioni di una notte possono partire in un unico ciclo. Ogni piano stabilisce quante trascrizioni girano contemporaneamente, e un file oltre quel numero non viene rifiutato: viene creato, resta in attesa in stato queued e parte da solo quando una precedente finisce. Il limite che puoi incontrare è il numero di trascrizioni che un account può avviare tramite l'API in un'ora; le cifre per ogni piano sono nella pagina dei prezzi. Non ci sono webhook, quindi il tuo script interroga ogni job finché non è completato, cosa che waitForJob fa per te.
Le etichette dei parlanti derivano dalla diarizzazione: la registrazione viene divisa in turni, e i turni vengono raggruppati per voce. Quello che torna è «Speaker 1» e «Speaker 2». Il sistema sa distinguere due voci, ma nulla nell'audio dice quale delle due sia di un tuo dipendente. Diarizzazione e riconoscimento vocale spiega il meccanismo; per le chiamate di assistenza, la risposta pratica è salvare ogni operatore una volta.
Un parlante salvato è un'impronta vocale con un nome. Una volta che esiste, ogni nuova trascrizione dell'account confronta le voci che sente con i tuoi parlanti salvati, e una corrispondenza porta il nome nella trascrizione. I file vengono abbinati in automatico, quindi le righe dell'operatore arrivano come «Dana» invece di «Speaker 1». Il cliente resta numerato finché non gli dai un nome.
Prendi l'impronta da una delle chiamate dell'operatore piuttosto che da una registrazione fatta alla scrivania. Una voce con le cuffie in una stanza silenziosa e la stessa voce su una linea telefonica possono suonare, per una macchina, meno simili di due persone diverse registrate nello stesso modo, e l'impronta corrisponde meglio a un audio simile a quello da cui proviene. POST /v1/speakers/from-appearance salva un parlante direttamente da una trascrizione, usando come campione i tratti della chiamata in cui parla lui. appearance è l'indice speaker che portano le sue righe.
await vs.speakers.createFromAppearance({ transcriptionId: tx.id, appearance: 0, name: 'Dana (Billing)' });
Salvare un parlante in questo modo conserva solo la sua impronta, da almeno 5 secondi del suo parlato; una chiamata in cui l'operatore parla per un minuto o più ne dà una più stabile. La clonazione della voce è un passo separato che richiede il consenso della persona, e un flusso di assistenza non ne ha alcun bisogno.
Da quel momento, la trascrizione di una chiamata conclusa ti dice chi è stato riconosciuto. GET /v1/transcriptions/{id}/transcript elenca gli speakers, e un parlante abbinato a uno salvato ha identified: true e il nome salvato. Gli altri si possono nominare con una chiamata ciascuno, PUT /v1/transcriptions/{id}/appearances/{number}, dove number è il numero con cui il parlante viene mostrato. Il nome viene memorizzato sulla trascrizione, quindi ogni esportazione successiva riporta «Customer» al posto di un numero.
const { speakers } = await vs.transcriptions.transcript(tx.id);
for (const s of speakers) {
if (!s.identified && s.number != null) await vs.transcriptions.nameAppearance(tx.id, s.number, 'Customer');
}
Considera «chiunque non sia riconosciuto è il cliente» una regola empirica, e verificala sulle tue chiamate. Un trasferimento porta un secondo operatore, un messaggio registrato del menu può essere sentito come una voce a sé, e un operatore non ancora salvato è identico a un cliente. Nota anche come è limitato il confronto: ogni trascrizione viene confrontata con i 64 parlanti salvati aggiornati più di recente nell'account, quindi un team più grande non dovrebbe contare sul riconoscimento di ogni operatore a ogni chiamata.
Due proprietà dell'audio telefonico vanno conosciute prima di giudicare le etichette. Una registrazione a due canali, con l'operatore a sinistra e il cliente a destra, viene mixata in un solo canale quando viene trascritta, quindi i parlanti sono separati dalle loro voci, non dal canale. E una linea telefonica a banda stretta non porta nulla sopra circa 3,4 kHz, il che toglie una parte di ciò che rende distinte due voci; i turni brevi e sovrapposti («yes», «mm-hm», «sorry, go on») sono il punto in cui le etichette sbagliano più spesso.
Con summary e title attivi, ogni chiamata riceve un titolo e alcune frasi su ciò di cui trattava, una volta che la trascrizione è definitiva. È ciò che va nel ticket, così l'operatore successivo conosce la storia senza aprire nulla. Il riassunto viene scritto dopo la trascrizione, quindi leggilo con GET /v1/transcriptions/{id}/summary e attendi finché il suo state è pending:
let sum = await vs.transcriptions.summary(tx.id);
while (sum.state === 'pending') {
await new Promise((r) => setTimeout(r, 3000));
sum = await vs.transcriptions.summary(tx.id);
}
Quando state è ready, title e summary contengono il testo. Una registrazione più breve di un minuto non riceve mai un riassunto (not_requested), il che riguarda le segreterie telefoniche: la maggior parte dei messaggi è così breve che la trascrizione è già il proprio riassunto. Una chiamata fatta senza summary può averne uno in seguito con POST /v1/transcriptions/{id}/summarize. I riassunti sono inclusi in ogni piano senza costi aggiuntivi.
GET /v1/transcriptions/{id}/export restituisce un file in uno di sette formati: json, xlsx, pdf, srt, vtt, txt o md. Ogni esportazione include le correzioni e i nomi dei parlanti che hai dato. Per un team di assistenza, due di questi fanno la maggior parte del lavoro.
JSON per il tuo codice. L'esportazione JSON ha name, language, durationS della chiamata e, con summary=true, il suo summary, poi segments: una voce per riga, con start e end in secondi, speaker, speakerName, text, una confidence, se la riga è stata corrected, e le words con i loro tempi. Basta a uno script per costruire una nota del CRM (il titolo, il riassunto, il nome dell'operatore, la durata della chiamata) o per estrarre ogni riga detta dal cliente.
const res = await vs.transcriptions.export(tx.id, 'json', { summary: true });
const call = await res.json();
const note = { subject: sum.title, body: sum.summary, minutes: Math.round(call.durationS / 60) };
// Your code posts `note` to the ticket: VocalStack has no CRM or helpdesk connector.
Excel per il revisore. L'esportazione XLSX ha un foglio Transcript con una riga per ogni riga di trascrizione e le colonne #, Start, End, Start (s), End (s), Speaker, Text, Confidence e Corrected. Con summary=true, il foglio About riporta il riassunto accanto a nome, lingua e durata della chiamata. Un responsabile qualità può filtrare le righe dell'operatore, aggiungere una colonna per punteggi o commenti e tenere una cartella di lavoro per ogni revisione.
curl -sSf "$API/v1/transcriptions/$TX/export?format=xlsx&summary=true" -H "$AUTH" -o ticket-48213.xlsx
L'assistenza in più lingue funziona allo stesso modo. Aggiungi lang=en a un'esportazione e il file si legge in inglese, una riga per frase, tradotto dove la chiamata era in spagnolo o in polacco; un revisore che legge una sola lingua può valutare chiamate ricevute in più lingue. L'esportazione PDF va bene per chi vuole leggere una chiamata intera su carta, con parlanti e timestamp.
Una trascrizione resta nell'account dopo essere stata esportata, quindi le chiamate formano via via una libreria. I tag le raggruppano: creane uno per coda o per team con POST /v1/tags, poi applicalo alle trascrizioni con POST /v1/tags/{id}/transcriptions.
const billing = await vs.tags.create({ name: 'Billing queue' });
await vs.tags.tagTranscriptions(billing.id, { add: [tx.id] });
GET /v1/search cerca poi ciò che è stato detto in tutte le chiamate, ristretto per tag e data: ogni chiamata della coda fatturazione di questo mese in cui qualcuno ha detto «cancel», ogni risultato con la sua chiamata e il secondo in cui è stato detto.
curl -sSfG "$API/v1/search" -H "$AUTH" --data-urlencode "q=cancel" \
--data-urlencode "tag=Billing queue" --data-urlencode "createdAfter=2026-11-01"
Tutto quanto sopra funziona anche senza codice. Un file caricato da Transcriptions → New viene etichettato, riassunto ed esportato dalla sua pagina, i parlanti si salvano in Speakers, e tag e ricerca stanno nell'elenco Transcriptions.
Alcune lacune vale la pena conoscerle prima di configurare qualsiasi cosa.
La conservazione dipende dal piano; la pagina dei prezzi mostra per quanto tempo audio e trascrizioni vengono conservati in ciascuno. Una trascrizione può essere archiviata, e una archiviata può essere eliminata con POST /v1/transcriptions/{id}/purge, che la cancella definitivamente con tutto ciò che contiene.
Ai prezzi di lancio, le chiamate registrate costano $0.20 all'ora di audio, fatturate al secondo ($0.0033 al minuto), con un minimo di 5 minuti per trascrizione con Pay as you go (a consumo), nessuno con Premium o Enterprise. Le tariffe attuali sono nella pagina dei prezzi. Etichette dei parlanti, assegnazione dei nomi, riassunti, traduzioni ed esportazioni non aggiungono mai nulla alla fattura.
Le chiamate di assistenza sono spesso brevi, quindi il minimo pesa più della tariffa nel conto di un team di assistenza. Con Pay as you go:
Con Premium ed Enterprise non c'è alcun minimo, quindi ogni chiamata è fatturata per i suoi secondi: il messaggio in segreteria di 40 secondi costa circa un quinto di centesimo, e le 1.000 chiamate da tre minuti circa $10. Un team che riceve per lo più chiamate brevi dovrebbe confrontare i due piani sulla durata reale delle proprie chiamate.
Ai prezzi di lancio, un team che registra 2.000 chiamate al mese con una media di 8 minuti invia 16.000 minuti di audio: circa $53 di credito al mese con Premium, riassunti e fogli di calcolo inclusi. Con Pay as you go, ogni chiamata sotto i 5 minuti si aggiunge a questa cifra.
La trascrizione in diretta costa di più ($0.60 all'ora ai prezzi di lancio), perché sta al passo con la chiamata; se durante la chiamata a nessuno servono le parole, trascrivi la registrazione dopo. Un nuovo account parte con un credito di registrazione una tantum e non serve la carta, quindi i passaggi sopra si possono provare su un lotto di tue chiamate prima di comprare qualsiasi cosa.