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.
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
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
chaveExterna | string | sim | Identificador da ligação na origem (id do bilhete, id da chamada). Até 120 caracteres. Chave de idempotência — ver Idempotência. |
urlAudio | string | sim | URL da gravação. https, host por nome (IP é recusado), terminando na extensão do arquivo. Até 1000 caracteres. Ver URLs de áudio. |
ocorridaEm | datetime | sim | Quando a ligação aconteceu. ISO-8601 com fuso. Ver Fuso horário. |
mensagens | array | sim, hoje | A ligação já transcrita, fala a fala. Ver o aviso acima e A mensagem. |
duracaoSegundos | int | não | Duração da ligação. Ausente, é calculada a partir dos horários das mensagens. |
matriculaOperador | string | não | Identificador do atendente na origem. Ver Metadados e atendente. |
metadados | objeto {string: string} | não | Campos 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
- JSON
- cURL
{
"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."
}
]
}
curl -X POST "$BASE_URL/api/v1/interacoes/ingestao/voz" \
-H "X-Api-Key: $QA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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" },
"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." }
]
}'
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.
id da mensagem em vozNos 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
mensagensenquanto 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
| Resposta | Causa |
|---|---|
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 201 | Ligação enviada sem mensagens — o Exemplo 2. |