Skip to main content
PATCH
/
contacts
/
v1
/
{id}
curl -X PATCH https://api.whaapy.com/contacts/v1/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer wha_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Juan Pérez González",
    "email": "juan.perez@nuevoemail.com"
  }'

{
  "contact": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "phone_number": "+5215512345678",
    "name": "Juan Pérez González",
    "email": "juan.perez@nuevoemail.com",
    "tags": ["cliente", "premium", "vip"],
    "custom_fields": { 
      "company": "Acme Inc", 
      "last_purchase": "2026-01-28" 
    },
    "funnel_stage": { "id": "new-stage-uuid", "name": "Closed Won" },
    "updated_at": "2026-01-28T12:30:00Z"
  }
}
Actualiza uno o más campos de un contacto. Solo envía los campos que quieres modificar.
Los campos no incluidos en la request permanecen sin cambios.

​
Path Parameters

​
id
string
required
UUID del contacto a actualizar

​
Body Parameters

Todos los campos son opcionales. Solo se actualizan los campos enviados.

​
Información Básica

​
name
string
Nombre completo
​
email
string
Email (debe ser válido)
​
avatar_url
string
URL de imagen de perfil
​
notes
string
Notas internas

​
Tags

​
tags
string[]
Reemplaza todos los tags existentes
​
add_tags
string[]
Agrega tags sin eliminar los existentes
​
remove_tags
string[]
Elimina tags específicos
Si envías tags, se reemplazarán todos los tags. Usa add_tags o remove_tags para modificaciones parciales.

​
Campos Personalizados

​
custom_fields
object
Campos personalizados (se fusionan con los existentes)
​
external_ids
object
IDs externos (se fusionan con los existentes)

​
Funnel y Origen

​
funnel_stage_id
string
UUID de nueva etapa del funnel. Envía null para quitar la etapa.
​
source
string
Origen del contacto

​
Información de Empresa

​
company
string
Nombre de empresa
​
address
string
Dirección
​
city
string
Ciudad
​
state
string
Estado/Provincia
​
postal_code
string
Código postal
​
country
string
Código de país ISO (2 letras)

​
Asignación de Agente

​
assigned_agent_id
string | null
UUID del agente humano a asignar. Obtén IDs con GET /team/v1. Envía null para quitar la asignación.Al asignar un agente:
  • Todas las conversaciones activas del contacto se reasignan automáticamente
  • Las conversaciones futuras del contacto también se asignarán a este agente

​
Ejemplos

​
Actualizar Nombre y Email

curl -X PATCH https://api.whaapy.com/contacts/v1/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer wha_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Juan Pérez González",
    "email": "juan.perez@nuevoemail.com"
  }'

​
Agregar Tags (sin eliminar existentes)

{
  "add_tags": ["vip", "newsletter"]
}

​
Actualizar Campos Personalizados

{
  "custom_fields": {
    "last_purchase": "2026-01-28",
    "purchase_count": 5
  }
}
Los custom_fields se fusionan con los existentes. Si el contacto tenía { "company": "Acme" } y envías { "last_purchase": "2026-01-28" }, el resultado será { "company": "Acme", "last_purchase": "2026-01-28" }.

​
Mover a Nueva Etapa del Funnel

{
  "funnel_stage_id": "new-stage-uuid"
}

​
Asignar Agente Humano

{
  "assigned_agent_id": "550e8400-e29b-41d4-a716-446655440000"
}
Primero lista los agentes disponibles con GET /team/v1 para obtener sus IDs.

​
Respuesta Exitosa

{
  "contact": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "phone_number": "+5215512345678",
    "name": "Juan Pérez González",
    "email": "juan.perez@nuevoemail.com",
    "tags": ["cliente", "premium", "vip"],
    "custom_fields": { 
      "company": "Acme Inc", 
      "last_purchase": "2026-01-28" 
    },
    "funnel_stage": { "id": "new-stage-uuid", "name": "Closed Won" },
    "updated_at": "2026-01-28T12:30:00Z"
  }
}

​
Errores

{
  "error": "not_found",
  "message": "Contacto no encontrado"
}

{
  "error": "validation_error",
  "message": "Datos inválidos",
  "details": {
    "email": ["Email inválido"]
  }
}

​
Próximos Pasos

Operaciones Masivas

Actualizar múltiples contactos

Eliminar Contacto

Eliminar contacto

Fusionar Contactos

Combinar duplicados

Listar Tags

Ver tags disponibles