telegram-management-system/marketing-agent/docs/api/users-api.md

# Users API

The Users API provides endpoints for managing users, groups, tags, and segments.

## User Endpoints

### List Users

Get a paginated list of users.

```http
GET /api/v1/users
```

#### Query Parameters

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| page | integer | Page number | 1 |
| limit | integer | Items per page (max 100) | 20 |
| search | string | Search in phone, firstName, lastName | - |
| status | string | Filter by status (active, inactive, blocked) | - |
| groups | string | Comma-separated group IDs | - |
| tags | string | Comma-separated tag IDs | - |
| sort | string | Sort field (prefix with - for descending) | -createdAt |

#### Response

```json
{
  "success": true,
  "data": {
    "users": [
      {
        "_id": "user123",
        "accountId": "acc123",
        "phone": "+1234567890",
        "firstName": "John",
        "lastName": "Doe",
        "username": "johndoe",
        "status": "active",
        "groups": [
          {
            "_id": "grp123",
            "name": "Premium Users"
          }
        ],
        "tags": [
          {
            "_id": "tag123",
            "name": "VIP",
            "color": "#FFD700"
          }
        ],
        "attributes": {
          "location": "New York",
          "language": "en",
          "joinDate": "2024-01-15T10:00:00Z"
        },
        "engagement": {
          "lastActivity": "2024-06-20T15:30:00Z",
          "messagesSent": 45,
          "messagesReceived": 120,
          "engagementScore": 85
        },
        "createdAt": "2024-01-15T10:00:00Z",
        "updatedAt": "2024-06-20T15:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1250,
      "pages": 63
    }
  }
}
```

### Get User

Get a specific user by ID.

```http
GET /api/v1/users/:id
```

### Create User

Create a new user.

```http
POST /api/v1/users
```

#### Request Body

```json
{
  "phone": "+1234567890",
  "firstName": "Jane",
  "lastName": "Smith",
  "username": "janesmith",
  "groups": ["grp123"],
  "tags": ["tag456"],
  "attributes": {
    "location": "Los Angeles",
    "language": "en",
    "source": "website"
  }
}
```

### Update User

Update user information.

```http
PUT /api/v1/users/:id
```

#### Request Body

```json
{
  "firstName": "Jane",
  "lastName": "Johnson",
  "status": "active",
  "attributes": {
    "location": "San Francisco",
    "preferences": {
      "notifications": true,
      "newsletter": false
    }
  }
}
```

### Delete User

Delete a user.

```http
DELETE /api/v1/users/:id
```

### Bulk Update Users

Update multiple users at once.

```http
POST /api/v1/users/bulk-update
```

#### Request Body

```json
{
  "userIds": ["user123", "user456", "user789"],
  "updates": {
    "addGroups": ["grp789"],
    "removeTags": ["tag123"],
    "attributes": {
      "campaign": "summer2024"
    }
  }
}
```

### Import Users

Import users from CSV.

```http
POST /api/v1/users/import
```

#### Request

- Content-Type: multipart/form-data
- File field name: `file`
- Optional field: `mapping` (JSON string)

#### Example CSV Format

```csv
phone,firstName,lastName,tags,groups
+1234567890,John,Doe,VIP,"Premium Users"
+0987654321,Jane,Smith,"VIP,Gold","Premium Users,Beta Testers"
```

### Export Users

Export users to CSV.

```http
GET /api/v1/users/export
```

#### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| format | string | Export format (csv, json) |
| fields | string | Comma-separated fields to export |
| filters | object | Same as list filters |

## Group Endpoints

### List Groups

Get all user groups.

```http
GET /api/v1/groups
```

#### Response

```json
{
  "success": true,
  "data": [
    {
      "_id": "grp123",
      "name": "Premium Users",
      "description": "Users with premium subscription",
      "type": "static",
      "memberCount": 450,
      "color": "#4CAF50",
      "isDefault": false,
      "createdAt": "2024-01-01T00:00:00Z"
    },
    {
      "_id": "grp456",
      "name": "Active Last 7 Days",
      "description": "Users active in the last 7 days",
      "type": "dynamic",
      "memberCount": 832,
      "rules": {
        "criteria": [
          {
            "field": "engagement.lastActivity",
            "operator": "greater_than",
            "value": "7d"
          }
        ],
        "logic": "AND"
      },
      "lastCalculated": "2024-06-20T15:00:00Z"
    }
  ]
}
```

### Create Group

Create a new user group.

```http
POST /api/v1/groups
```

#### Request Body (Static Group)

```json
{
  "name": "Beta Testers",
  "description": "Users testing beta features",
  "type": "static",
  "color": "#FF5722"
}
```

#### Request Body (Dynamic Group)

```json
{
  "name": "High Engagement Users",
  "description": "Users with engagement score > 80",
  "type": "dynamic",
  "rules": {
    "criteria": [
      {
        "field": "engagement.engagementScore",
        "operator": "greater_than",
        "value": 80
      }
    ],
    "logic": "AND"
  },
  "color": "#9C27B0"
}
```

### Update Group

Update group information.

```http
PUT /api/v1/groups/:id
```

### Delete Group

Delete a group.

```http
DELETE /api/v1/groups/:id
```

### Add Users to Group

