🚀 Chat Microservice API

Real-time messaging service for multiple Laravel Sanctum applications

📡 REST API Endpoints

Messages

GET /api/messages?user_id=123&other_user_id=456&limit=50

Get message history between two users (requires authentication)

Query Params: user_id, other_user_id, limit (optional, default: 50)

GET /api/messages/user/:user_id?limit=100&source=app1

Get all messages for a specific user (requires authentication)

Query Params: limit (optional, default: 100), source (optional)

Activity & Status

GET /api/activity/user/:user_id

Get user activity status (active, last_seen) 🔒 Requires Authorization

Headers: Authorization: Bearer <token>, X-Source: <source>

Response: { success, user_id, is_active, last_seen, typing_to_user_id }

PUT /api/activity/user/:user_id/active

Update current user's activity status 🔒 Requires Authorization

Headers: Authorization: Bearer <token>, X-Source: <source>

Body: { is_active: true/false }

⚠️ Authorization: User can only update their own activity status

POST /api/activity/messages/seen

Mark messages as seen 🔒 Requires Authorization

Headers: Authorization: Bearer <token>, X-Source: <source>

Body: { other_user_id: 123 }

Notifications

POST /api/notifications/send-to-user

Send push notification to a user 🔒 Requires Authorization

Headers: Authorization: Bearer <token>, X-Source: <source>

Body: { user_id: 123, title: "Title", body: "Body", data: {} }

Response: { success, message, user_id, total_devices, success_count, failure_count, results }

Example Request: { "user_id": 123, "title": "New Message", "body": "You have a new message", "data": { "sender_id": 456, "message_id": 789 } }

🖼️ Image Upload

POST /api/upload/image

Upload an image to use in a chat message 🔒 Requires Authorization

Headers: Authorization: Bearer <token>, X-Source: <source>

Body: multipart/form-data — field name: image

Allowed types: JPEG, PNG, GIF, WebP  |  Max size: 5 MB

Response: { success, image_url, filename, size, mimetype }

Step 1 — Upload image: POST /api/upload/image Content-Type: multipart/form-data Field: image = <file> Response: { "success": true, "image_url": "/uploads/chat_img_42_1234567890.jpg", "filename": "chat_img_42_1234567890.jpg", "size": 204800, "mimetype": "image/jpeg" } Step 2 — Send via socket: { to_user_id: 5, message_type: "image", image_url: "/uploads/chat_img_42_1234567890.jpg" }

System

GET /health

Health check endpoint

🔌 Socket.IO Events

Client → Server 🔒 All require Socket.IO authentication

send_message

Send a text or image message to another user 🔒 Authenticated

Auth: Token and source passed via socket.handshake.auth

// Text message: { to_user_id: 123, message: "Hello!", message_type: "text" } // Image message (upload first via POST /api/upload/image): { to_user_id: 123, message_type: "image", image_url: "/uploads/chat_img_42_xxx.jpg" }
get_message_history

Request message history between current user and another user 🔒 Authenticated

{ other_user_id: 456, limit: 50 }
mark_seen

Mark messages from another user as seen 🔒 Authenticated

{ other_user_id: 456 }
typing

Send typing indicator (is_typing: true to start, false to stop) 🔒 Authenticated

{ to_user_id: 123, is_typing: true }

Server → Client

receive_message

Receive a message (sent to both sender and receiver)

// Text message: { id, from_user_id, to_user_id, source, message, message_type: "text", image_url: null, created_at, seen_at, is_sent } // Image message: { id, from_user_id, to_user_id, source, message: "", message_type: "image", image_url: "/uploads/chat_img_42_xxx.jpg", created_at, seen_at, is_sent }
message_history

Receive message history in response to get_message_history

{ success, count, messages, user_id, other_user_id }
messages_seen

Notification that messages were seen by recipient

{ user_id, other_user_id, count }
user_typing

Notification that a user is typing

{ from_user_id, to_user_id, is_typing }
user_active

Notification about user activity status change

{ user_id, is_active, last_seen }
mark_seen_success

Confirmation that messages were marked as seen

{ success, count, other_user_id }
error

Error occurred during operation

{ message: "Error description" }

🔐 Authentication

All API endpoints require Bearer token authentication via Authorization header:

Headers: Authorization: Bearer <your-sanctum-token> X-Source: <app-source> OR Query Parameter: ?source=<app-source>

Example Request:

GET /api/activity/user/123 Headers: Authorization: Bearer 1|abc123def456... X-Source: blood_donation

⚠️ Without valid Authorization header, all requests will return 401 Unauthorized

📚 Full Documentation

See API_DOCUMENTATION.md for complete API documentation.