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.

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

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

GET /api/v1/users/:id

Create User

Create a new user.

POST /api/v1/users

Request Body

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

PUT /api/v1/users/:id

Request Body

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

Delete User

Delete a user.

DELETE /api/v1/users/:id

Bulk Update Users

Update multiple users at once.

POST /api/v1/users/bulk-update

Request Body

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

Import Users

Import users from CSV.

POST /api/v1/users/import

Request

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

Example CSV Format

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.

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.

GET /api/v1/groups

Response

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

POST /api/v1/groups

Request Body (Static Group)

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

Request Body (Dynamic Group)

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

PUT /api/v1/groups/:id

Delete Group

Delete a group.

DELETE /api/v1/groups/:id

Add Users to Group

Add users to a static group.

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

Request Body

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

Remove Users from Group

Remove users from a static group.

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

Recalculate Dynamic Group

Manually trigger recalculation of a dynamic group.

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

Tag Endpoints

List Tags

Get all tags.

GET /api/v1/tags

Query Parameters

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

Response

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

POST /api/v1/tags

Request Body

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

Update Tag

Update tag information.

PUT /api/v1/tags/:id

Delete Tag

Delete a tag.

DELETE /api/v1/tags/:id

Merge Tags

Merge multiple tags into one.

POST /api/v1/tags/merge

Request Body

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

Segment Endpoints

List Segments

Get all segments.

GET /api/v1/segments

Response

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

POST /api/v1/segments

Request Body

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

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

Response

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

Export Segment Users

Export users in a segment.

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

Clone Segment

Create a copy of a segment.

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

Statistics Endpoints

User Statistics

Get user statistics.

GET /api/v1/users-stats

Response

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

GET /api/v1/groups-stats

Tag Statistics

Get tag usage statistics.

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