Skip to main content
POST
/
funnel
/
v1
/
contacts
/
{id}
/
move
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"
  }'

{
  "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"
}
Scope requerido: funnels:write
Cambia la etapa de un contacto en el funnel. Puedes moverlo a cualquier etapa o quitarlo del funnel.
Envía stage_id: null para quitar al contacto de todas las etapas (útil para leads descartados).

​
Path Parameters

​
id
string
required
UUID del contacto a mover

​
Body Parameters

​
stage_id
string
required
UUID de la etapa destino. Envía null para quitar el contacto de cualquier etapa.

​
Ejemplos

​
Mover a una etapa

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

​
Quitar de todas las etapas

{
  "stage_id": null
}

​
Respuesta Exitosa

{
  "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"
}

​
Quitar de etapa (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"
}

​
Errores

​
Contacto no encontrado

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

​
Etapa no encontrada

{
  "error": "not_found",
  "message": "Etapa no encontrada"
}

​
Webhooks

Cuando mueves un contacto, se dispara el webhook contact.stage_changed: 
{
  "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: 
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

Listar Etapas

Ver etapas disponibles

Operaciones Masivas

Mover múltiples contactos

Obtener Contacto

Ver etapa actual del contacto

Webhooks

Recibir notificaciones de cambios