Add users to a static group.

```http
POST /api/v1/groups/:id/add-users
```

#### Request Body

```json
{
  "userIds": ["user123", "user456", "user789"]
}
```

### Remove Users from Group

Remove users from a static group.

```http
POST /api/v1/groups/:id/remove-users
```

### Recalculate Dynamic Group

Manually trigger recalculation of a dynamic group.

```http
POST /api/v1/groups/:id/recalculate
```

## Tag Endpoints

### List Tags

Get all tags.

```http
GET /api/v1/tags
```

#### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| category | string | Filter by category |
| search | string | Search in tag names |

#### Response

```json
{
  "success": true,
  "data": [
    {
      "_id": "tag123",
      "name": "VIP",
      "category": "status",
      "color": "#FFD700",
      "description": "Very important customers",
      "usageCount": 156,
      "isSystem": false,
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}
```

### Create Tag

Create a new tag.

```http
POST /api/v1/tags
```

#### Request Body

```json
{
  "name": "Newsletter",
  "category": "preferences",
  "color": "#2196F3",
  "description": "Subscribed to newsletter"
}
```

### Update Tag

Update tag information.

```http
PUT /api/v1/tags/:id
```

### Delete Tag

Delete a tag.

```http
DELETE /api/v1/tags/:id
```

### Merge Tags

Merge multiple tags into one.

```http
POST /api/v1/tags/merge
```

#### Request Body

```json
{
  "sourceTagIds": ["tag456", "tag789"],
  "targetTagId": "tag123"
}
```

## Segment Endpoints

### List Segments

Get all segments.

```http
GET /api/v1/segments
```

#### Response

```json
{
  "success": true,
  "data": [
    {
      "_id": "seg123",
      "name": "High Value Customers",
      "description": "Customers with high purchase value and engagement",
      "criteria": [
        {
          "field": "attributes.totalPurchases",
          "operator": "greater_than",
          "value": 1000
        },
        {
          "field": "engagement.engagementScore",
          "operator": "greater_than",
          "value": 70
        }
      ],
      "logic": "AND",
      "userCount": 342,
      "lastCalculated": "2024-06-20T15:00:00Z",
      "isActive": true
    }
  ]
}
```

### Create Segment

Create a new segment.

```http
POST /api/v1/segments
```

#### Request Body

```json
{
  "name": "Inactive Users",
  "description": "Users who haven't been active in 30 days",
  "criteria": [
    {
      "field": "engagement.lastActivity",
      "operator": "less_than",
      "value": "30d"
    }
  ],
  "logic": "AND",
  "excludeSegments": ["seg456"]
}
```

### Test Segment

Test segment criteria and get user count.

```http
POST /api/v1/segments/:id/test
```

#### Response

```json
{
  "success": true,
  "data": {
    "userCount": 156,
    "sampleUsers": [
      {
        "_id": "user123",
        "phone": "+1234567890",
        "firstName": "John"
      }
    ],
    "executionTime": 125
  }
}
```

### Export Segment Users

Export users in a segment.

```http
GET /api/v1/segments/:id/export
```

### Clone Segment

Create a copy of a segment.

```http
POST /api/v1/segments/:id/clone
```

## Statistics Endpoints

### User Statistics

Get user statistics.

```http
GET /api/v1/users-stats
```

#### Response

```json
{
  "success": true,
  "data": {
    "totalUsers": 12500,
    "activeUsers": 8900,
    "newUsers": {
      "today": 45,
      "thisWeek": 312,
      "thisMonth": 1250
    },
    "engagement": {
      "avgEngagementScore": 72.5,
      "highlyEngaged": 3200,
      "moderatelyEngaged": 5700,
      "lowEngagement": 3600
    },
    "growth": {
      "daily": 2.5,
      "weekly": 8.3,
      "monthly": 15.6
    }
  }
}
```

### Group Statistics

Get group statistics.

```http
GET /api/v1/groups-stats
```

### Tag Statistics

Get tag usage statistics.

```http
GET /api/v1/tags-stats
```

## Supported Operators

For dynamic groups and segments:

| Operator | Description | Example |
|----------|-------------|----------|
| equals | Exact match | status equals "active" |
| not_equals | Not equal | status not_equals "blocked" |
| contains | Contains string | tags contains "VIP" |
| not_contains | Doesn't contain | groups not_contains "Blocked" |
| greater_than | Greater than | engagementScore greater_than 80 |
| less_than | Less than | lastActivity less_than "7d" |
| greater_or_equal | Greater or equal | totalPurchases greater_or_equal 100 |
| less_or_equal | Less or equal | messagesSent less_or_equal 10 |
| in | In list | location in ["NY", "CA", "TX"] |
| not_in | Not in list | status not_in ["blocked", "inactive"] |
| exists | Field exists | email exists true |
| regex | Regular expression | phone regex "^\+1" |

## Best Practices

1. **Segmentation**: Use segments for targeted campaigns
2. **Dynamic Groups**: Leverage dynamic groups for automatic user categorization
3. **Tags**: Use tags for flexible user labeling
4. **Bulk Operations**: Use bulk endpoints for efficiency
5. **Caching**: Segment calculations are cached for performance
6. **Regular Updates**: Keep user data updated for accurate targeting