> ## 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.

# Mover Contacto

> Mueve un contacto a otra etapa del funnel

<Info>
  **Scope requerido:** `funnels:write`
</Info>

Cambia la etapa de un contacto en el funnel. Puedes moverlo a cualquier etapa o quitarlo del funnel.

<Tip>
  Envía `stage_id: null` para quitar al contacto de todas las etapas (útil para leads descartados).
</Tip>

***

## Path Parameters

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

***

## Body Parameters

<ParamField body="stage_id" type="string" required>
  UUID de la etapa destino. Envía `null` para quitar el contacto de cualquier etapa.
</ParamField>

***

## Ejemplos

### Mover a una etapa

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.whaapy.com/funnel/v1/contacts/550e8400-e29b-41d4-a716-446655440000/move \
    -H "Authorization: Bearer wha_TU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "stage_id": "stage-qualified-uuid"
    }'
  ```

  ```javascript Node.js theme={null}
  const contactId = '550e8400-e29b-41d4-a716-446655440000';
  const response = await fetch(
    `https://api.whaapy.com/funnel/v1/contacts/${contactId}/move`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer wha_TU_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        stage_id: 'stage-qualified-uuid'
      })
    }
  );
  ```

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

  contact_id = '550e8400-e29b-41d4-a716-446655440000'
  response = requests.post(
      f'https://api.whaapy.com/funnel/v1/contacts/{contact_id}/move',
      headers={
          'Authorization': 'Bearer wha_TU_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'stage_id': 'stage-qualified-uuid'
      }
  )
  ```

  ```php PHP theme={null}
  $contactId = '550e8400-e29b-41d4-a716-446655440000';
  $ch = curl_init("https://api.whaapy.com/funnel/v1/contacts/{$contactId}/move");
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: Bearer wha_TU_API_KEY',
      'Content-Type: application/json'
  ]);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
      'stage_id' => 'stage-qualified-uuid'
  ]));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $response = curl_exec($ch);
  ```
</RequestExample>

### Quitar de todas las etapas

<RequestExample>
  ```json Request theme={null}
  {
    "stage_id": null
  }
  ```
</RequestExample>

***

## Respuesta Exitosa

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "contact_id": "550e8400-e29b-41d4-a716-446655440000",
    "previous_stage": {
      "id": "stage-lead-uuid",
      "name": "Lead"
    },
    "new_stage": {
      "id": "stage-qualified-uuid",
      "name": "Qualified"
    },
    "moved_at": "2026-01-28T12:00:00Z"
  }
  ```
</ResponseExample>

### Quitar de etapa (null)

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "contact_id": "550e8400-e29b-41d4-a716-446655440000",
    "previous_stage": {
      "id": "stage-lead-uuid",
      "name": "Lead"
    },
    "new_stage": null,
    "moved_at": "2026-01-28T12:00:00Z"
  }
  ```
</ResponseExample>

***

## Errores

### Contacto no encontrado

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

### Etapa no encontrada

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

***

## Webhooks

Cuando mueves un contacto, se dispara el webhook `contact.stage_changed`:

```json theme={null}
{
  "event": "contact.stage_changed",
  "data": {
    "contact_id": "550e8400-e29b-41d4-a716-446655440000",
    "phone_number": "+5215512345678",
    "previous_stage_id": "stage-lead-uuid",
    "previous_stage_name": "Lead",
    "new_stage_id": "stage-qualified-uuid",
    "new_stage_name": "Qualified",
    "moved_at": "2026-01-28T12:00:00Z"
  }
}
```

***

## Movimiento Masivo

Para mover múltiples contactos a la vez, usa la [API de operaciones masivas](/api-reference/contacts/bulk):

```json theme={null}
POST /contacts/v1/bulk
{
  "operation": "set_funnel_stage",
  "contact_ids": ["uuid-1", "uuid-2", "uuid-3"],
  "funnel_stage_id": "stage-qualified-uuid"
}
```

***

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Listar Etapas" icon="list" href="/api-reference/funnels/stages-list">
    Ver etapas disponibles
  </Card>

  <Card title="Operaciones Masivas" icon="layer-group" href="/api-reference/contacts/bulk">
    Mover múltiples contactos
  </Card>

  <Card title="Obtener Contacto" icon="user" href="/api-reference/contacts/get">
    Ver etapa actual del contacto
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks/events">
    Recibir notificaciones de cambios
  </Card>
</CardGroup>