Pular para o conteúdo principal

Enviar uma conversa (WhatsApp)

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

O endpoint mais usado da integração. Recebe uma conversa de texto — com ou sem mensagens de áudio no meio — em um dos dois gatilhos da RN de texto: tabulação do atendimento, ou ociosidade de 2 a 3 dias.

Campos​

CampoTipoObrigatórioRegras
chaveExternastringsimIdentificador da conversa na origem (id do chat, id do protocolo). Até 120 caracteres. É a chave de idempotência — ver Idempotência.
mensagensarraysimA conversa inteira, sempre — nunca só as mensagens novas. Ao menos uma. Ver A mensagem.
ocorridaEmdatetimesimQuando a conversa aconteceu na origem. ISO-8601 com fuso. Ver Fuso horário.
parcialboolnão (false)true quando a conversa foi enviada sem ter terminado — o caso da ociosidade. É o que permite reenviar depois com a continuação.
matriculaOperadorstringnãoIdentificador do atendente na origem. Ver Metadados e atendente.
metadadosobjeto {string: string}nãoCampos livres da operação: campanha, fila, produto, equipe. Ver Metadados.
parcial decide se a conversa pode continuar

Enviada com parcial: false, a conversa é imutável: nenhum reenvio posterior muda o conteúdo, nem que ele venha com mensagens novas. Não há como reabrir pela API. Marque parcial: true sempre que o atendimento ainda puder receber mensagem.

Exemplo 1 — conversa concluída, só texto​

O caso mais comum: o operador tabulou o atendimento.

{
"chaveExterna": "WA-2026-09-01-000482",
"ocorridaEm": "2026-09-01T14:02:10-03:00",
"parcial": false,
"matriculaOperador": "A-77",
"metadados": {
"campanha": "cobranca",
"fila": "renegociacao",
"atendente_nome": "Ana Souza",
"equipe": "Cobrança Sul"
},
"mensagens": [
{
"id": "msg-1",
"interlocutor": "Cliente",
"emitidaEm": "2026-09-01T14:02:10-03:00",
"texto": "Boa tarde, recebi uma cobrança que não reconheço."
},
{
"id": "msg-2",
"interlocutor": "Operador",
"emitidaEm": "2026-09-01T14:02:48-03:00",
"texto": "Boa tarde! Meu nome é Ana, vou verificar. Pode me confirmar o CPF?"
},
{
"id": "msg-3",
"interlocutor": "Cliente",
"emitidaEm": "2026-09-01T14:03:15-03:00",
"texto": "Claro, 123.456.789-00."
},
{
"id": "msg-4",
"interlocutor": "Operador",
"emitidaEm": "2026-09-01T14:05:02-03:00",
"texto": "Localizei. A cobrança é da fatura de agosto, vencida dia 10. Consigo parcelar em até 3x sem juros."
},
{
"id": "msg-5",
"interlocutor": "Cliente",
"emitidaEm": "2026-09-01T14:05:40-03:00",
"texto": "Pode fazer em 3x então."
},
{
"id": "msg-6",
"interlocutor": "Operador",
"emitidaEm": "2026-09-01T14:07:11-03:00",
"texto": "Feito. O boleto da primeira parcela chega por e-mail em instantes. Posso ajudar em algo mais?"
},
{
"id": "msg-7",
"interlocutor": "Cliente",
"emitidaEm": "2026-09-01T14:07:30-03:00",
"texto": "Não, obrigado."
},
{
"id": "msg-8",
"interlocutor": "Sistema",
"emitidaEm": "2026-09-01T14:07:35-03:00",
"texto": "Atendimento encerrado pelo operador."
}
]
}

Resposta — 201 Created:

{
"interacaoId": "019205a1-7c3e-7f10-b2d4-3a9c21e8f0aa",
"status": "Análise pendente",
"resultado": "Criada",
"duplicada": false,
"versao": 1,
"mensagensNovas": 0,
"consumiuVaga": true,
"aguardandoLimite": false,
"pendenteMetadadoObrigatorio": false,
"metadadosNovos": ["fila"],
"metadadosIgnorados": []
}

metadadosNovos: ["fila"] avisa que fila nunca havia aparecido nesta conta e foi criada agora. É o seu sinal de erro de digitação — ver Metadados.

Exemplo 2 — conversa com mensagens de áudio​

O cliente mandou áudios. Quem já tem o texto manda texto junto; quem não tem manda só a URL, e a plataforma transcreve.

{
"chaveExterna": "WA-2026-09-01-000519",
"ocorridaEm": "2026-09-01T09:41:00-03:00",
"parcial": false,
"metadados": { "campanha": "suporte", "atendente_id": "B-12" },
"mensagens": [
{
"id": "m-1",
"interlocutor": "Cliente",
"emitidaEm": "2026-09-01T09:41:00-03:00",
"urlAudio": "https://midia.parceiro.com.br/wa/000519/m-1.ogg"
},
{
"id": "m-2",
"interlocutor": "Operador",
"emitidaEm": "2026-09-01T09:42:20-03:00",
"texto": "Entendi. Vou abrir o chamado técnico agora."
},
{
"id": "m-3",
"interlocutor": "Cliente",
"emitidaEm": "2026-09-01T09:43:05-03:00",
"urlAudio": "https://midia.parceiro.com.br/wa/000519/m-3.ogg",
"texto": "Tá bom, obrigada, vou aguardar."
}
]
}

