Overview The Messages API allows administrators to proactively send messages to Telegram conversations. This is useful for:
Broadcasting announcements to users
Initiating conversations without waiting for user input
Sending notifications or updates
Testing bot responses
This endpoint requires authentication. Include a valid JWT token in the Authorization header.
Send Message to Conversation cURL
cURL with Authentication Flow
Java Controller
curl -X POST http://localhost:8080/api/conversations/123456789/messages \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "content": "Hello! This is a message from the admin panel." }'
Sends a message from the admin to a specific Telegram conversation.
Endpoint POST /api/conversations/{id}/messages
Path Parameters The conversation ID (Telegram chat ID) to send the message to Example: 123456789 Show How to get conversation IDs
Use the GET /api/conversations endpoint to retrieve all conversation IDs: curl -X GET http://localhost:8080/api/conversations \ -H "Authorization: Bearer YOUR_JWT_TOKEN"
Bearer token for authentication Authorization: Bearer <your-jwt-token>
Request Body The message text to send to the Telegram conversation
Cannot be blank or empty
Must contain at least one non-whitespace character
No maximum length restriction (limited by Telegram’s 4096 character limit)
Request Example { "content" : "Hello! This is a proactive message from the admin panel. How can we help you today?" }
Response On success, returns an empty response body with HTTP 200 status.
Success Response (200 OK) No response body is returned. The message has been successfully sent to the Telegram chat.
The message will be delivered to the Telegram user in real-time via the bot. The message is also stored in the database and will appear in the conversation history with direction OUTGOING.
Error Responses
400 Bad Request - Validation Failed
Returned when the message content is empty or invalid. { "message" : "Validation Failed" , "details" : { "content" : "Content cannot be blank" } }
400 Bad Request - Malformed JSON
401 Unauthorized - Missing or Invalid Token
Returned when authentication token is missing or expired. { "message" : "Authentication Failed" , "details" : "JWT token is missing or invalid" }
404 Not Found - Conversation Not Found
Returned when the specified conversation ID doesn’t exist. { "message" : "Resource Not Found" , "details" : "Conversation with ID '123456789' could not be found." }
Message Flow When you send a message via this endpoint:
API Receives Request
Your authenticated request is validated and processed
Message Stored
The message is saved to the database with direction OUTGOING
Telegram Delivery
The message is sent to the Telegram user via the Bot API
User Receives Message
The Telegram user sees your message in their chat
Complete Example: Send Message Workflow Here’s a complete workflow showing how to authenticate and send a message:
Complete Workflow
JavaScript/Node.js
Python
#!/bin/bash # Step 1: Register (if needed) curl -X POST http://localhost:8080/auth/register \ -H "Content-Type: application/json" \ -d '{ "name": "Admin User", "email": "[email protected] ", "password": "securepass123" }' # Step 2: Login and capture token TOKEN = $( curl -s -X POST http://localhost:8080/auth/login \ -H "Content-Type: application/json" \ -d '{ "email": "[email protected] ", "password": "securepass123" }' | jq -r '.token' ) echo "Token: $TOKEN " # Step 3: List conversations to get IDs echo "\nAvailable conversations:" curl -s -X GET http://localhost:8080/api/conversations \ -H "Authorization: Bearer $TOKEN " \ | jq '.' # Step 4: Send message to specific conversation CONV_ID = "123456789" # Replace with actual conversation ID curl -X POST http://localhost:8080/api/conversations/ $CONV_ID /messages \ -H "Authorization: Bearer $TOKEN " \ -H "Content-Type: application/json" \ -d '{ "content": "Hello from the admin panel!" }' echo "\nMessage sent successfully!"
Use Cases
Broadcast Announcements Send important updates to all or specific users
Proactive Support Reach out to users without waiting for them to message first
Notifications Alert users about events, deadlines, or changes
Testing Test bot responses and conversation flows
Best Practices Keep messages concise : While Telegram supports messages up to 4096 characters, shorter messages tend to have better engagement.
Avoid spam : Sending too many unsolicited messages may lead to users blocking your bot. Use this feature responsibly.
Message delivery : Messages are sent asynchronously to Telegram. A successful API response (200 OK) means the message was accepted and queued for delivery, not that it was necessarily delivered to the user.
Source Code References
Controller : ConversationController.java:72 (send message endpoint)DTO : SendMessageRequest.java:5 (request structure)Domain Model : Message.java:23 (message creation logic)
Next Steps
View Conversations List conversations and view message history
Authentication Learn about JWT token authentication
