Pular para o conteúdo principal

Enviar uma ligação (Voz)

POST {BASE_URL}/api/v1/interacoes/ingestao/voz

Uma ligação, enviada imediatamente após o operador desligar. O áudio não trafega no webhook: vem a URL da gravação, e a plataforma busca o arquivo quando precisa.

Hoje a ligação precisa vir já transcrita

O campo mensagens é documentado como opcional no contrato, mas na prática é obrigatório: a transcrição de gravação de ligação inteira ainda não está disponível — ela depende de identificar quem fala em cada trecho (diarização). Sem mensagens, o payload é aceito com 201 e a interação vai para Falha em seguida, com o motivo escrito na tela do cliente.

Detalhe e alternativa no Exemplo 2 e em O que ainda não existe.

Campos​

CampoTipoObrigatórioRegras
chaveExternastringsimIdentificador da ligação na origem (id do bilhete, id da chamada). Até 120 caracteres. Chave de idempotência — ver Idempotência.
urlAudiostringsimURL da gravação. https, host por nome (IP é recusado), terminando na extensão do arquivo. Até 1000 caracteres. Ver URLs de áudio.
ocorridaEmdatetimesimQuando a ligação aconteceu. ISO-8601 com fuso. Ver Fuso horário.
mensagensarraysim, hojeA ligação já transcrita, fala a fala. Ver o aviso acima e A mensagem.
duracaoSegundosintnãoDuração da ligação. Ausente, é calculada a partir dos horários das mensagens.
matriculaOperadorstringnãoIdentificador do atendente na origem. Ver Metadados e atendente.
metadadosobjeto {string: string}nãoCampos livres da operação. Ver Metadados.

Note que não há parcial aqui. Uma ligação termina quando termina; não existe ligação que continua depois. Consequência: ligação enviada não aceita reingestão — reenviar com conteúdo diferente devolve 200 Duplicada.

Por que a urlAudio é obrigatória mesmo com a transcrição​

A URL sustenta duas coisas que o texto não substitui: o player na tela do supervisor, e a evidência primária da auditoria. Transcrição — de quem quer que seja, nossa ou sua — é derivada. Quando o supervisor quer conferir se a MAIA leu certo, ele ouve.

Exemplo 1 — ligação já transcrita pelo discador​

{
"chaveExterna": "CALL-7f3a9c21",
"urlAudio": "https://gravacoes.discador.com.br/2026/09/01/7f3a9c21.mp3",
"ocorridaEm": "2026-09-01T11:15:00-03:00",
"duracaoSegundos": 214,
"matriculaOperador": "C-301",
"metadados": {
"campanha": "vendas",
"produto": "consignado",
"fila": "ativo-vendas"
},
"mensagens": [
{
"interlocutor": "Operador",
"emitidaEm": "2026-09-01T11:15:03-03:00",
"texto": "Bom dia, falo com a senhora Maria Oliveira?"
},
{
"interlocutor": "Cliente",
"emitidaEm": "2026-09-01T11:15:06-03:00",
"texto": "Sim, sou eu."
},
{
"interlocutor": "Operador",
"emitidaEm": "2026-09-01T11:15:09-03:00",
"texto": "Aqui é o Carlos, da Financeira X. Esta ligação é gravada. Estou ligando sobre a proposta de crédito consignado que a senhora simulou no nosso site."
},
{
"interlocutor": "Cliente",
"emitidaEm": "2026-09-01T11:15:22-03:00",
"texto": "Ah sim, eu simulei mas achei a taxa alta."
},
{
"interlocutor": "Operador",
"emitidaEm": "2026-09-01T11:15:31-03:00",
"texto": "Entendo. Consigo revisar a taxa conforme a margem disponível. A senhora tem interesse em ouvir a condição?"
},
{
"interlocutor": "Cliente",
"emitidaEm": "2026-09-01T11:15:44-03:00",
"texto": "Pode falar."
},
{
"interlocutor": "Operador",
"emitidaEm": "2026-09-01T11:18:12-03:00",
"texto": "A senhora prefere que eu envie a proposta por e-mail para analisar com calma?"
},
{
"interlocutor": "Cliente",
"emitidaEm": "2026-09-01T11:18:20-03:00",
"texto": "Sim, manda por e-mail."
}
]
}

Resposta — 201 Created:

{
"interacaoId": "019205b4-2e11-7a03-9c8f-1d4e77a9b201",
"status": "Análise pendente",
"resultado": "Criada",
"duplicada": false,
"versao": 1,
"mensagensNovas": 0,
"consumiuVaga": true,
"aguardandoLimite": false,
"pendenteMetadadoObrigatorio": false,
"metadadosNovos": [],
"metadadosIgnorados": []
}

status: "Análise pendente" — e não Transcrição pendente — porque a ligação já veio transcrita. Ela segue exatamente o caminho de uma conversa de texto.

O id da mensagem em voz

Nos exemplos de ligação omitimos o id, porque um discador raramente tem identificador por fala e a ligação não é reingerida. Se o seu sistema tiver, mande — não custa nada e o custo de não ter só aparece na reingestão, que aqui não acontece.

Exemplo 2 — só com a URL — ainda não suportado​

{
"chaveExterna": "CALL-7f3a9c22",
"urlAudio": "https://gravacoes.discador.com.br/2026/09/01/7f3a9c22.mp3",
"ocorridaEm": "2026-09-01T11:20:00-03:00",
"duracaoSegundos": 180
}

O que acontece: a ingestão responde 201 com status: "Transcrição pendente" — o payload é válido. Em seguida, no processamento, a interação vai para Falha com a mensagem:

Transcrição de gravação de ligação ainda não disponível: depende da diarização (D3). Envie a ligação já transcrita em mensagens enquanto isso.

Por que a plataforma não transcreve assim mesmo: sem diarização, todos os trechos sairiam como se fossem do mesmo falante. A auditoria julga a conduta do atendente — e sobre uma transcrição sem falantes ela julgaria o cliente como se fosse o operador. Uma nota errada é pior que nota nenhuma.

O que fazer até então: enviar mensagens com a transcrição do seu lado, como no Exemplo 1. Se o seu discador não transcreve, converse com o time do QA Analytics antes de integrar o canal de voz.

Erros mais comuns neste endpoint​

RespostaCausa
URL do áudio precisa ser https.Esquema http.
URL do áudio precisa apontar para um nome, não para um IP.Host numérico, como https://200.1.2.3/a.mp3.
URL do áudio precisa terminar com a extensão do arquivo.Caminho sem extensão — comum em URL de download por id.
Extensão de áudio não permitida: 'xyz'. Aceitas: ...Formato fora da lista. Ver URLs de áudio.
Interação em Falha logo após 201Ligação enviada sem mensagens — o Exemplo 2.