Na resposta, status vem Transcrição pendente: m-1 precisa virar texto antes de a conversa ser analisada. m-3 já veio com texto — a plataforma não transcreve por cima do que a origem mandou, e a URL fica só para o supervisor ouvir.

A conversa só segue para a análise com todos os áudios em texto: sentimento e auditoria leem o todo, e um áudio faltando no meio muda o julgamento.

Exemplo 3 — conversa parcial, e depois a continuação​

Primeiro envio, por ociosidade — o cliente parou de responder há três dias:

{
"chaveExterna": "WA-2026-08-28-000301",
"ocorridaEm": "2026-08-28T16:10:00-03:00",
"parcial": true,
"mensagens": [
{ "id": "m-1", "interlocutor": "Cliente", "emitidaEm": "2026-08-28T16:10:00-03:00", "texto": "Quero cancelar o plano." },
{ "id": "m-2", "interlocutor": "Operador", "emitidaEm": "2026-08-28T16:11:30-03:00", "texto": "Posso saber o motivo? Talvez eu consiga uma condição melhor." }
]
}

→ 201, resultado: "Criada", versao: 1. A conversa é auditada como está, incompleta.

Segundo envio, quatro dias depois, quando o cliente voltou — desta vez concluída. Aqui vai a conversa inteira, que é o formato mais comum quando o sistema de origem guarda a thread toda:

{
"chaveExterna": "WA-2026-08-28-000301",
"ocorridaEm": "2026-08-28T16:10:00-03:00",
"parcial": false,
"mensagens": [
{ "id": "m-1", "interlocutor": "Cliente", "emitidaEm": "2026-08-28T16:10:00-03:00", "texto": "Quero cancelar o plano." },
{ "id": "m-2", "interlocutor": "Operador", "emitidaEm": "2026-08-28T16:11:30-03:00", "texto": "Posso saber o motivo? Talvez eu consiga uma condição melhor." },
{ "id": "m-3", "interlocutor": "Cliente", "emitidaEm": "2026-09-01T10:22:00-03:00", "texto": "O valor subiu muito." },
{ "id": "m-4", "interlocutor": "Operador", "emitidaEm": "2026-09-01T10:24:10-03:00", "texto": "Consigo manter o valor anterior por 12 meses. Fecha?" },
{ "id": "m-5", "interlocutor": "Cliente", "emitidaEm": "2026-09-01T10:25:00-03:00", "texto": "Fecha." }
]
}

→ 201, resultado: "Reingerida", versao: 2, mensagensNovas: 3.

Repare que mensagensNovas é 3, e não 5: a plataforma casou m-1 e m-2 com o que já tinha, pelo id.

O mesmo resultado, mandando só o delta. Se o seu sistema não guarda a thread inteira — cada ticket carrega só o que chegou nele —, este payload produz exatamente a mesma versão 2:

{
"chaveExterna": "WA-2026-08-28-000301",
"ocorridaEm": "2026-08-28T16:10:00-03:00",
"parcial": false,
"mensagens": [
{ "id": "m-3", "interlocutor": "Cliente", "emitidaEm": "2026-09-01T10:22:00-03:00", "texto": "O valor subiu muito." },
{ "id": "m-4", "interlocutor": "Operador", "emitidaEm": "2026-09-01T10:24:10-03:00", "texto": "Consigo manter o valor anterior por 12 meses. Fecha?" },
{ "id": "m-5", "interlocutor": "Cliente", "emitidaEm": "2026-09-01T10:25:00-03:00", "texto": "Fecha." }
]
}

→ 201, resultado: "Reingerida", versao: 2, mensagensNovas: 3. A versão 2 fica com as cinco falas nos dois casos: a plataforma une o que chegou com o que já tinha.

Escolha o formato que for mais fácil de produzir e fique com ele — misturar os dois funciona, mas torna o seu log mais difícil de ler no dia em que algo não bater.

Nasce uma versão nova da conversa, com auditoria própria. A versão 1 continua existindo, intacta, no histórico — a auditoria feita sobre ela não é reescrita. O detalhe inteiro está em Conversa que continuou.

O id da mensagem é o que faz isso funcionar

É por ele que a plataforma casa as falas entre um envio e o outro — sem ele, nenhum dos dois formatos acima daria certo, e por isso ele é obrigatório em conversa parcial.

Ele ainda paga a si mesmo numa segunda frente: neste exemplo não havia áudio, mas se houvesse, é o id que permite reaproveitar as transcrições já feitas na versão 1 em vez de baixar e transcrever tudo de novo — o que o cliente pagaria.

Erros mais comuns neste endpoint​

RespostaCausa
Interação de texto exige ao menos uma mensagem.mensagens vazio ou ausente.
Mensagem sem texto e sem áudio.Alguma mensagem sem texto e sem urlAudio.
Interlocutor inválido: 'Atendente'. Válidos: ...Valor fora da lista fechada. Ver A mensagem.
Conversa com mais de 50 áudios não é aceita numa ingestão só.Teto de áudios por conversa.
200 com resultado: "Duplicada" quando você esperava criarOu o conteúdo é idêntico ao gravado, ou a conversa já estava parcial: false.

A lista completa e a política de retry estão em Erros e retry.