Chats
A Chat is a conversation thread between a Seller and a Buyer regarding a specific Order.
Each Chat is defined by a subject.
- Retrieve Chat Subjects
- Check Emails existence
- Initiate a Chat
- Retrieve list of Chats
- Count Chats with unseen Messages
Retrieve Chat Subjects
Chat Subjects must be known, before initiating a Chat.
To retrieve the list of all available Chat Subjects, a GET request can be made to /openapi/v1/chat-subjects.
Request:
GET https://service-message-center.sandbox.infra.metro-markets.cloud/openapi/v1/chat-subjects
Response:
{
"status": "success",
"message": "Chat Subjects have been fetched successfully",
"data": {
"SELLER": [
{
"id": 121,
"subject": "INVOICES",
"isCustom": false,
"parentId": null,
"children": [
{
"id": 221,
"subject": "INVOICE_INSTRUCTIONS",
"isCustom": false,
"parentId": 121,
"children": []
},
{
"id": 222,
"subject": "INVOICE_ATTACHMENT",
"isCustom": false,
"parentId": 121,
"children": []
}
]
},
{
"id": 135,
"subject": "OTHERS",
"isCustom": true,
"parentId": null,
"children": []
}
],
"BUYER": [
{
"id": 132,
"subject": "INVOICES",
"isCustom": false,
"parentId": null,
"children": [
{
"id": 241,
"subject": "INVOICE_NOT_UPLOADED",
"isCustom": false,
"parentId": 132,
"children": []
},
{
"id": 242,
"subject": "INVOICE_CORRECTION",
"isCustom": false,
"parentId": 132,
"children": []
}
]
}
]
},
"metadata": []
}
The response data is an object where subjects are grouped by User Type ( SELLER, BUYER).
Each Chat Subject has the following key properties:
isCustom: Iftrue, this is a customChat Subject(like"OTHERS") that requires thecustomSubjectfield when initiating a chat.parentId: If it isnull, this is a top-level “parent”. Otherwise, this is the “child” of theparentId.children: An array containing any nested “children” subjects.
Check Emails existence
To check for pre-existing email communication for an OrderNumber, a GET request can be made to /openapi/v1/orders/{{orderNumber}}/emails-exist.
Request:
GET https://service-message-center.sandbox.infra.metro-markets.cloud/openapi/v1/orders/{{orderNumber}}/emails-exist
Response:
{
"status": "success",
"message": "Successfully verified email existence for Order [O25-12345678910]",
"data": {
"exist": false
},
"metadata": []
}
exist: A boolean that istrueif email communication already exists for the givenorderNumber.- If
true, the Seller can choose to continue the email-based communication or initiate a new Chat.
- If
Initiate a Chat
To initiate a new Chat with the Buyer for a specific Order, a POST request to /openapi/v1/orders/{orderId}/chats can be made.
Mandatory fields:
orderIdin the URL.subjectfrom the Chat Subjects in the request Body.- Only subjects from the
SELLERuser type can be used. - Only subjects with an empty
childrenarray (“leaf” nodes) can be used. - If a
subjectis used havingisCustomfield set totrue(like"OTHERS"), a value for thecustomSubjectfield is also mandatory.
- Only subjects from the
Request:
POST https://service-message-center.sandbox.infra.metro-markets.cloud/openapi/v1/orders/9e159b23-5585-4482-b078-9a9e1db2b252/chats
request Body:
{
"subject": "OTHERS",
"customSubject": "Open API Custom Subject"
}
Response:
A 201 Created response will be received containing the details of the newly created Chat, including its unique id.
{
"status": "success",
"message": "Chat [9fd9e513-8284-4764-91f8-f4a818f2d549] has been created successfully",
"data": {
"id": "9fd9e513-8284-4764-91f8-f4a818f2d549",
"subject": "SELLER.OTHERS",
"customSubject": "Open API Custom Subject",
"status": "DRAFT",
"lastMessageAt": null,
"isSeen": true,
"createdAt": "2025-09-11T09:13:19+00:00",
"buyer": {
"id": "66fbf578-b711-3fdb-8124-7ebc01f2c038",
"lastName": "Stark",
"firstName": "Sibyl"
},
"seller": {
"organization": {
"id": "33981b0d-9bab-353d-902a-b09a7dd68ec7",
"shopName": "Kaia Borer"
},
"accounts": [
{
"id": "18461e1b-d845-4587-8ecb-90ba8838fc6e",
"firstName": "Test",
"lastName": "Metro"
}
]
},
"order": {
"id": "4819d952-3875-3df8-a36f-f02806b17869",
"orderNumber": "O94-324386732",
"salesChannel": "pt"
}
},
"metadata": []
}
status: The current state of the chat. Possible values are:DRAFT: The chat has been created but has no messages yet.WAITING_FOR_BUYER: The last message was sent by the Seller.WAITING_FOR_SELLER: The last message was sent by the Buyer.OVER_SLA: The Seller has not replied for over 48 hours.
isSeen,falseif Chat contains at least 1 Message with field"seenAt": null,for"senderUserType": "SELLER".- A
Chatis unique for eachorganization.idandorder.idpair.
Retrieve list of Chats
To retrieve a list of all chats, a GET request to /openapi/v1/chats can be made.
Query parameters can be optionally used to filter and paginate the results.
Optional fields:
Filters:
filters[orderNumber]: Filter by a specific Order number.filters[orderId]: Filter by a specific Order ID.filters[chatId]: Filter by a specific Chat ID.filters[destinations]: Filter by country codes (e.g.,["de", "fr"]).filters[isSeen]: Filter by read status. Use1for seen chats and0for chats with unread messages.
Pagination:
limit: Number of results per page (default: 20).offset: Number of results to skip.
Request:
GET https://service-message-center.sandbox.infra.metro-markets.cloud/openapi/v1/chats?limit=15&offset=21
Response:
{
"status": "success",
"message": "[15] chats have been fetched successfully",
"data": [
{
"id": "9fc8aac4-6fce-43f2-b230-0b372097729b",
"subject": "SELLER.ORDERS.ORDER_CONFIRMATION",
"customSubject": null,
"status": "WAITING_FOR_BUYER",
"lastMessageAt": "2025-09-02T19:41:12+00:00",
"isSeen": true,
"createdAt": "2025-09-02T19:41:12+00:00",
"buyer": {
"id": "7cc2d1d0-bf2c-4af6-89c0-01fbb24a436a",
"lastName": "Valid Vies",
"firstName": "Quality Business"
},
"seller": {
"organization": {
"id": "581c41ea-6bc5-4716-a325-4a803c0ebff0",
"shopName": "My DESHOP"
},
"accounts": [
{
"id": "18461e1b-d845-4587-8ecb-90ba8838fc6e",
"firstName": "Test",
"lastName": "Metro"
}
]
},
"order": {
"id": "4cff7a94-224c-45e4-8187-6d978e3afab5",
"orderNumber": "O25-568200129071",
"salesChannel": "pt"
}
}
],
"metadata": {
"total": 57,
"offset": 21,
"limit": 15
}
}
Count Chats with unseen Messages
To check for chats with unseen messages, a GET request can be made to /openapi/v1/chats/unseen.
A count of all chats that contain at least one unseen message will be retrieved.
Request:
GET https://service-message-center.sandbox.infra.metro-markets.cloud/openapi/v1/chats/unseen
Response:
{
"status": "success",
"message": "[3] chats with unseen messages have been found",
"data": {
"count": 3
},
"metadata": []
}