[NEWS] Centrum wiadomości - rozszerzamy zasoby /messaging o obsługę Problemów z zakupem / Message Center - we are extending /messaging resources to support problems with purchases

W ramach prac nad ujednoliceniem obsługi komunikacji, rozszerzamy możliwości istniejących endpointów na ścieżce **/messaging** o obsługę nowego typu wątku w Centrum Wiadomości czyli Problemów z zakupem, które z czasem całkowicie zastąpią Dyskusje. Nowa struktura endpointów **/messaging** dostępna jest w wersji **beta.v1**.

Sprzedający na Allegro, którzy korzystają z Twoich rozwiązań, dostaną od nas osobną komunikację o tych zmianach. Poinformujemy ich o tym z odpowiednim wyprzedzeniem.

**Co zmieniliśmy?**

W ramach nowej struktury wybranych endpointów **/messaging** dostępnych w wersji **beta.v1**, wprowadziliśmy kilka istotnych zmian, które umożliwią zarządzanie nowymi **Problemami z zakupem**.

1. [GET /messaging/threads](https://developer.allegro.pl/documentation/#operation/listThreadsGET):

- pobierzesz teraz listę wątków, dla których **“type”**:

- COMMON - obejmuje dotychczasowe wątki,
- POST_PURCHASE_ISSUE - to Problemy z zakupem,
- zamiast parametrów **“offset”** i **“limit”** skorzystasz teraz z nowego parametru **“page.id”**. Rozwiązanie to eliminuje problemy wydajnościowe przy dużej liczbie wątków i wiadomości,
- dodaliśmy również parametry:
- **"read"** - określający czy wątek został odczytany; true - tak, false - nie,
- **"status"** - status wątku; dostępne wartości: OPEN, CLOSED,
- **"orderId"** - numer zamówienia (dostępne tylko dla typu wątku: POST_PURCHASE_ISSUE),
- dodaliśmy nowe pola - przykładowa odpowiedź poniżej:

```
{
"threads": [
...
{
"id": "88ae369b-8f65-4fc4-9c77-bedf604a2e2",
"type": "POST_PURCHASE_ISSUE", // typ wątku; możliwe wartości: COMMON - dotychczasowe wątki, POST_PURCHASE_ISSUE - problemy z zakupem
"read": false,
"createdAt": "2026-06-02T09:00:00Z", // data utworzenia
"lastMessageDateTime": "2026-06-02T10:00:00Z",
"participants": [ // użytkownicy wątku
{
"role": "BUYER", // rola użytkownika; możliwe wartości: BUYER (kupujący), SELLER (sprzedający), USER (użytkownik występujący w dotychczasowych wątkach)
"login": "BuyerLogin" // login użytkownika
},
{
"role": "SELLER",
"login": "SellerLogin"
}
],
"orders": [ // lista zamówień
{
"id": "29738e61-7f6a-11e8-ac45-09db60ede9d6", // identyfikator zamówienia
"offers": [ // lista ofert
{
"id": "82398120310", // identyfikator oferty
"quantity": 1 // liczba sztuk
}
]
}
],
"subType": "PRODUCT_INCONSISTENT_WITH_THE_OFFER", // podtyp wątku, rodzaj problemu pozakupowego; możliwe wartości dostępne w dokumentacji
"status": "OPEN" // status wątku
}
],
"nextPage": "cD0yMDI2LTA2LTAyVDEyOjEwOjAwWjtzPTEwMDQ=" // token, który pozwala pobrać następną stronę wątków
}
```

2. [GET /messaging/threads/{threadId}](https://developer.allegro.pl/documentation/#operation/getThreadGET):
- podobnie jak powyżej dla [GET /messaging/threads](https://developer.allegro.pl/documentation/#operation/listThreadsGET), dodaliśmy nowe pola – z wyjątkiem **„nextPage”**.

3. [PUT /messaging/threads/{threadId}/read](https://developer.allegro.pl/documentation/#operation/changeReadFlagOnThreadPUT):
- zmieniliśmy response body dla status code: 200

**Przykładowy response:**

```
{
"read": true
}
```
4. [GET /messaging/threads/{threadId}/messages](https://developer.allegro.pl/documentation/#operation/listMessagesGET):

- zamiast parametrów **“offset”** i **“limit”** skorzystasz teraz z nowego parametru **“page.id”**,
- dodaliśmy nowe pola:

- **“author.role”** - rola użytkownika w wiadomości; dostępne wartości: USER, SYSTEM, CHATBOT, CONSULTANT, BUYER, SELLER,
- **“attachments.id”** - identyfikator załącznika,
- **„nextPage”** - token pozwalający na pobranie kolejnej strony wiadomości.

5. [GET /messaging/messages/{messageId}](https://developer.allegro.pl/documentation/#operation/getMessageGET):

- podobnie jak powyżej dla [GET /messaging/threads/{threadId}/messages](https://developer.allegro.pl/documentation/#operation/listMessagesGET), dodaliśmy nowe pola – z wyjątkiem **„nextPage”**.

6. Endpoint [DELETE /messaging/messages/{messageId}](https://developer.allegro.pl/documentation/#operation/deleteMessageDELETE) do usuwania wiadomości oznaczyliśmy jako **deprecated** i w przyszłości go **usuniemy**.

**Harmonogram prac**

Poniżej znajdziesz plan zmian w dostępności ścieżek API przeznaczonych do obsługi zgłoszeń transakcyjnych (Dyskusji oraz nowych Problemów z zakupem):

**ETAP I - Stan obecny:**

- zarządzanie wszystkimi problemami transakcyjnymi w ramach dyskusji odbywa się standardowo poprzez ścieżkę /sale/issues,
- w dokumentacji znajdziecie dwie wersje endpointów /messaging:
- **public.v1** - dotychczasowe funkcjonalności,
- **beta.v1** - nowa struktura obejmująca dotychczasowe funkcjonalności oraz obsługę Problemów z zakupem, która wdrożona zostanie w **ETAPIE III.**

**ETAP II - Od 3 sierpnia 2026:**

- sprzedający z kontem zwykłym zaczną otrzymywać pierwsze zgłoszenia **Problemów z zakupem** w Centrum Wiadomości,
- jednocześnie na tym etapie proces ten nie wpłynie jeszcze bezpośrednio na Allegro API.

**ETAP III - Koniec sierpnia:** **wdrożymy** nową wersję endpointów na ścieżce **/messaging**, w wersji **beta.v1**.

**ETAP IV - Od 28 października 2026 r.:**

- u wszystkich sprzedających z kontem firmowym zaczniemy wprowadzać **Problemy z zakupem** jako nowy typ komunikacji w ramach Centrum Wiadomości, które będą obsługiwane wyłącznie przez ścieżkę **/messaging**,
- wszystkie utworzone wcześniej Dyskusje nadal będą obsługiwane za pomocą endpointów na ścieżce **/sale/issues**, które docelowo służyć będą jednak do obsługi **wyłącznie reklamacji**,
- **nie planujemy** migracji wcześniej utworzonych Dyskusji do **Problemów z zakupem**.

Reasumując, endpointy na poniższych ścieżkach docelowo służyć będą:

- **/sale/issues** - wyłącznie do obsługi reklamacji,
- **/messaging** - do obsługi dotychczasowej komunikacji w ramach Centrum Wiadomości oraz Problemów z zakupem.

Zadbaj o to, aby **do 28 października 2026 r.** Twoje oprogramowanie korzystało z nowej wersji zasobów na ścieżce **/messaging**, która obejmuje:

- dotychczasową komunikację sprzedającego z kupującym, w ramach Centrum Wiadomości,
- obsługę nowych **Problemów z zakupem**.

**Ważne!** Nowa struktura dostępna jest w wersji **beta.v1**. Jak tylko nowy proces zacznie już funkcjonować, podczas korzystania z endpointów, w nagłówku **Accept** przekazuj **“application/vnd.allegro.beta.v1+json”**.

**Dlaczego wprowadzamy zmiany?**

Zmiana ma na celu uporządkowanie sposobu rozwiązywania problemów transakcyjnych poprzez stopniowe przeniesienie ich z Dyskusji do wątków „Problem z zakupem” w ramach Centrum Wiadomości.

Dzięki temu sprzedający zyskają możliwość szybszego rozwiązywania spraw dzięki precyzyjnemu wskazaniu problematycznych produktów przez klientów oraz lepszą ochronę jakości sprzedaży, ponieważ kupujący nie będą mogli subiektywnie oznaczać spraw jako nierozwiązanych.

**Jakie są kolejne kroki?**

W przyszłości planujemy przenieść strukturę zasobu w wersji **beta.v1** na wersję **public.v1**. Poinformujemy o tym z odpowiednim wyprzedzeniem. Natomiast do tego czasu dostępne będą obie wersje endpointów **/messaging**.

Więcej informacji na temat nowych funkcjonalności, znajdziesz w [naszym poradniku](https://developer.allegro.pl/tutorials/jak-zarzadzac-centrum-wiadomosci-XxWm2K890Fk).

--------

As part of our work to unify communication handling, we are extending the capabilities of existing endpoints on the /messaging path to include support for a new thread type in the Message Center: problems with purchases, which will eventually completely replace Disputes. The new **/messaging** endpoint structure is available in the **beta.v1** version.

Sellers on Allegro who use your solutions will receive separate communication from us regarding these changes. We will inform them with appropriate notice.

**What have we changed?**

As part of the new selected **/messaging** endpoint structure available in version **beta.v1**, we have introduced several significant changes that will enable the management of new **Problems with purchases**.

1. [GET /messaging/threads](https://developer.allegro.pl/documentation/#operation/listThreadsGET):

- you can retrieve a list of threads for which **“type”**:
- COMMON - covers existing threads,
- POST_PURCHASE_ISSUE - these are Problems with purchases,
- instead of the **“offset”** and **“limit”** parameters, you can use a new parameter called **“page.id”**. This solution eliminates performance issues with a large number of threads and messages,
- We've also added parameters:
- **“read”** - specifying whether the thread has been read; **true** - yes, **false** - no,
- **“status”** - thread status; available values: OPEN, CLOSED,
- **“orderId”** - order number (only available for thread type: POST_PURCHASE_ISSUE),
- we have added new fields - sample response below:

```
{
"threads": [
...
{
"id": "88ae369b-8f65-4fc4-9c77-bedf604a2e2",
"type": "POST_PURCHASE_ISSUE", // thread type; possible values: COMMON - current threads, POST_PURCHASE_ISSUE - Problems with purchases
"read": false,
"createdAt": "2026-06-02T09:00:00Z", // creation date
"lastMessageDateTime": "2026-06-02T10:00:00Z",
"participants": [ // thread users
{
"role": "BUYER", // user role; possible values: BUYER, SELLER, USER (user appearing in existing threads)
"login": "BuyerLogin" // user login
},
{
"role": "SELLER",
"login": "SellerLogin"
}
],
"orders": [ // order identifier
{
"id": "29738e61-7f6a-11e8-ac45-09db60ede9d6", // identyfikator zamówienia
"offers": [ // list of offers
{
"id": "82398120310", // offer identifier
"quantity": 1 // quantity
}
]
}
],
"subType": "PRODUCT_INCONSISTENT_WITH_THE_OFFER", // thread subtype, type of post-purchase issue; possible values available in documentation
"status": "OPEN" // thread status
}
],
"nextPage": "cD0yMDI2LTA2LTAyVDEyOjEwOjAwWjtzPTEwMDQ=" // token to retrieve the next page of threads
}
```

2. [GET /messaging/threads/{threadId}](https://developer.allegro.pl/documentation/#operation/getThreadGET):
- similar to above for [GET /messaging/threads](https://developer.allegro.pl/documentation/#operation/listThreadsGET), we have added new fields – except for **“nextPage”**.
3. [PUT /messaging/threads/{threadId}/read](https://developer.allegro.pl/documentation/#operation/changeReadFlagOnThreadPUT):
- we have changed the response body for status code: 200

**Sample response:**

```
{
"read": true
}
```

4. [GET /messaging/threads/{threadId}/messages](https://developer.allegro.pl/documentation/#operation/listMessagesGET):

- instead of the “offset” and “limit” parameters, you will now use a new parameter called “page.id”,
- we added new fields:
- **“author.role”** - user role in the message; available values: USER, SYSTEM, CHATBOT, CONSULTANT, BUYER, SELLER,
- **“attachments.id”** - attachment identifier,
- **„nextPage”** - token to retrieve the next page of messages.

5. [GET /messaging/messages/{messageId}](https://developer.allegro.pl/documentation/#operation/getMessageGET):

- similar to above for [GET /messaging/threads/{threadId}/messages](https://developer.allegro.pl/documentation/#operation/listMessagesGET), we have added new fields – except for **„nextPage”**.

6. The [DELETE /messaging/messages/{messageId}](https://developer.allegro.pl/documentation/#operation/deleteMessageDELETE) endpoint for deleting messages has been marked as **deprecated** and **will be removed in the future**.

**Work Schedule**

Below you will find the plan for changes in the availability of API paths intended for handling transactional reports (Disputes and new **Problems with purchases**):

**STAGE I - Current Status:**

- management of all transactional issues within disputes takes place as standard via the **/sale/issues** path,
- in the documentation you will find two versions of **/messaging** endpoints:
- **public.v1** - existing functionalities,
- **beta.v1** - new structure covering current functionalities and handling problems with purchases, which will be implemented in **STAGE III**.

**STAGE II - [From August 3](https://help.allegro.com/pl/sell/a/jak-rozwiazywac-problemy-z-zakupem-w-centrum-wiadomosci-x5ZVrvzXPuP), 2026:**

- sellers with a regular account will start receiving the first Problem with purchases reports in the Message Center,
- at this stage, this process will not yet directly affect the Allegro API.

**STAGE III - Late August:** we will implement a new version of endpoints on the /messaging path, in version beta.v1.

**STAGE IV - From October 28, 2026:**

- for all sellers with a business account, we will begin introducing Problems with purchases as a new type of communication within the Message Center, which will be handled exclusively via the **/messaging** path,
- all previously created Disputes will still be handled using endpoints on the **/sale/issues** path which will ultimately be used to **handle claims (issues) only**,
- we do not plan to migrate previously created Disputes to **Problems with purchases**.

To summarize, the endpoints on the following paths will ultimately be used:

- **/sale/issues** - exclusively for handling claims,
- **/messaging** - for handling existing communication within the Message Center and **Problems with purchases**.

Please ensure that **by October 28, 2026**, your software uses the new version of resources on the /messaging path, which includes:

- existing seller-buyer communication within the Message Center,
- handling of new Problems with purchases.

**Important!** The new structure is available in version **beta.v1**. As soon as the new process starts functioning, when using endpoints, pass **“application/vnd.allegro.beta.v1+json”** in the **Accept** header.

**Why are we introducing these changes?**

The change aims to organize the way transactional problems are solved by gradually moving them from Disputes to **„Problems with purchases”** threads within the Message Center.

As a result, sellers will be able to resolve matters faster thanks to precise indication of problematic products by customers and better protection of sales quality, as buyers will not be able to subjectively mark matters as unresolved.

**What are the next steps?**

In the future, we plan to move the resource structure in version **beta.v1** to version **public.v1**. We will inform you about this with appropriate notice. Until then, both versions of **/messaging** endpoints will be available.

More information about the new functionalities can be found in [our guide](https://developer.allegro.pl/tutorials/how-to-manage-the-message-center-g05avyGlZUW).