237c7802e5
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>
136 lines
3.6 KiB
Markdown
136 lines
3.6 KiB
Markdown
# Telegram Marketing Agent System API Documentation
|
|
|
|
## Overview
|
|
|
|
The Telegram Marketing Agent System provides a comprehensive REST API for managing marketing campaigns, user segmentation, message scheduling, and analytics. This documentation covers all available endpoints, authentication requirements, and usage examples.
|
|
|
|
## Base URL
|
|
|
|
```
|
|
http://localhost:3000/api/v1
|
|
```
|
|
|
|
## Authentication
|
|
|
|
All API endpoints (except login and public endpoints) require JWT authentication. Include the JWT token in the Authorization header:
|
|
|
|
```
|
|
Authorization: Bearer <your-jwt-token>
|
|
```
|
|
|
|
## Getting Started
|
|
|
|
1. **Login to get access token**
|
|
```bash
|
|
curl -X POST http://localhost:3000/api/v1/auth/login \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"username": "admin", "password": "password123"}'
|
|
```
|
|
|
|
2. **Use the token for subsequent requests**
|
|
```bash
|
|
curl -X GET http://localhost:3000/api/v1/campaigns \
|
|
-H "Authorization: Bearer <your-token>"
|
|
```
|
|
|
|
## API Documentation Sections
|
|
|
|
### Core Services
|
|
|
|
1. [Authentication API](./auth-api.md) - User authentication and session management
|
|
2. [Campaigns API](./campaigns-api.md) - Campaign creation and management
|
|
3. [Analytics API](./analytics-api.md) - Real-time analytics and reporting
|
|
4. [Users API](./users-api.md) - User management and segmentation
|
|
|
|
### Marketing Features
|
|
|
|
5. [Templates API](./templates-api.md) - Message template management
|
|
6. [Scheduled Campaigns API](./scheduled-campaigns-api.md) - Campaign scheduling
|
|
7. [A/B Testing API](./ab-testing-api.md) - A/B test management
|
|
8. [Workflows API](./workflows-api.md) - Marketing automation workflows
|
|
|
|
### Integration Services
|
|
|
|
9. [Webhooks API](./webhooks-api.md) - Webhook integration management
|
|
10. [Translations API](./translations-api.md) - Multi-language support
|
|
11. [AI API](./ai-api.md) - Claude AI integration for smart suggestions
|
|
|
|
### System Management
|
|
|
|
12. [Accounts API](./accounts-api.md) - Telegram account management
|
|
13. [Compliance API](./compliance-api.md) - Compliance checking
|
|
14. [Settings API](./settings-api.md) - System configuration
|
|
|
|
## Interactive API Explorer
|
|
|
|
Access the Swagger UI at: `http://localhost:3000/api-docs`
|
|
|
|
## Rate Limiting
|
|
|
|
- Default rate limit: 100 requests per minute per IP
|
|
- Authenticated users: 1000 requests per minute
|
|
- AI endpoints: 20 requests per minute
|
|
|
|
## Error Handling
|
|
|
|
All API errors follow a consistent format:
|
|
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": "Error message",
|
|
"code": "ERROR_CODE",
|
|
"details": {}
|
|
}
|
|
```
|
|
|
|
### Common Error Codes
|
|
|
|
- `400` - Bad Request
|
|
- `401` - Unauthorized
|
|
- `403` - Forbidden
|
|
- `404` - Not Found
|
|
- `429` - Too Many Requests
|
|
- `500` - Internal Server Error
|
|
|
|
## Pagination
|
|
|
|
List endpoints support pagination:
|
|
|
|
```
|
|
GET /api/v1/campaigns?page=1&limit=20&sort=-createdAt
|
|
```
|
|
|
|
- `page` - Page number (default: 1)
|
|
- `limit` - Items per page (default: 20, max: 100)
|
|
- `sort` - Sort field, prefix with `-` for descending
|
|
|
|
## Filtering
|
|
|
|
Most list endpoints support filtering:
|
|
|
|
```
|
|
GET /api/v1/campaigns?status=active&type=message
|
|
```
|
|
|
|
## Webhooks
|
|
|
|
Configure webhooks to receive real-time notifications:
|
|
|
|
1. Register webhook endpoint
|
|
2. Verify webhook signature
|
|
3. Handle webhook events
|
|
|
|
See [Webhooks API](./webhooks-api.md) for details.
|
|
|
|
## SDKs and Libraries
|
|
|
|
- [Node.js SDK](https://github.com/yourusername/tg-marketing-sdk-node)
|
|
- [Python SDK](https://github.com/yourusername/tg-marketing-sdk-python)
|
|
- [PHP SDK](https://github.com/yourusername/tg-marketing-sdk-php)
|
|
|
|
## Support
|
|
|
|
- API Status: `http://localhost:3000/health`
|
|
- Contact: api-support@yourcompany.com
|
|
- GitHub: https://github.com/yourusername/telegram-marketing-agent |