Overview The Conversations API allows you to list all Telegram conversations initiated with the bot and retrieve messages from specific conversations.
All conversation endpoints require authentication. Include a valid JWT token in the Authorization header.
List All Conversations curl -X GET http://localhost:8080/api/conversations \ -H "Authorization: Bearer YOUR_JWT_TOKEN"
Retrieves a summary list of all Telegram conversations initiated with the bot.
Endpoint Bearer token for authentication Authorization: Bearer <your-jwt-token>
Response Returns an array of conversation summary objects.
Show ConversationSummaryDto
Unique identifier for the conversation (Telegram chat ID)
Name of the Telegram user (username if available, otherwise first name)
Timestamp of the last message in ISO-8601 format Example: 2024-03-15T10:30:45
Success Response (200 OK) [ { "id" : "123456789" , "participantName" : "JohnDoe" , "lastMessageAt" : "2024-03-15T10:30:45" }, { "id" : "987654321" , "participantName" : "Jane Smith" , "lastMessageAt" : "2024-03-14T15:22:10" } ]
Error Responses
401 Unauthorized - Missing or Invalid Token
{ "message" : "Authentication Failed" , "details" : "JWT token is missing or invalid" }
Get Conversation Messages curl -X GET http://localhost:8080/api/conversations/123456789/messages \ -H "Authorization: Bearer YOUR_JWT_TOKEN"
Retrieves the complete list of messages for a specific conversation, ordered by date.
Endpoint GET /api/conversations/{id}/messages
Path Parameters The conversation ID (Telegram chat ID) Example: 123456789
Bearer token for authentication Authorization: Bearer <your-jwt-token>
Response Returns an array of message objects ordered chronologically.
Unique identifier for the message (UUID format)
The text content of the message
Message direction:
INCOMING: Message received from Telegram userOUTGOING: Message sent by the bot or admin Show MessageDirection Enum
public enum MessageDirection { INCOMING , OUTGOING }
Source: Message.java:48 Timestamp when the message was sent (ISO-8601 format) Example: 2024-03-15T10:30:45
Success Response (200 OK) [ { "id" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "content" : "Hello! How can I help you?" , "direction" : "INCOMING" , "sentAt" : "2024-03-15T10:28:30" }, { "id" : "b2c3d4e5-f6a7-8901-bcde-f12345678901" , "content" : "This is a response from the AI bot" , "direction" : "OUTGOING" , "sentAt" : "2024-03-15T10:28:35" }, { "id" : "c3d4e5f6-a7b8-9012-cdef-123456789012" , "content" : "Thanks! That was helpful." , "direction" : "INCOMING" , "sentAt" : "2024-03-15T10:30:45" } ]
Error Responses
401 Unauthorized - Missing or Invalid Token
{ "message" : "Authentication Failed" , "details" : "JWT token is missing or invalid" }
404 Not Found - Conversation Not Found
{ "message" : "Resource Not Found" , "details" : "Conversation with ID '123456789' could not be found." }
Message Direction Flow Understanding message directions:
INCOMING Messages
Messages sent by Telegram users to the bot. These trigger the AI response system.
OUTGOING Messages
Messages sent from the bot to Telegram users. Can be:
AI-generated responses (automatic)
Admin-initiated messages (via API)
The current API version does not implement pagination. All messages for a conversation are returned in a single response. This may be added in future versions for conversations with large message histories.
Source Code References
Controller : ConversationController.java:44 (list conversations), ConversationController.java:58 (get messages)DTOs :
ConversationSummaryDto.java:5 - Conversation summary structureMessageDto.java:6 - Message structure
Domain Model : Message.java:48 - MessageDirection enum
Next Steps
Send Messages Learn how to send messages to conversations
Authentication Review authentication requirements
