Messages API

Endpoints for claim messages and real-time communication.

List Claim Messages

Get all messages for a specific claim.

GET /api/claims/{claimId}/messages

Response:

[
  {
    "id": "1",
    "senderId": "5",
    "senderName": "John Doe",
    "senderEmail": "john@example.com",
    "senderProfilePicture": "/api/user/profile-picture/abc.jpg",
    "message": "Hello, I have an issue with my product.",
    "createdAt": "2024-01-15T10:30:00+00:00",
    "isRead": true,
    "readAt": "2024-01-15T10:35:00+00:00",
    "attachment": null
  },
  {
    "id": "2",
    "senderId": "10",
    "senderName": "Support Team",
    "senderEmail": "support@company.com",
    "senderProfilePicture": null,
    "message": "We'll look into this right away.",
    "createdAt": "2024-01-15T11:00:00+00:00",
    "isRead": false,
    "readAt": null,
    "attachment": {
      "filename": "guide.pdf",
      "mimeType": "application/pdf",
      "size": 102400,
      "url": "/api/claims/1/messages/2/attachment"
    }
  }
]

Send Message

Send a new message in a claim conversation.

POST /api/claims/{claimId}/messages

Request Body:

{
  "message": "Here is my response to your inquiry.",
  "attachment": {
    "dataUrl": "base64-encoded-data",
    "fileName": "receipt.jpg",
    "mimeType": "image/jpeg",
    "size": 51200
  }
}

Field	Type	Required	Description
message	string	No*	Message text
attachment	object	No*	Attachment data

*At least one of message or attachment is required.

Response: 201 Created

{
  "id": "3",
  "senderId": "5",
  "senderName": "John Doe",
  "senderEmail": "john@example.com",
  "message": "Here is my response to your inquiry.",
  "createdAt": "2024-01-15T12:00:00+00:00",
  "isRead": false,
  "readAt": null
}

Notifications

When a message is sent:

1. Push notification is sent to the recipient
2. Email notification is sent (if enabled)
3. Real-time update via Mercure

Download Attachment

Download a message attachment.

GET /api/claims/{claimId}/messages/{messageId}/attachment

Response: Binary file with appropriate content-type header.

Mark Messages as Read

Mark all messages in a claim as read for the current user.

POST /api/claims/{claimId}/messages/read

Response:

{
  "markedAsRead": 5,
  "messageIds": ["1", "2", "3", "4", "5"]
}

List All Messages (Admin)

Get all messages across all claims.

GET /api/messages

Query Parameters:

Parameter	Type	Description
page	int	Page number
limit	int	Items per page
claimId	int	Filter by claim
senderId	int	Filter by sender
unread	boolean	Filter unread only

Admin Only

This endpoint requires ROLE_ADMIN.

Real-time Updates

Messages support real-time updates via Mercure.

Subscribe to Messages

Subscribe to the Mercure topic for a claim:

const url = new URL('https://mercure.example.com/hub');
url.searchParams.append('topic', `claims/${claimId}/messages`);

const eventSource = new EventSource(url, {
  withCredentials: true
});

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);

  if (data.type === 'new_message') {
    // Handle new message
    console.log('New message:', data.message);
  }

  if (data.type === 'messages_read') {
    // Handle read status update
    console.log('Messages marked as read:', data.messageIds);
  }
};

Event Types

Type	Description	Payload
new_message	New message received	{ type, message }
messages_read	Messages marked as read	{ type, messageIds, readAt }

Email Reply Integration

Messages can be received via email reply:

1. Email notifications include a Reply-To address: claim+{claimId}@domain.com
2. When user replies to email, it's processed as a new message
3. The reply is added to the claim conversation

Email Processing

Inbound emails are processed via webhook from Resend. The system extracts the reply text and strips quoted content.