Principal API e integrações | Chaves, endpoints e webhooks Como mesclar (merge) contatos via API

Como mesclar (merge) contatos via API

Última atualização em Sep 23, 2026

A documentação mais atualizada das APIs da Cloud Humans fica em docs.cloudhumans.com/api-reference. Em caso de divergência entre este artigo e a referência, vale o que está lá.

Quando usar

  • Você tem o mesmo cliente duplicado em dois contatos (ex.: entrou por canais diferentes) e quer juntar em um só
  • Você está deduplicando a base de contatos via integração
  • Você quer consolidar histórico (conversas, mensagens, notas) de dois contatos em um único registro

Pré-requisitos

Endpoint

POST https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/actions/contact_merge

Headers

Header Valor
content-type application/json
api_access_token Seu token de API

Corpo da requisição

{
  "base_contact_id": 100,
  "mergee_contact_id": 250
}
Campo Descrição
base_contact_id Contato que permanece (vencedor da mesclagem)
mergee_contact_id Contato que será absorvido e excluído

Como funciona

Ao mesclar:

  • Todas as conversas, mensagens, notas, caixas de entrada (contact_inboxes), respostas de CSAT e eventos de campanha do contato absorvido passam para o contato-base.

  • Nos campos de perfil (name, email, phone_number, identifier, additional_attributes, custom_attributes), o contato-base vence. Onde o base estiver vazio, o valor do contato absorvido é aproveitado.

  • O contato absorvido (mergee_contact_id) é excluído ao final.

  • Resposta 200 com o contato-base resultante.

A mesclagem é irreversível. Fica registrada uma auditoria interna, mas não existe "desfazer". Confirme qual id é o base_contact_id (o que permanece) antes de chamar — inverter os dois exclui o contato errado.

Exemplo de requisição

curl -X POST \
  'https://{CLOUDCHAT_DOMAIN}/api/v1/accounts/{ACCOUNT_ID}/actions/contact_merge' \
  --header 'content-type: application/json' \
  --header 'api_access_token: SEU_TOKEN' \
  --data '{
    "base_contact_id": 100,
    "mergee_contact_id": 250
  }'

Erros comuns

Status Significado
404 Not Found Um dos contatos (base_contact_id ou mergee_contact_id) não existe na conta
422 Unprocessable Entity Payload inválido (falta base_contact_id ou mergee_contact_id)

Observações