Uma transcrição distingue as vozes, mas não pode saber qual é o atendente. Salve cada atendente uma vez, a partir de uma chamada dele, e todas as chamadas seguintes chegam com o atendente identificado pelo nome, um resumo no topo e uma planilha pronta para a análise de qualidade.
Um responsável de qualidade que revisa chamadas de suporte ouvindo consegue dar conta de poucas por dia, e uma chamada de sete minutos leva sete minutos por mais rápido que você clique. Lida como texto, a mesma chamada tem cerca de mil palavras, uma página, e uma página pode ser folheada, pesquisada e colada num ticket. A transcrição de chamadas de atendimento ao cliente transforma as gravações que o seu sistema telefônico já guarda nessas páginas. Três coisas decidem se as páginas servem para alguma coisa: se cada linha diz quem falou, atendente ou cliente; se a chamada vem com um resumo curto do que foi pedido e do que foi combinado; e se o resultado chega onde a equipe trabalha, uma nota do CRM ou uma planilha de qualidade.
Este artigo percorre esse fluxo de trabalho com o VocalStack: chamadas gravadas enviadas pela API, o atendente reconhecido pelo nome, um resumo escrito para cada chamada e exportações em JSON e Excel. Ele também diz com franqueza o que o VocalStack não faz por uma equipe de suporte, porque parte disso importa antes de enviar a primeira chamada.
A maioria dos sistemas de telefonia e de central de atendimento consegue exportar as gravações como arquivos de áudio, ou dar um link de download para cada uma. Qualquer um serve. POST /v1/transcriptions aceita um arquivo como upload multipart, ou um corpo JSON com uma url que o próprio servidor baixa. O tutorial de arquivos cobre a chamada em detalhe; para chamadas, estas configurações importam, todas dentro de settings:
speakerLabels: defina como on, para que cada linha de uma chamada entre duas pessoas leve um locutor. O padrão, When Needed (auto), rotula as linhas só quando um segundo locutor é ouvido, o que serve melhor para uma palestra do que para uma chamada.summary e title: ambos ficam desligados a menos que você peça. Com eles ligados, um título e um resumo curto são escritos para a chamada depois de transcrita.spokenLanguage: informe quando souber, como numa fila que só recebe chamadas em um idioma. Se omitir, o idioma é detectado, entre 100.O upload responde na hora com um id de transcrição; as palavras chegam um pouco depois. Envie uma Idempotency-Key com cada upload: uma nova tentativa com a mesma chave e o mesmo corpo em até 24 horas devolve a primeira transcrição em vez de criar, e cobrar, uma segunda. O id da própria chamada no seu sistema telefônico é uma chave natural.
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 ?? ''}`);
As gravações de uma noite podem subir num único laço. Cada plano define quantas transcrições rodam ao mesmo tempo, e um arquivo acima desse número não é recusado: ele é criado, espera em queued e começa sozinho quando uma anterior termina. O limite que você pode atingir é o número de transcrições que uma conta pode iniciar pela API em uma hora; os valores de cada plano estão na página de preços. Não há webhooks, então o seu script consulta cada trabalho até ele terminar, que é o que waitForJob faz por você.
Os rótulos de locutor vêm da diarização: a gravação é dividida em turnos, e os turnos são agrupados por voz. O que volta é «Speaker 1» e «Speaker 2». O sistema consegue distinguir duas vozes, mas nada no áudio diz qual delas trabalha para você. Diarização versus reconhecimento de fala explica a mecânica; para chamadas de suporte, a resposta prática é salvar cada atendente uma vez.
Um locutor salvo é uma impressão de voz com um nome. Depois que ele existe, toda nova transcrição da conta compara as vozes que ouve com os seus locutores salvos, e uma correspondência leva o nome para a transcrição. Os arquivos são comparados automaticamente, então as linhas do atendente chegam como «Dana» em vez de «Speaker 1». O cliente continua numerado até você dar um nome a ele.
Tire a impressão de uma chamada do próprio atendente, e não de uma gravação feita numa mesa. Uma voz de fone de ouvido numa sala silenciosa e a mesma voz numa linha telefônica podem soar menos parecidas para uma máquina do que duas pessoas diferentes gravadas do mesmo jeito, e a impressão combina melhor com áudio parecido com aquele de onde saiu. POST /v1/speakers/from-appearance salva um locutor direto de uma transcrição, usando os trechos da chamada em que essa pessoa fala como amostra. appearance é o índice speaker que as linhas dela carregam.
await vs.speakers.createFromAppearance({ transcriptionId: tx.id, appearance: 0, name: 'Dana (Billing)' });
Salvar um locutor desse jeito guarda só a impressão dele, a partir de pelo menos 5 segundos de fala; uma chamada em que o atendente fala por um minuto ou mais dá uma impressão mais estável. A clonagem de voz é uma etapa separada que exige o consentimento da pessoa, e um fluxo de suporte não tem uso para ela.
Daí em diante, a transcrição de uma chamada concluída diz quem foi reconhecido. GET /v1/transcriptions/{id}/transcript lista os speakers, e um locutor que combinou com um salvo tem identified: true e o nome salvo. Os demais podem ser nomeados com uma chamada cada, PUT /v1/transcriptions/{id}/appearances/{number}, onde number é o número de exibição do locutor. O nome é guardado na transcrição, então toda exportação depois dele diz «Customer» em vez de um número.
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');
}
Trate «todo mundo que não foi reconhecido é o cliente» como uma regra prática e confira nas suas próprias chamadas. Uma transferência traz um segundo atendente, um aviso gravado de menu pode ser ouvido como uma voz própria, e um atendente que ainda não foi salvo se parece exatamente com um cliente. Note também como a comparação é limitada: cada transcrição é comparada com os 64 locutores salvos atualizados mais recentemente na conta, então uma equipe maior que isso não deve contar com o reconhecimento de todos os atendentes em todas as chamadas.
Duas propriedades do áudio telefônico vale conhecer antes de julgar os rótulos. Uma gravação de dois canais, com o atendente à esquerda e o cliente à direita, é misturada em um único canal ao ser transcrita, então os locutores são separados pela voz, não pelo canal. E uma linha telefônica de banda estreita não carrega nada acima de cerca de 3,4 kHz, o que remove parte do que torna duas vozes distintas; turnos curtos e sobrepostos («sim», «aham», «desculpe, pode continuar») são onde os rótulos mais erram.
Com summary e title ligados, cada chamada recebe um título e algumas frases sobre o assunto assim que a transcrição é final. É isso que vai para o ticket, para que o próximo atendente conheça o histórico sem abrir nada. O resumo é escrito depois da transcrição, então leia-o com GET /v1/transcriptions/{id}/summary e espere enquanto o state for 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 trazem o texto. Uma gravação com menos de um minuto nunca recebe resumo (not_requested), o que importa para o correio de voz: a maioria das mensagens é curta o bastante para que a transcrição seja o seu próprio resumo. Uma chamada feita sem summary pode receber um depois com POST /v1/transcriptions/{id}/summarize. Os resumos estão incluídos em todos os planos sem custo extra.
GET /v1/transcriptions/{id}/export devolve um arquivo em um de sete formatos: json, xlsx, pdf, srt, vtt, txt ou md. Toda exportação inclui as correções e os nomes de locutor que você deu. Para uma equipe de suporte, duas delas fazem a maior parte do trabalho.
JSON para o seu próprio código. A exportação JSON traz o name, o language, a durationS da chamada e, com summary=true, o seu summary, e depois segments: uma entrada por linha, com start e end em segundos, speaker, speakerName, text, uma confidence, se a linha foi corrected e as words com seus próprios tempos. Isso basta para um script montar uma nota de CRM (o título, o resumo, o nome do atendente, a duração da chamada) ou extrair todas as linhas ditas pelo 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 para o revisor. A exportação XLSX tem uma planilha Transcript com uma linha por fala e as colunas #, Start, End, Start (s), End (s), Speaker, Text, Confidence e Corrected. Com summary=true, a planilha About traz o resumo ao lado do nome, do idioma e da duração da chamada. Um responsável de qualidade pode filtrar as linhas do atendente, acrescentar uma coluna para notas ou comentários e manter uma pasta de trabalho por revisão.
curl -sSf "$API/v1/transcriptions/$TX/export?format=xlsx&summary=true" -H "$AUTH" -o ticket-48213.xlsx
O suporte em mais de um idioma funciona do mesmo jeito. Adicione lang=en a uma exportação e o arquivo é lido em inglês, uma linha por frase, traduzida onde a chamada era em espanhol ou polonês; um revisor que lê um só idioma pode avaliar chamadas atendidas em vários. A exportação em PDF serve a quem quer ler uma chamada inteira no papel, com locutores e marcas de tempo.
Uma transcrição continua na conta depois de exportada, então as chamadas formam uma biblioteca. As tags as agrupam: crie uma por fila ou equipe com POST /v1/tags e aplique-a às transcrições com 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 então pesquisa o que foi dito em todas as chamadas, restrito por tag e data: todas as chamadas da fila de cobrança deste mês em que alguém disse «cancel», cada resultado com a sua chamada e o segundo em que foi dito.
curl -sSfG "$API/v1/search" -H "$AUTH" --data-urlencode "q=cancel" \
--data-urlencode "tag=Billing queue" --data-urlencode "createdAfter=2026-11-01"
Tudo isso também funciona sem código. Um arquivo enviado em Transcriptions → New é rotulado, resumido e exportado a partir da própria página, os locutores são salvos em Speakers, e as tags e a busca ficam na lista de Transcriptions.
Algumas lacunas valem ser conhecidas antes de configurar qualquer coisa.
A retenção depende do plano; a página de preços mostra por quanto tempo o áudio e as transcrições são guardados em cada um. Uma transcrição pode ser arquivada, e uma arquivada pode ser eliminada com POST /v1/transcriptions/{id}/purge, que a apaga junto com tudo o que há nela, em definitivo.
Com os preços de lançamento, as chamadas gravadas custam $0.20 por hora de áudio, cobradas por segundo ($0.0033 o minuto), com um mínimo de 5 minutos por transcrição no Pay as you go (nenhum no Premium ou no Enterprise). As tarifas atuais estão na página de preços. Rótulos de locutor, nomes de locutor, resumos, traduções e exportações nunca aumentam a conta.
As chamadas de suporte costumam ser curtas, então o mínimo decide mais da conta de uma equipe de suporte do que a tarifa. No Pay as you go:
No Premium e no Enterprise não há mínimo, então cada chamada é cobrada pelos seus próprios segundos: a mensagem de voz de 40 segundos custa cerca de um quinto de centavo, e as 1.000 chamadas de três minutos cerca de $10. Uma equipe que atende principalmente chamadas curtas deve comparar os dois com a duração das suas próprias chamadas.
Com os preços de lançamento, uma equipe que grava 2.000 chamadas por mês com média de 8 minutos envia 16.000 minutos de áudio: cerca de $53 de crédito por mês no Premium, com resumos e planilhas incluídos. No Pay as you go, cada chamada com menos de 5 minutos soma a esse valor.
A transcrição ao vivo custa mais ($0.60 por hora com os preços de lançamento), porque acompanha o ritmo da chamada; se ninguém precisa das palavras durante a chamada, transcreva a gravação depois. Uma conta nova começa com um crédito de cadastro único e não é preciso cartão, então os passos acima podem ser testados num lote das suas próprias chamadas antes de comprar qualquer coisa.