Skip to main content

​
Base URL

The TelegrmBot API is built with Spring Boot and runs on: 
http://localhost:8080
For production deployments, replace localhost:8080 with your deployed server URL.

​
Authentication

The API uses JWT (JSON Web Token) authentication for protected endpoints:
  • Public endpoints: /auth/register and /auth/login do not require authentication
  • Protected endpoints: All /api/* endpoints require a valid JWT token in the Authorization header

​
Authorization Header Format

Authorization: Bearer <your-jwt-token>
To obtain a JWT token:
  1. Register a new user via POST /auth/register
  2. Login with your credentials via POST /auth/login
  3. Use the returned token in subsequent requests
The JWT token expires after 24 hours (86400000 milliseconds).

​
API Structure

The API is organized into two main sections:

​
Authentication (/auth)

  • User registration and login
  • JWT token generation
  • No authentication required

​
Conversations (/api/conversations)

  • List all Telegram conversations
  • Retrieve messages from specific conversations
  • Send messages to Telegram chats
  • Requires authentication

​
Response Format

All API responses use JSON format with consistent structures.

​
Success Response

Successful requests return the appropriate HTTP status code with a JSON body: 
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "email": "[email protected]",
  "name": "John Doe"
}

​
Error Response

Errors follow a standardized format: 
{
  "message": "Error category",
  "details": "Detailed error description or validation errors"
}
For validation errors, details contains a map of field names to error messages: 
{
  "message": "Validation Failed",
  "details": {
    "email": "Invalid email format",
    "password": "Password must be at least 6 characters long"
  }
}

​
HTTP Status Codes

The API uses standard HTTP status codes:
Status CodeMeaningDescription
200OKRequest succeeded
201CreatedResource created successfully
400Bad RequestInvalid input data or malformed JSON
401UnauthorizedMissing or invalid authentication token
404Not FoundResource not found
409ConflictResource already exists (e.g., duplicate email)
500Internal Server ErrorUnexpected server error

​
Common Error Scenarios

​
Authentication Errors

Missing Token 
{
  "message": "Authentication Failed",
  "details": "JWT token is missing or invalid"
}
Invalid Credentials 
{
  "message": "Authentication Failed",
  "details": "Invalid email or password"
}

​
Validation Errors

Invalid Input 
{
  "message": "Validation Failed",
  "details": {
    "email": "Email is required",
    "password": "Password is required"
  }
}
Malformed JSON 
{
  "message": "Malformed Request",
  "details": "Required request body is missing or unreadable."
}

​
Interactive API Documentation

The API includes Swagger UI for interactive documentation and testing: 
http://localhost:8080/swagger-ui.html
Use Swagger UI to explore endpoints, view detailed schemas, and test API calls directly from your browser.

​
Rate Limiting

Currently, the API does not enforce rate limiting. This may change in future versions.

​
Versioning

The current API version is v1. The API does not use explicit versioning in the URL path at this time.

​
Content Type

All requests and responses use application/json content type: 
Content-Type: application/json

​
Next Steps

Authentication

Learn how to register users and obtain JWT tokens

Conversations

Manage Telegram conversations and retrieve messages

Messages

Send messages to Telegram chats

Build docs developers (and LLMs) love

Get started for freeTalk to us