> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whaapy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Actualizar Contacto

> Actualiza los datos de un contacto existente

Actualiza uno o más campos de un contacto. Solo envía los campos que quieres modificar.

<Note>
  Los campos no incluidos en la request permanecen sin cambios.
</Note>

***

## Path Parameters

<ParamField path="id" type="string" required>
  UUID del contacto a actualizar
</ParamField>

***

## Body Parameters

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

### Información Básica

<ParamField body="name" type="string">
  Nombre completo
</ParamField>

<ParamField body="email" type="string">
  Email (debe ser válido)
</ParamField>

<ParamField body="avatar_url" type="string">
  URL de imagen de perfil
</ParamField>

<ParamField body="notes" type="string">
  Notas internas
</ParamField>

### Tags

<ParamField body="tags" type="string[]">
  **Reemplaza** todos los tags existentes
</ParamField>

<ParamField body="add_tags" type="string[]">
  **Agrega** tags sin eliminar los existentes
</ParamField>

<ParamField body="remove_tags" type="string[]">
  **Elimina** tags específicos
</ParamField>

<Warning>
  Si envías `tags`, se reemplazarán todos los tags. Usa `add_tags` o `remove_tags` para modificaciones parciales.
</Warning>

### Campos Personalizados

<ParamField body="custom_fields" type="object">
  Campos personalizados (se fusionan con los existentes)
</ParamField>

<ParamField body="external_ids" type="object">
  IDs externos (se fusionan con los existentes)
</ParamField>

### Funnel y Origen

<ParamField body="funnel_stage_id" type="string">
  UUID de nueva etapa del funnel. Envía `null` para quitar la etapa.
</ParamField>

<ParamField body="source" type="string">
  Origen del contacto
</ParamField>

### Información de Empresa

<ParamField body="company" type="string">
  Nombre de empresa
</ParamField>

<ParamField body="address" type="string">
  Dirección
</ParamField>

<ParamField body="city" type="string">
  Ciudad
</ParamField>

<ParamField body="state" type="string">
  Estado/Provincia
</ParamField>

<ParamField body="postal_code" type="string">
  Código postal
</ParamField>

<ParamField body="country" type="string">
  Código de país ISO (2 letras)
</ParamField>

### Asignación de Agente

<ParamField body="assigned_agent_id" type="string | null">
  UUID del agente humano a asignar. Obtén IDs con [GET /team/v1](/api-reference/team/list). 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
</ParamField>

***

## Ejemplos

### Actualizar Nombre y Email

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript Node.js theme={null}
  const contactId = '550e8400-e29b-41d4-a716-446655440000';
  const response = await fetch(
    `https://api.whaapy.com/contacts/v1/${contactId}`,
    {
      method: 'PATCH',
      headers: {
        'Authorization': 'Bearer wha_TU_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: 'Juan Pérez González',
        email: 'juan.perez@nuevoemail.com'
      })
    }
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  contact_id = '550e8400-e29b-41d4-a716-446655440000'
  response = requests.patch(
      f'https://api.whaapy.com/contacts/v1/{contact_id}',
      headers={
          'Authorization': 'Bearer wha_TU_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'name': 'Juan Pérez González',
          'email': 'juan.perez@nuevoemail.com'
      }
  )
  ```
</RequestExample>

### Agregar Tags (sin eliminar existentes)

<RequestExample>
  ```json Request theme={null}
  {
    "add_tags": ["vip", "newsletter"]
  }
  ```
</RequestExample>

### Actualizar Campos Personalizados

<RequestExample>
  ```json Request theme={null}
  {
    "custom_fields": {
      "last_purchase": "2026-01-28",
      "purchase_count": 5
    }
  }
  ```
</RequestExample>

<Info>
  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" }`.
</Info>

### Mover a Nueva Etapa del Funnel

<RequestExample>
  ```json Request theme={null}
  {
    "funnel_stage_id": "new-stage-uuid"
  }
  ```
</RequestExample>

### Asignar Agente Humano

<RequestExample>
  ```json Request theme={null}
  {
    "assigned_agent_id": "550e8400-e29b-41d4-a716-446655440000"
  }
  ```
</RequestExample>

<Tip>
  Primero lista los agentes disponibles con [GET /team/v1](/api-reference/team/list) para obtener sus IDs.
</Tip>

***

## Respuesta Exitosa

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>

***

## Errores

<ResponseExample>
  ```json 404 Not Found theme={null}
  {
    "error": "not_found",
    "message": "Contacto no encontrado"
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 400 Bad Request theme={null}
  {
    "error": "validation_error",
    "message": "Datos inválidos",
    "details": {
      "email": ["Email inválido"]
    }
  }
  ```
</ResponseExample>

***

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Operaciones Masivas" icon="layer-group" href="/api-reference/contacts/bulk">
    Actualizar múltiples contactos
  </Card>

  <Card title="Eliminar Contacto" icon="trash" href="/api-reference/contacts/delete">
    Eliminar contacto
  </Card>

  <Card title="Fusionar Contactos" icon="code-merge" href="/api-reference/contacts/merge">
    Combinar duplicados
  </Card>

  <Card title="Listar Tags" icon="tags" href="/api-reference/contacts/tags">
    Ver tags disponibles
  </Card>
</CardGroup>