Inicio API e integraciones | Claves, endpoints y webhooks Cómo fusionar (merge) contactos vía API

Cómo fusionar (merge) contactos vía API

Última actualización el Oct 02, 2026

La documentación más actualizada de las APIs de Cloud Humans está en docs.cloudhumans.com/api-reference. Si hay diferencias entre este artículo y la referencia, prevalece lo que está allí.

Cuándo usar

  • Tienes al mismo cliente duplicado en dos contactos (ej.: entró por canales diferentes) y quieres unirlos en uno solo
  • Estás deduplicando la base de contactos mediante una integración
  • Quieres consolidar el historial (conversaciones, mensajes, notas) de dos contactos en un único registro

Requisitos previos

Endpoint

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

Headers

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

Cuerpo de la solicitud

{
  "base_contact_id": 100,
  "mergee_contact_id": 250
}
Campo Descripción
base_contact_id Contacto que permanece (ganador de la fusión)
mergee_contact_id Contacto que será absorbido y eliminado

Cómo funciona

Al fusionar:

  • Todas las conversaciones, mensajes, notas, bandejas de entrada (contact_inboxes), respuestas de CSAT y eventos de campaña del contacto absorbido pasan al contacto base.

  • En los campos de perfil (name, email, phone_number, identifier, additional_attributes, custom_attributes), gana el contacto base. Donde el contacto base esté vacío, se aprovecha el valor del contacto absorbido.

  • El contacto absorbido (mergee_contact_id) se elimina al final.

  • Respuesta 200 con el contacto base resultante.

La fusión es irreversible. Queda registrada una auditoría interna, pero no existe "deshacer". Confirma cuál id es el base_contact_id (el que permanece) antes de hacer la llamada — invertir los dos elimina el contacto equivocado.

Ejemplo de solicitud

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
  }'

Errores comunes

Status Significado
404 Not Found Uno de los contactos (base_contact_id o mergee_contact_id) no existe en la cuenta
422 Unprocessable Entity Payload inválido (falta base_contact_id o mergee_contact_id)

Observaciones