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 Categories
Retrieve Chat Subjects
Check Emails existence
Initiate a Chat
Retrieve list of Chats
Retrieve Chats with unseen Messages

Retrieve Chat Categories

Chat Categories must be known, before initiating a Chat. To retrieve the list of all available ones, a GET request can be made to /openapi/v1/chat-categories.

Request:

GET https://service-message-center.sandbox.infra.metro-markets.cloud/openapi/v1/chat-categories

Response:

{
  "status": "success",
  "message": "Chat categories have been fetched successfully",
  "data": [
    {
      "id": 200,
      "key": "POST-PURCHASE",
      "parentId": null,
      "translations": [
        {
          "en": "Post-purchase",
          "de": "Nach dem Kauf"
        }
      ],
      "children": [
        {
          "id": 210,
          "key": "ORDER",
          "parentId": 200,
          "translations": [
            {
              "en": "Order",
              "de": "Bestellung"
            }
          ],
          "children": []
        }
      ]
    }
  ]
}

Retrieve Chat Subjects

This API EP will be deprecated soon. Use Chat Categories instead

To retrieve the list of all available ones, 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.
categoryId from the Chat Categories in the request Body.
- Only IDs from categories with an empty children array (“leaf” nodes) can be used.
subject from the Chat Subjects can be included instead of categoryId for backward compatibility 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.
- If both category and subject are provided, category will be used to determine the Chat’s category and subject, while the subject field will be ignored.
  - Each category corresponds to a specific subject, as defined in the Chat Categories and Subjects data.
  - For backward compatibility purposes A custom subject will be created for the Chat based on the category’s key and translations, regardless of the isCustom value of the corresponding subject.

Optional fields:

Accept-Language header can be used to specify the preferred language for the response’s Chat category. Supported values are listed in chat categories' translations field (en, de, fr, it, es, pt, nl, hr). If not provided, it defaults to en.

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": "Invoice correction request",
  "categoryId": 242
}

Response:

A 201 Created response will be received containing the details of the newly created Chat, including its unique id.

{
  "data": {
    "buyer": {
      "firstName": "Quality Business",
      "id": "7cc2d1d0-bf2c-4af6-89c0-01fbb24a436a",
      "lastName": "Valid Vies"
    },
    "category": {
      "id": 211,
      "locale": "en",
      "name": "Order status",
      "parent": {
        "id": 210,
        "name": "Order"
      }
    },
    "createdAt": "2025-09-02T19:41:12+00:00",
    "customSubject": null,
    "id": "9fc8aac4-6fce-43f2-b230-0b372097729b",
    "isSeen": true,
    "lastMessageAt": "2025-09-02T19:41:12+00:00",
    "order": {
      "id": "4cff7a94-224c-45e4-8187-6d978e3afab5",
      "orderNumber": "O25-568200129071",
      "salesChannel": "pt"
    },
    "seller": {
      "accounts": [
        {
          "firstName": "Test",
          "id": "18461e1b-d845-4587-8ecb-90ba8838fc6e",
          "lastName": "Metro"
        }
      ],
      "organization": {
        "id": "581c41ea-6bc5-4716-a325-4a803c0ebff0",
        "shopName": "My DESHOP"
      }
    },
    "status": "WAITING_FOR_BUYER",
    "subject": "SELLER.ORDERS.ORDER_CONFIRMATION",
    "unseenMessagesCount": 0
  },
  "message": "Chat [9fc8aac4-6fce-43f2-b230-0b372097729b] has been created successfully",
  "metadata": [],
  "status": "success"
}

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:

Translations:

Accept-Language header can be used to specify the preferred language for the response’s Chat category. Supported values are listed in chat categories' translations field (en, de, fr, it, es, pt, nl, hr). If not provided, it defaults to en.

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[isSeen]: Filter by read status. Use 1 for seen chats and 0 for chats with unread messages.
filters[destinations][]: Filter by one or more country codes (e.g., filters[destinations][]=de&filters[destinations][]=fr).
filters[statuses][]: Filter by one or more Chat statuses (e.g., filters[statuses][]=DRAFT&filters[statuses][]=WAITING_FOR_SELLER).
filters[lastMessage][from]: Filters for chats where the last message was sent at or after this timestamp. The value must be in RFC 3339 format (e.g., 2025-09-02T19:41:12+00:00). If filters[lastMessage][to] is not provided, it defaults to the current time.
filters[lastMessage][to]: Filters for chats where the last message was sent at or before this timestamp. The value must be in RFC 3339 format (e.g., 2025-09-03T10:00:00+00:00).

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

