Intentions

Manage user's intentions preferences and settings. Intentions represent the user's goals and preferences for different aspects of the application. Some intentions may require VIP subscription access.

Update Intention

Update the user's current intention. This will reset the user's progress and create new scheduled notifications based on the new intention.

Endpoint

• Method: PATCH
• URL: /api/intentions

Request Headers

Header	Value	Required
Content-Type	application/json	Yes
Accept	application/json	Yes
Authorization	Bearer YOUR_API_TOKEN	Yes

Request Parameters

Parameter	Type	Required	Description
intention_id	integer	Yes	ID of the intention to update
is_in_register	string	Yes	Whether this is being set during registration. Must be 'true' or 'false'

Request Body Example

{
    "intention_id": 1,
    "is_in_register": "false"
}

Success Response

{
    "success": true,
    "message": "تم إنشاء البيانات بنجاح",
    "data": {
        "id": 1,
        "name": "John Doe",
        "email": "john@example.com",
        "avatar": "https://example.com/avatars/john.jpg",
        "is_using_apple_private_relay_email": false,
        "is_app_rated": true,
        "is_subscribed": false,
        "is_app_rated_reminder": true,
        "profile": {
            "date_of_birth": "1990-01-01",
            "age": 33,
            "gender": "male",
            "phone": "555555555",
            "country_phone_code": "+966",
            "letter_intention_index": 1,
            "language_app": "ar",
            "language_affirmation": "ar",
            "profile_progress": 80,
            "marital_status": "single",
            "background_type": "LIGHT",
            "custom_background": null,
            "reminders_per_day": 3,
            "start_time": "08:00:00",
            "end_time": "22:00:00",
            "start_time_human": "08:00 AM",
            "end_time_human": "10:00 PM",
            "check_if_need_to_update_intention": false
        },
        "nationality": {
            "id": 1,
            "name": "Saudi"
        },
        "intention": {
            "id": 1,
            "name": "Self Development"
        },
        "country": {
            "id": 1,
            "name": "Saudi Arabia"
        },
        "incomeLevel": {
            "id": 2,
            "name": "10,000 - 20,000"
        },
        "educationalLevel": {
            "id": 3,
            "name": "Bachelor's Degree"
        },
        "interests": [
            {
                "id": 1,
                "name": "Reading"
            },
            {
                "id": 2,
                "name": "Writing"
            }
        ],
        "hobbies": [
            {
                "id": 1,
                "name": "Photography"
            }
        ],
        "devices": [
            {
                "device_id": "device_123",
                "is_Expired": false
            }
        ]
    },
    "status_code": 200
}

Error Responses

Unauthorized (401)

{
    "success": false,
    "message": "Unauthenticated",
    "data": null,
    "status_code": 401
}

Invalid Intention ID (422)

{
    "success": false,
    "message": "حقل intention_id غير موجود",
    "data": null,
    "status_code": 422
}

VIP Subscription Required (403)

{
    "success": false,
    "message": "يجب أن تكون مشتركاً في الباقة المميزة",
    "data": null,
    "status_code": 403
}

User Profile Not Found (404)

{
    "success": false,
    "message": "لم يتم العثور على السجل",
    "data": null,
    "status_code": 404
}

Example Implementation Flow

Update Intention

1. Get the user's API token from storage
2. Prepare intention update request:
   • Validate intention_id exists
   • Set is_in_register appropriately ("true" if during registration, "false" otherwise)
3. Make PATCH request to /api/intentions
4. Upon success:
   • Update UI to show new intention
   • Update user profile with new intention data
   • Reset progress indicators
   • Wait for new notifications to be scheduled
   • Show success message in Arabic
5. Upon error:
   • If unauthorized (401):
     • Clear stored credentials
     • Redirect to login
     • Preserve intention_id for after login
   • If VIP required (403):
     • Show VIP subscription dialog
     • Explain VIP benefits
     • Provide subscription options
     • Keep current intention active
   • If invalid intention (422):
     • Show error message
     • Guide user to select valid intention
     • Log invalid intention_id for debugging
   • If profile not found (404):
     • Redirect to profile creation
     • Store intention_id for after profile creation

Error Recovery

1. Network errors:
   • Implement retry mechanism
   • Show connection status
   • Cache intention_id for retry
2. VIP access required:
   • Preserve current intention
   • Show upgrade benefits
   • Provide easy way to restore previous intention
3. Invalid states:
   • Guide user to complete profile if missing
   • Help select valid intention if invalid
   • Clear invalid cached data

Best Practices

1. Profile handling:
   • Always verify profile exists before update
   • Guide user to complete profile if missing
2. VIP features:
   • Clearly mark VIP intentions
   • Show VIP benefits before update
   • Provide smooth upgrade path
3. User experience:
   • Show loading state during update
   • Explain progress reset if applicable
   • Preview new notifications schedule
   • Allow canceling during processing