Chats

Link to swagger documentation

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: If true, this is a custom Chat Subject (like "OTHERS") that requires the customSubject field when initiating a chat.
parentId: If it is null, this is a top-level “parent”. Otherwise, this is the “child” of the parentId.
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 is true if email communication already exists for the given orderNumber.
- If true, the Seller can choose to continue the email-based communication or initiate a new Chat.

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 having isCustom field set to true (like "OTHERS"), a value for the customSubject field is also mandatory.

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 each organization.id and order.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"]).
filters[isSeen]: Filter by read status. Use 1 for seen chats and 0 for 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": []
}