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 thecustomSubject
field 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 istrue
if 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:
orderId
in the URL.subject
from the Chat Subjects in the request Body.- Only subjects from the
SELLER
user type can be used. - Only subjects with an empty
children
array (“leaf” nodes) can be used. - If a
subject
is used havingisCustom
field set totrue
(like"OTHERS"
), a value for thecustomSubject
field 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
,false
if Chat contains at least 1 Message with field"seenAt": null,
for"senderUserType": "SELLER"
.- A
Chat
is unique for eachorganization.id
andorder.id
pair.
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"]
).
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": []
}