Chats

Link to swagger documentation

A Chat is a conversation thread between a Seller and a Buyer regarding a specific Order and Category.

Only one Chat can exist for a given combination of orderId and categoryId.

Retrieve Chat Categories
Check Emails existence
Initiate a Chat
Retrieve list of Chats
Retrieve list of Chats for a specific Order
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": []
        }
      ]
    }
  ]
}

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.

Optional headers:

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.

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.

Request:

POST https://service-message-center.sandbox.infra.metro-markets.cloud/openapi/v1/orders/9e159b23-5585-4482-b078-9a9e1db2b252/chats

request Body:

{
  "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",
    "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",
    "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.
- CLOSED: Can be set either by Buyer action or by System automation, eg. due to inactivity.
isSeen, false if Chat contains at least 1 Message with field "seenAt": null, for "senderUserType": "SELLER".
A Chat is unique for each organization.id, order.id, and category.id combination.

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 headers:

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

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",
      "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",
      "unseenMessagesCount": 0
    }
  ],
  "message": "[15] chats have been fetched successfully",
  "metadata": {
    "limit": 15,
    "offset": 21,
    "total": 57
  },
  "status": "success"
}

Retrieve list of Chats for a specific Order

To retrieve all chats for a specific Order, a GET request to /openapi/v1/orders/{orderId}/chats can be made.

Optional headers:

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:

GET https://service-message-center.sandbox.infra.metro-markets.cloud/openapi/v1/orders/4cff7a94-224c-45e4-8187-6d978e3afab5/chats

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",
      "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",
      "unseenMessagesCount": 0
    }
  ],
  "message": "Chats for orderId [4cff7a94-224c-45e4-8187-6d978e3afab5] have been fetched successfully",
  "metadata": [],
  "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.

Optional headers:

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:

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",
        "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",
        "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.