Skip to main content
POST
/
contacts
/
v1
/
{id}
/
merge
curl -X POST https://api.whaapy.com/contacts/v1/target-uuid/merge \
  -H "Authorization: Bearer wha_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_contact_id": "duplicate-uuid",
    "merge_strategy": {
      "name": "prefer_filled",
      "tags": "merge",
      "custom_fields": "merge"
    }
  }'

{
  "contact": {
    "id": "target-uuid",
    "phone_number": "+5215512345678",
    "name": "Juan Pérez",
    "email": "juan@email.com",
    "tags": ["cliente", "premium", "vip"],
    "custom_fields": { 
      "company": "Acme", 
      "source_field": "value",
      "role": "CEO"
    },
    "external_ids": {
      "hubspot": "abc123",
      "salesforce": "xyz789"
    },
    "notes": "Notas originales...\n\n---\n\nNotas del contacto fusionado...",
    "funnel_stage": { "id": "stage-uuid", "name": "Qualified" },
    "updated_at": "2026-01-28T12:00:00Z"
  },
  "merged_from": {
    "id": "duplicate-uuid",
    "deleted": true
  },
  "changes": {
    "tags_added": ["vip"],
    "custom_fields_added": ["source_field", "role"],
    "conversations_transferred": 2
  }
}
Combina dos contactos en uno solo. Útil para limpiar duplicados y consolidar información.
El contacto target (el de la URL) es el que permanece. El contacto source (el del body) será eliminado y sus datos fusionados al target.

​
Path Parameters

​
id
string
required
UUID del contacto target (el que permanece)

​
Body Parameters

​
source_contact_id
string
required
UUID del contacto a fusionar (será eliminado)
​
merge_strategy
object
Estrategia para resolver conflictos de datos

​
Estrategias de Merge

​
Nombre

​
merge_strategy.name
string
default:"prefer_filled"
  • keep_target: Mantener nombre del target
  • keep_source: Usar nombre del source
  • prefer_filled: Usar el que no esté vacío (prioridad target)

​
Tags

​
merge_strategy.tags
string
default:"merge"
  • merge: Combinar tags de ambos contactos
  • replace: Usar solo tags del source
  • keep_target: Mantener tags del target

​
Campos Personalizados

​
merge_strategy.custom_fields
string
default:"merge"
  • merge: Combinar campos (source sobrescribe si hay conflicto)
  • replace: Usar solo campos del source
  • keep_target: Mantener campos del target

​
Comportamiento Automático

Además de la estrategia configurable, el merge automáticamente:
  • Transfiere todas las conversaciones del source al target
  • Fusiona external_ids (IDs de CRMs externos)
  • Concatena las notas (separadas por ---)
  • Aplica prefer_filled para: email, avatar_url, company, address, city, state, postal_code
  • Elimina (soft delete) el contacto source

​
Ejemplos

curl -X POST https://api.whaapy.com/contacts/v1/target-uuid/merge \
  -H "Authorization: Bearer wha_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_contact_id": "duplicate-uuid",
    "merge_strategy": {
      "name": "prefer_filled",
      "tags": "merge",
      "custom_fields": "merge"
    }
  }'

​
Merge Simple (Estrategia por Defecto)

{
  "source_contact_id": "duplicate-uuid"
}

​
Priorizar Datos del Source

{
  "source_contact_id": "duplicate-uuid",
  "merge_strategy": {
    "name": "keep_source",
    "tags": "replace",
    "custom_fields": "replace"
  }
}

​
Respuesta Exitosa

{
  "contact": {
    "id": "target-uuid",
    "phone_number": "+5215512345678",
    "name": "Juan Pérez",
    "email": "juan@email.com",
    "tags": ["cliente", "premium", "vip"],
    "custom_fields": { 
      "company": "Acme", 
      "source_field": "value",
      "role": "CEO"
    },
    "external_ids": {
      "hubspot": "abc123",
      "salesforce": "xyz789"
    },
    "notes": "Notas originales...\n\n---\n\nNotas del contacto fusionado...",
    "funnel_stage": { "id": "stage-uuid", "name": "Qualified" },
    "updated_at": "2026-01-28T12:00:00Z"
  },
  "merged_from": {
    "id": "duplicate-uuid",
    "deleted": true
  },
  "changes": {
    "tags_added": ["vip"],
    "custom_fields_added": ["source_field", "role"],
    "conversations_transferred": 2
  }
}

​
Campos de la Respuesta

CampoDescripción
contactEl contacto target actualizado con los datos fusionados
merged_from.idUUID del contacto source que fue eliminado
merged_from.deletedSiempre true
changes.tags_addedTags que se agregaron del source
changes.custom_fields_addedCampos personalizados agregados del source
changes.conversations_transferredNúmero de conversaciones transferidas

​
Errores

{
  "error": "not_found",
  "message": "Uno o ambos contactos no encontrados"
}

{
  "error": "validation_error",
  "message": "No se puede fusionar un contacto consigo mismo"
}

​
Webhooks

Cuando fusionas contactos, se dispara el webhook contact.merged: 
{
  "event": "contact.merged",
  "data": {
    "target_contact_id": "target-uuid",
    "source_contact_id": "duplicate-uuid",
    "changes": {
      "tags_added": ["vip"],
      "custom_fields_added": ["source_field"],
      "conversations_transferred": 2
    },
    "merged_at": "2026-01-28T12:00:00Z"
  }
}

​
Próximos Pasos

Búsqueda Avanzada

Encontrar duplicados

Obtener Contacto

Ver contacto fusionado

Listar Contactos

Ver lista actualizada

Operaciones Masivas

Gestionar múltiples contactos