Initial commit: Telegram Management System
Some checks failed
Deploy / deploy (push) Has been cancelled
Some checks failed
Deploy / deploy (push) Has been cancelled
Full-stack web application for Telegram management - Frontend: Vue 3 + Vben Admin - Backend: NestJS - Features: User management, group broadcast, statistics 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
你的用户名
623
marketing-agent/docs/api/users-api.md
Normal file
623
marketing-agent/docs/api/users-api.md
Normal file
@@ -0,0 +1,623 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user