Criar ou atualizar sem duplicar

Cada envio procura um registro existente. No CRM, a ordem é: externalRef, telefone, e-mail. Na prospecção: externalRef, CNPJ, e-mail ou telefone de um contato. Se achar, atualiza; se não, cria.

O parâmetro ?mode= controla como a atualização acontece:

Modo	O que faz
merge (padrão)	Preenche campos vazios, junta as tags e os campos extras. Nunca apaga um valor existente com um vazio
overwrite	Substitui os valores existentes pelos que você enviou. Valores vazios continuam sem apagar nada
create_only	Só cria. Se o registro já existe, não mexe em nada

O resultado vem em result: created, updated, unchanged (nada mudou) ou skipped (pulado, por exemplo por estar bloqueado).

Proteção contra reenvio

Envie o cabeçalho Idempotency-Key com um valor único por registro (por exemplo, o id do pedido). Se a sua ferramenta repetir a chamada por causa de uma falha de rede, o Conversaas devolve a resposta original em vez de processar de novo. A proteção vale por 24 horas.

Contatos que pediram para não receber mensagens

Se o telefone ou e-mail de um lead já está na lista de quem não quer receber mensagens, o lead é salvo normalmente, mas o Conversaas não remove nem altera esse bloqueio, e a resposta traz um aviso em warnings (phone_opted_out ou email_opted_out). Os disparos continuam respeitando o bloqueio.