telegram-management-system/marketing-agent/docs/api

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

   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

   curl -X GET http://localhost:3000/api/v1/campaigns \
     -H "Authorization: Bearer <your-token>"
   

API Documentation Sections

Core Services

1. Authentication API - User authentication and session management
2. Campaigns API - Campaign creation and management
3. Analytics API - Real-time analytics and reporting
4. Users API - User management and segmentation

Marketing Features

5. Templates API - Message template management
6. Scheduled Campaigns API - Campaign scheduling
7. A/B Testing API - A/B test management
8. Workflows API - Marketing automation workflows

Integration Services

9. Webhooks API - Webhook integration management
10. Translations API - Multi-language support
11. AI API - Claude AI integration for smart suggestions

System Management

12. Accounts API - Telegram account management
13. Compliance API - Compliance checking
14. Settings API - 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:

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

SDKs and Libraries

• Node.js SDK
• Python SDK
• PHP SDK

Support

• API Status: http://localhost:3000/health
• Contact: api-support@yourcompany.com
• GitHub: https://github.com/yourusername/telegram-marketing-agent