Optional fields:

Translations:

Accept-Language header can be used to specify the preferred language for the response’s Chat category. Supported values are listed in chat categories' translations field (en, de, fr, it, es, pt, nl, hr). If not provided, it defaults to en.

Response:

{
  "data": [
    {
      "buyer": {
        "firstName": "Quality Business",
        "id": "7cc2d1d0-bf2c-4af6-89c0-01fbb24a436a",
        "lastName": "Valid Vies"
      },
      "category": {
        "id": 211,
        "locale": "en",
        "name": "Order status",
        "parent": {
          "id": 210,
          "name": "Order"
        }
      },
      "createdAt": "2025-09-02T19:41:12+00:00",
      "customSubject": null,
      "id": "9fc8aac4-6fce-43f2-b230-0b372097729b",
      "isSeen": true,
      "lastMessageAt": "2025-09-02T19:41:12+00:00",
      "order": {
        "id": "4cff7a94-224c-45e4-8187-6d978e3afab5",
        "orderNumber": "O25-568200129071",
        "salesChannel": "pt"
      },
      "seller": {
        "accounts": [
          {
            "firstName": "Test",
            "id": "18461e1b-d845-4587-8ecb-90ba8838fc6e",
            "lastName": "Metro"
          }
        ],
        "organization": {
          "id": "581c41ea-6bc5-4716-a325-4a803c0ebff0",
          "shopName": "My DESHOP"
        }
      },
      "status": "WAITING_FOR_BUYER",
      "subject": "SELLER.ORDERS.ORDER_CONFIRMATION",
      "unseenMessagesCount": 0
    }
  ],
  "message": "[15] chats have been fetched successfully",
  "metadata": {
    "limit": 15,
    "offset": 21,
    "total": 57
  },
  "status": "success"
}

Retrieve Chats with unseen Messages

To retrieve all chats containing at least one unseen message from the seller, along with the total count, a GET request to /openapi/v1/chats/unseen can be made.

Request:

GET https://service-message-center.sandbox.infra.metro-markets.cloud/openapi/v1/chats/unseen

Response:

{
  "data": {
    "chats": [
      {
        "buyer": {
          "firstName": "Quality Business",
          "id": "7cc2d1d0-bf2c-4af6-89c0-01fbb24a436a",
          "lastName": "Valid Vies"
        },
        "category": {
          "id": 211,
          "locale": "en",
          "name": "Order status",
          "parent": {
            "id": 210,
            "name": "Order"
          }
        },
        "createdAt": "2025-09-02T19:41:12+00:00",
        "customSubject": null,
        "id": "9fc8aac4-6fce-43f2-b230-0b372097729b",
        "isSeen": true,
        "lastMessageAt": "2025-09-02T19:41:12+00:00",
        "order": {
          "id": "4cff7a94-224c-45e4-8187-6d978e3afab5",
          "orderNumber": "O25-568200129071",
          "salesChannel": "pt"
        },
        "seller": {
          "accounts": [
            {
              "firstName": "Test",
              "id": "18461e1b-d845-4587-8ecb-90ba8838fc6e",
              "lastName": "Metro"
            }
          ],
          "organization": {
            "id": "581c41ea-6bc5-4716-a325-4a803c0ebff0",
            "shopName": "My DESHOP"
          }
        },
        "status": "WAITING_FOR_BUYER",
        "subject": "SELLER.ORDERS.ORDER_CONFIRMATION",
        "unseenMessagesCount": 0
      }
    ],
    "count": 1
  },
  "message": "[1] chats with unseen messages have been fetched successfully",
  "status": "success"
}

count: Total number of chats with unseen messages.
chats: An array of Chat objects where at least one message from the seller is unseen.