Messages API
Send and receive messages between buyers and sellers.
Endpoints Overview
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| GET | /api/messages | List all message threads | Required |
| GET | /api/messages/unread | Get unread message count | Required |
| GET | /api/messages/:threadId | Get messages in thread | Required |
| POST | /api/messages | Send a message | Required |
| PATCH | /api/messages/:threadId/archive | Archive a thread | Required |
Notification Endpoints
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| GET | /api/notifications | List notifications | Required |
| GET | /api/notifications/unread-count | Get unread count | Required |
| PATCH | /api/notifications/:id/read | Mark as read | Required |
| PATCH | /api/notifications/read-all | Mark all as read | Required |
List Conversations
Get all conversations for the authenticated user.
Request
bash
GET /v1/messages/conversations
Authorization: Bearer YOUR_JWT_TOKEN1
2
2
Query Parameters
| Parameter | Type | Description |
|---|---|---|
page | integer | Page number |
limit | integer | Items per page |
status | string | all, unread, read, archived |
role | string | buyer, seller (for sellers) |
Response
json
{
"success": true,
"data": {
"conversations": [
{
"id": "conv_123",
"listing": {
"id": "lst_abc",
"title": "2021 Volvo FH 500",
"thumbnail": "https://cdn.menonmobility.com/thumb.jpg",
"price": 85000,
"status": "active"
},
"participant": {
"id": "usr_456",
"name": "John Smith",
"avatar": "https://cdn.menonmobility.com/avatar.jpg",
"type": "buyer",
"verified": true
},
"last_message": {
"content": "Is this vehicle still available?",
"sender": "usr_456",
"sent_at": "2024-01-15T14:30:00Z",
"read": false
},
"unread_count": 2,
"created_at": "2024-01-15T10:00:00Z",
"updated_at": "2024-01-15T14:30:00Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 45
},
"summary": {
"total": 45,
"unread": 8
}
}
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
Get Conversation
Get messages in a specific conversation.
Request
bash
GET /v1/messages/conversations/conv_123
Authorization: Bearer YOUR_JWT_TOKEN1
2
2
Query Parameters
| Parameter | Type | Description |
|---|---|---|
page | integer | Page number |
limit | integer | Messages per page |
before | string | Messages before timestamp |
Response
json
{
"success": true,
"data": {
"conversation": {
"id": "conv_123",
"listing": {
"id": "lst_abc",
"title": "2021 Volvo FH 500",
"thumbnail": "https://cdn.menonmobility.com/thumb.jpg",
"price": 85000,
"status": "active"
},
"participant": {
"id": "usr_456",
"name": "John Smith",
"type": "buyer",
"verified": true,
"online": true
}
},
"messages": [
{
"id": "msg_1",
"content": "Hello, I'm interested in this truck.",
"sender_id": "usr_456",
"type": "text",
"read": true,
"read_at": "2024-01-15T10:05:00Z",
"sent_at": "2024-01-15T10:00:00Z"
},
{
"id": "msg_2",
"content": "Hi! Yes, it's still available. Would you like to schedule a viewing?",
"sender_id": "usr_me",
"type": "text",
"read": true,
"read_at": "2024-01-15T10:12:00Z",
"sent_at": "2024-01-15T10:10:00Z"
},
{
"id": "msg_3",
"content": "Is this vehicle still available?",
"sender_id": "usr_456",
"type": "text",
"read": false,
"sent_at": "2024-01-15T14:30:00Z"
}
],
"pagination": {
"page": 1,
"limit": 50,
"total": 3,
"has_more": false
}
}
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
Start Conversation
Start a new conversation about a listing.
Request
bash
POST /v1/messages/conversations
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json1
2
3
2
3
Body
json
{
"listing_id": "lst_abc123",
"message": "Hello, I'm interested in this vehicle. Is it still available?"
}1
2
3
4
2
3
4
Response
json
{
"success": true,
"data": {
"conversation": {
"id": "conv_new123",
"listing": {
"id": "lst_abc123",
"title": "2021 Volvo FH 500"
},
"participant": {
"id": "sel_789",
"name": "ABC Trucks"
},
"created_at": "2024-01-15T15:00:00Z"
},
"message": {
"id": "msg_1",
"content": "Hello, I'm interested in this vehicle. Is it still available?",
"sent_at": "2024-01-15T15:00:00Z"
}
}
}1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
Send Message
Send a message in an existing conversation.
Request
bash
POST /v1/messages/conversations/conv_123
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json1
2
3
2
3
Body
json
{
"content": "Thank you for your interest! Yes, it's available.",
"type": "text"
}1
2
3
4
2
3
4
Message Types
| Type | Description |
|---|---|
text | Plain text message |
image | Image attachment |
document | Document attachment |
quick_reply | Template response |
Send with Attachment
bash
POST /v1/messages/conversations/conv_123
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: multipart/form-data
content: Here are the service records
type: document
attachment: [file]1
2
3
4
5
6
7
2
3
4
5
6
7
Response
json
{
"success": true,
"data": {
"message": {
"id": "msg_new",
"content": "Thank you for your interest! Yes, it's available.",
"type": "text",
"sent_at": "2024-01-15T15:05:00Z"
}
}
}1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
Mark as Read
Mark conversation or specific messages as read.
Mark Conversation Read
bash
PUT /v1/messages/conversations/conv_123/read
Authorization: Bearer YOUR_JWT_TOKEN1
2
2
Mark Specific Messages
bash
PUT /v1/messages/conversations/conv_123/read
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json
{
"message_ids": ["msg_1", "msg_2", "msg_3"]
}1
2
3
4
5
6
7
2
3
4
5
6
7
Archive Conversation
Archive
bash
PUT /v1/messages/conversations/conv_123/archive
Authorization: Bearer YOUR_JWT_TOKEN1
2
2
Unarchive
bash
DELETE /v1/messages/conversations/conv_123/archive
Authorization: Bearer YOUR_JWT_TOKEN1
2
2
Delete Conversation
bash
DELETE /v1/messages/conversations/conv_123
Authorization: Bearer YOUR_JWT_TOKEN1
2
2
WARNING
Deletion is permanent and cannot be undone.
Message Templates
List Templates
bash
GET /v1/messages/templates
Authorization: Bearer YOUR_JWT_TOKEN1
2
2
Response
json
{
"success": true,
"data": {
"templates": [
{
"id": "tpl_1",
"name": "Vehicle Available",
"category": "inquiry",
"content": "Thank you for your interest in the {{vehicle_title}}. Yes, it is still available at {{price}}. Would you like to schedule a viewing?"
}
]
}
}1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
Create Template
bash
POST /v1/messages/templates
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json
{
"name": "Quick Response",
"category": "inquiry",
"content": "Thank you for contacting us..."
}1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
Use Template
bash
POST /v1/messages/conversations/conv_123
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json
{
"template_id": "tpl_1",
"variables": {
"vehicle_title": "2021 Volvo FH 500",
"price": "EUR 85,000"
}
}1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
Unread Count
Get Unread Count
bash
GET /v1/messages/unread
Authorization: Bearer YOUR_JWT_TOKEN1
2
2
Response
json
{
"success": true,
"data": {
"unread_count": 8,
"conversations_with_unread": 3
}
}1
2
3
4
5
6
7
2
3
4
5
6
7
Report Message
Report inappropriate messages.
bash
POST /v1/messages/msg_123/report
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json
{
"reason": "spam",
"details": "User is sending promotional content"
}1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
Webhooks
Subscribe to message events via webhooks. See Webhooks for details.
Events:
message.receivedmessage.readconversation.created