> For the complete documentation index, see [llms.txt](https://docs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.akinon.com/technical-guides/commerce/conversation-and-messages.md).

# Conversation & Messages

This document provides a comprehensive guide to using the Message, Review, and Question features developed for the Akinon Seller Center. It includes request and response examples for Omnitron, Commerce, and Project Zero products.

Different endpoints are used depending on the platform. Below are the specific URLs for making requests from Omnitron, Commerce, and Project Zero. Requests sent from Omnitron are sent by sellers and moderators (staff users), while requests sent from Commerce and Project Zero are sent by users.

**For requests made from Omnitron, use the following URLs:**

* https\://{omnitron\_url}/api/v1/remote/1/conversations/
* https\://{omnitron\_url}/api/v1/remote/1/messages/
* https\://{omnitron\_url}/api/v1/remote/1/conversation-rejection-reasons/
* https\://{omnitron\_url}/api/v1/remote/1/conversation-events/

{% hint style="warning" %}
The number “1” that appears after remote in the URL represents the **channel ID**.
{% endhint %}

{% hint style="info" %}
The same endpoints can also be called directly on Commerce with a staff user's token, without the remote prefix: `https://{commerce_url}/api/v1/<path>`, for example `https://{commerce_url}/api/v1/conversations/`.
{% endhint %}

**For requests made from Commerce, use the following URLs:**

* https\://{commerce\_url}/users/conversations/
* https\://{commerce\_url}/users/conversations/{id}/

**For requests made from Project Zero, use the following URLs:**

* https\://{storefront\_url}/users/conversations/
* https\://{storefront\_url}/users/conversations/{id}/
* https\://{storefront\_url}/public-questions/
* https\://{storefront\_url}/public-reviews/

For the full field reference of the storefront endpoints, see [User Support & Conversation](https://apidocs.akinon.com/commerce/users/user-support-and-conversation) in the API Reference.

{% hint style="info" %}
Requests to `/users/conversations/` (listing, detail and creating alike) and to `/api/v1/messages/` are rate-limited under the `send-message` key of the `THROTTLING_SETTINGS` dynamic setting: by default 10 requests per 60 seconds per account. A request over the limit is answered `429 Too Many Requests`, except the first one from a client that has not been flagged yet: it is let through once, and the client is flagged for `SECURITYCOP_IP_BAN_TIMEOUT` (6 hours by default). Requests sent from Omnitron all use the same integration account, so they share one limit on `/api/v1/remote/1/messages/`.
{% endhint %}

{% hint style="warning" %}
From Omnitron, sellers can open only private messages, which are used to inform users about various topics (e.g., when an ordered product is out of stock). Questions and reviews are written by users only; sellers can answer questions but cannot open or reply to reviews.
{% endhint %}

To delve into the concepts and methods more deeply:

### Conversation

**Conversation** is the structure where communication between a user and a seller is established. For a message to be sent, the creation of a **Conversation** is initially expected. With conversation, messages between users and sellers can be created within this communication and these messages can be listed and filtered as desired.

Creating conversation objects allows for communication about products and orders—such as messages, questions, and reviews—as well as messaging independent of any specific product or order.

Different types of Conversations can be created, including:

* Sending a private message to the seller, either on its own or about an item in one of the user's orders (for example, asking the status of an order),
* Asking a question about a specific product, or a general question to the seller,
* Leaving a rated review on a product the user has purchased, through the order item it was bought with.

Each type follows its own rules about moderation, ratings, what it may be about and who may write in it. See [Conversation Types and Rules](#conversation-types-and-rules).

When creating a conversation object, the expected fields are as follows:

***Required fields:***

* user
* datasource
* conversation\_type
* user\_type
* message\_content
* content\_type
* content\_id

***Optional fields:***

* subject
* item\_content
* item\_id
* conversation
* rating (required for reviews)

Briefly explaining these fields,

* **user** and **datasource** are used to determine which user and seller (datasource) the conversation is between,
* **conversation\_type** indicates the type of communication (question, message, review),
* **message\_content** specifies the message content to be sent (at most 500 characters, cannot be blank),
* **user\_type** distinguishes whether the user is registered in the system.
* **content\_type** tracks the sender of the message, which can either be a **datasource** (seller) or a **user** object, and **content\_id** holds the ID of this object.
* **subject** field, which is optional, serves as the subject heading.
* **item\_content** and **item\_id** indicate which product or order item the communication relates to. **item\_content** is either **product** or **orderitem**, while **item\_id** holds the ID of that object. Which of the two a conversation may use depends on its type.
* **conversation** field is used when adding a new message to an existing conversation by making a request to a previously created conversation. This field is relevant only when a new message is being added, and only private messages accept further messages from the user.
* **rating** is the star rating, an integer from 1 to 5. It is required when **conversation\_type** is **review** and refused for questions and messages.

It's important to note that fields like **user\_type**, **content\_type**, **content\_id**, and **message\_content** are not stored within the conversation object itself. These fields are used when the conversation is created along with the initial message.

The **is\_public**, **is\_answered** and **status** fields of a conversation are managed by Commerce and cannot be set when creating one. Every new conversation is created with **is\_public** set to **false**, and an **is\_public** value sent in the request body is ignored. Questions and reviews become public only when a moderator approves them (see [Moderation](#moderation)).

The following sections of this document provide examples of how to create Conversations and Messages for these various scenarios.

### Conversation Types and Rules

The **conversation\_type** field decides how a conversation behaves:

| Type       | Moderated         | Rated               | Allowed anchor (`item_content`) | Seller may open | Seller may reply | Customer may add messages |
| ---------- | ----------------- | ------------------- | ------------------------------- | --------------- | ---------------- | ------------------------- |
| `message`  | No (never public) | No                  | `orderitem`, or none            | Yes             | Yes              | Yes                       |
| `question` | Yes               | No                  | `product`, or none              | No              | Yes              | No                        |
| `review`   | Yes               | Yes (1–5, required) | `orderitem` (required)          | No              | No               | No                        |

* **Moderated:** A new question or review starts with the status `pending` and stays hidden until a moderator approves it. Private messages are never moderated and never become public.
* **Allowed anchor:** The anchor is checked only when `item_content` is sent, so a message or a question can also be sent without one. When a user anchors a message or a review to an order item, the order item must belong to one of the user's own orders.
* **Anchor and seller:** The product or order item must exist. When it names a seller, **datasource** must be that seller: for an order item, the seller it was sold by (or, if the order item names none, the seller of its product); for a product, its seller. An item that names no seller, as on a single-seller site, is accepted with any **datasource**.
* **Seller may open:** From Omnitron, a seller can open only a private message. Opening a question or a review from Omnitron is refused.
* **Seller may reply:** A seller reply is a message with `content_type` set to `datasource`. Questions and messages accept seller replies; reviews do not.
* **Customer may add messages:** A question and a review are written once. Only a private message accepts further messages from the user.

A review additionally has to meet the following rules:

* It must name the order item it is about (`item_content` set to `orderitem` and `item_id` set to the order item's ID), from one of the user's own orders.
* It must carry a `rating` and a non-empty `message_content`: a rating alone is not a review.
* By default, the order item must be delivered. This is controlled by the `REVIEW_REQUIRES_PURCHASE` dynamic setting (default `true`). When it is set to `false`, an order item that is bought but not yet delivered can also be reviewed; all the other rules still apply. See [Dynamic Settings](https://docs.akinon.com/technical-guides/commerce/dynamic-settings.md).
* A user can have one review per order item: any earlier review on the same order item that was not rejected (pending, approved or created before moderation was introduced) blocks a new one. A rejected review does not count, so after a rejection the user can write a new review for the same order item.

When a request breaks one of these rules, it is refused in one of two ways.

A request whose fields do not hold together is answered `400 Bad Request`, with a list of messages under the field concerned or under **non\_field\_errors**:

| Case                                                                                                                                              | Response body                                                                                                                         |
| ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| A rating outside 1–5                                                                                                                              | `{"rating": ["Ensure this value is greater than or equal to 1."]}` or `{"rating": ["Ensure this value is less than or equal to 5."]}` |
| **message\_content** longer than 500 characters                                                                                                   | `{"message_content": ["Ensure this field has no more than 500 characters."]}`                                                         |
| A review without an order item                                                                                                                    | `{"non_field_errors": ["A review must name the order item it is about."]}`                                                            |
| An order item that does not exist or is not in the user's own orders (Commerce)                                                                   | `{"item_id": ["Invalid pk \"1\" - object does not exist."]}`                                                                          |
| A review of an order item that is not in the delivered status `550` — not delivered yet, or since refunded (`REVIEW_REQUIRES_PURCHASE` is `true`) | `{"non_field_errors": ["Only a customer who received this product can review it."]}`                                                  |
| A second review of the same order item while an earlier one is not rejected (pending, approved or created before moderation)                      | `{"non_field_errors": ["You have already reviewed this purchase."]}`                                                                  |
| **user** or **content\_id** is not the requesting user, **content\_type** is not **user**, or **conversation** belongs to another user (Commerce) | `{"non_field_errors": ["Users do not match."]}`                                                                                       |

A well-formed request that breaks a conversation rule is answered `406 Not Acceptable`, with a single message and an `error_code`:

| Case                                                       | Response body                                                                                            |
| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| A review without a rating                                  | `{"non_field_errors": "A review must carry a rating.", "error_code": "conversation_100_6"}`              |
| A rating on a question or a message                        | `{"non_field_errors": "A question cannot carry a rating.", "error_code": "conversation_100_7"}`          |
| An anchor the type does not allow                          | `{"non_field_errors": "A review cannot be about a product.", "error_code": "conversation_100_5"}`        |
| A product or order item that does not exist                | `{"non_field_errors": "The product does not exist.", "error_code": "conversation_100_12"}`               |
| An item that belongs to a seller other than **datasource** | `{"non_field_errors": "This orderitem belongs to another seller.", "error_code": "conversation_100_13"}` |
| A question or a review opened from Omnitron                | `{"non_field_errors": "Only its author writes a review.", "error_code": "conversation_100_8"}`           |
| A user message added to a question or a review             | `{"non_field_errors": "A review is written once, not added to.", "error_code": "conversation_100_10"}`   |
| A seller reply to a review                                 | `{"non_field_errors": "A review cannot be replied to.", "error_code": "conversation_100_9"}`             |

Every `406` code is listed in [Error Codes](#error-codes).

{% hint style="warning" %}
Error messages are translated into the language of the request. Match a `406` response on its `error_code`, and a `400` response on the field key, rather than on the message text.
{% endhint %}

### Error Codes

A request that breaks a conversation rule is answered `406 Not Acceptable`. The body carries the message as a single string, not a list, and a stable `error_code`:

```json
{"non_field_errors": "A review cannot be replied to.", "error_code": "conversation_100_9"}
```

In the messages below, `{kind}` is the conversation type (`review`, `question` or `message`), `{item}` is the anchor (`orderitem` or `product`) and `{target}` is the decision (`approved` or `rejected`). The message is translated into the language of the request, so match on `error_code`.

| Code                  | Message                                                              | Returned when                                                                                                                                                                                                                                                                         |
| --------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `conversation_100_1`  | Conversation already exists                                          | A conversation with the same user, seller, subject, type and item already exists, published or not. Rejected questions and reviews are not taken into account. A second review of the same order item is answered with the `400` already-reviewed error before this check is reached. |
| `conversation_100_2`  | Storefront visibility follows moderation and cannot be set directly. | The update-private-status action is called (see [Moderation](#moderation)).                                                                                                                                                                                                           |
| `conversation_100_3`  | A {kind} is not moderated.                                           | A private message is approved or rejected.                                                                                                                                                                                                                                            |
| `conversation_100_4`  | This conversation is already {target}.                               | An approved conversation is approved again, or a rejected one is rejected again.                                                                                                                                                                                                      |
| `conversation_100_5`  | A {kind} cannot be about a {item}.                                   | The anchor is not one the type allows (see [Conversation Types and Rules](#conversation-types-and-rules)).                                                                                                                                                                            |
| `conversation_100_6`  | A {kind} must carry a rating.                                        | A review is sent without a rating.                                                                                                                                                                                                                                                    |
| `conversation_100_7`  | A {kind} cannot carry a rating.                                      | A rating is sent with a question or a message.                                                                                                                                                                                                                                        |
| `conversation_100_8`  | Only its author writes a {kind}.                                     | A question or a review is opened from Omnitron, or **conversation\_type** is set to one of them in a `PUT` or `PATCH`, even when it is the conversation's current type.                                                                                                               |
| `conversation_100_9`  | A {kind} cannot be replied to.                                       | A seller reply is added to a review, through the conversations or the messages endpoint.                                                                                                                                                                                              |
| `conversation_100_10` | A {kind} is written once, not added to.                              | A user message is added to a question or a review.                                                                                                                                                                                                                                    |
| `conversation_100_11` | A {kind} cannot be added to once it has been decided.                | A user message is added to a question or a review that has been approved or rejected. Not returned while questions and reviews refuse further user messages altogether (`conversation_100_10`).                                                                                       |
| `conversation_100_12` | The {item} does not exist.                                           | **item\_id** is not the ID of an existing product or order item. On Commerce, an order item that does not exist or is not in the user's own orders is answered with the `400` **item\_id** error instead.                                                                             |
| `conversation_100_13` | This {item} belongs to another seller.                               | The product or order item names a seller other than **datasource** (see [Conversation Types and Rules](#conversation-types-and-rules)).                                                                                                                                               |
| `conversation_100_14` | A {kind} cannot be turned into another type.                         | A `PUT` or `PATCH` sends a **conversation\_type** other than the conversation's own, for example to turn a review into a message.                                                                                                                                                     |

When a conversation is edited from Omnitron with `PUT` or `PATCH` on `/api/v1/remote/1/conversations/{id}/`:

* **conversation\_type** cannot change. **question** and **review** are refused even when they are the conversation's current type (`conversation_100_8`), and **message** is refused on a question or a review (`conversation_100_14`). Because a `PUT` requires **conversation\_type**, a question or a review cannot be edited with `PUT`; use `PATCH` without **conversation\_type**. A message accepts **message**.
* The type and the anchor are checked against each other only when the request contains **item\_content** or **conversation\_type** (`conversation_100_5`).
* The item's existence and seller are checked only when the request contains **item\_content**, **item\_id** or **datasource** (`conversation_100_12`, `conversation_100_13`), against the values the conversation ends up with.
* **user**, **last\_message\_date**, **is\_public** and **is\_answered** are read-only: a value sent is ignored and the stored one is returned. A conversation cannot be moved to another user, so a review always stays under its author's name.

A request that touches none of these fields, for example one that changes only **subject**, is not checked, so older conversations stay editable.

### Order or Product Based Conversation

To initiate conversation about a product;

* **item\_content** should be set to **product**, and **item\_id** should be the ID of that object. Only questions can be about a product.

To initiate conversation about an order;

* **item\_content** should be set to **orderitem**, and **item\_id** should be the ID of that object. Private messages and reviews are about an order item.

#### `POST` Create an Order-Based Message

**Path:** `/api/v1/remote/1/conversations/`

To send a private message to the user regarding an order, the **conversation\_type** parameter value is set to **message**, and the request body must include the **item\_id** and **item\_content** (**orderitem**) parameters of the relevant order item.

When the seller writes the first message, **content\_type** is set to **datasource** and **content\_id** to the ID of the seller (datasource). The user is notified by e-mail, as with any seller reply.

**Example Request**

```json
curl --location 'https://{omnitron_url}/api/v1/remote/1/conversations/' \
--header 'Authorization: Token 500dd3a7fa57eaeff27f54dcde4db1f15b20312e7' \
--header 'Content-Type: application/json' \
--header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpc2wTdAecMcBTgi9VmsAfEwI92I8TqBkeDK' \
--data '{
	    "conversation_type": "message",
	    "user_type": "registered",
	    "message_content": "Hello, the product you ordered is out of stock.",
	    "datasource": "1",
	    "content_type": "datasource",
	    "content_id": "1",
	    "user": "545382",
	    "item_id": "1",
	    "item_content": "orderitem"
}'
```

**Example Response (201 Created)**

When a request is successful, the response will include details such as the conversation type, the users and sellers (datasource) involved, and the related object, as shown below. The **id** in the response is the ID of the conversation.

```json
{
"id": 1,
"datasource": 1,
"user": 545382,
"subject": null,
"item_content": "orderitem",
"is_public": false,
"item_id": 1,
"conversation_type": "message",
"message_content": "Hello, the product you ordered is out of stock.",
"user_type": "registered",
"content_id": 1,
"content_type": "datasource",
"rating": null
}
```

Users open the same kind of conversation from Commerce at `/users/conversations/`, with **content\_type** set to **user** and **content\_id** set to their own ID. The order item must belong to one of their own orders.

A message cannot be about a product. If **item\_content** is set to **product** for a message, the request is refused with `406 Not Acceptable`:

```json
{"non_field_errors": "A message cannot be about a product.", "error_code": "conversation_100_5"}
```

The order item must exist and, when it names a seller, belong to the seller in **datasource**; otherwise `conversation_100_12` or `conversation_100_13` is returned (see [Error Codes](#error-codes)).

**Example Response (406 Not Acceptable)**

If a conversation already exists, any further messages should be sent within that existing conversation. If an attempt is made to create a duplicate conversation (same user, seller, subject, type and item), the request is refused with `406 Not Acceptable`, whether the existing one is published or not. Rejected questions and reviews are not taken into account.

```json
{"non_field_errors": "Conversation already exists", "error_code": "conversation_100_1"}
```

#### `POST` Create a Product-Based Question

**Path:** `/users/conversations/`

To ask a question regarding a product, the **conversation\_type** parameter value is set to **question**.

Additionally, the request body must include the **item\_id** and **item\_content** (**product**) parameters of the relevant product. A question cannot be about an order item.

**Example Request**

```json
curl --location 'https://{commerce_url}/users/conversations/' \
--header 'Authorization: Token 500dd3a7fa57eaef27f54dcde4db1f15b20312e7' \
--header 'Content-Type: application/json' \
--header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpfc2wTAefcMcBTgi9VmsAfEwI92I8TqBkeDK' \
--data '{
	    "conversation_type": "question",
	    "user_type": "registered",
	    "message_content": "Does this TV support HDMI 2.1?",
	    "datasource": "1",
	    "content_type": "user",
	    "content_id": "545382",
	    "user": "545382",
	    "item_id": "1",
	    "item_content": "product"
}'
```

**Example Response (201 Created)**

```json
{
"id": 11,
"datasource": 1,
"user": 545382,
"subject": null,
"item_content": "product",
"is_public": false,
"item_id": 1,
"conversation_type": "question",
"message_content": "Does this TV support HDMI 2.1?",
"user_type": "registered",
"content_id": 545382,
"content_type": "user",
"rating": null
}
```

The question is created with the status **pending** and is listed on `/public-questions/` only after a moderator approves it.

If the product does not exist, the request is refused with `406 Not Acceptable` and `{"non_field_errors": "The product does not exist.", "error_code": "conversation_100_12"}`.

If a question is sent from Omnitron, it is refused with `406 Not Acceptable`:

```json
{"non_field_errors": "Only its author writes a question.", "error_code": "conversation_100_8"}
```

#### `POST` Create an Order-Based Review

**Path:** `/users/conversations/`

To leave a review on a purchased product, the **conversation\_type** parameter value is set to **review**. Reviews are written only by users, through `/users/conversations/`.

The request body must include:

* **item\_content** set to **orderitem** and **item\_id** set to the ID of the order item the product was bought with. The order item must belong to one of the user's own orders and, by default, be delivered.
* **rating**, an integer from 1 to 5.
* **message\_content**, the text of the review.

**Example Request**

```json
curl --location 'https://{commerce_url}/users/conversations/' \
--header 'Authorization: Token 500dd3a7fa57eaef27f54dcde4db1f15b20312e7' \
--header 'Content-Type: application/json' \
--header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpfc2wTAefcMcBTgi9VmsAfEwI92I8TqBkeDK' \
--data '{
	    "conversation_type": "review",
	    "user_type": "registered",
	    "message_content": "Great picture quality, arrived quickly.",
	    "datasource": "1",
	    "content_type": "user",
	    "content_id": "545382",
	    "user": "545382",
	    "item_id": "1",
	    "item_content": "orderitem",
	    "rating": 5
}'
```

**Example Response (201 Created)**

```json
{
"id": 12,
"datasource": 1,
"user": 545382,
"subject": null,
"item_content": "orderitem",
"is_public": false,
"item_id": 1,
"conversation_type": "review",
"message_content": "Great picture quality, arrived quickly.",
"user_type": "registered",
"content_id": 545382,
"content_type": "user",
"rating": 5
}
```

The review is created with the status **pending**. It is listed on `/public-reviews/` and counted in the product's `review_stats` only after a moderator approves it. For the errors a review request can return, see [Conversation Types and Rules](#conversation-types-and-rules).

If a review is sent from Omnitron, it is refused with `406 Not Acceptable`:

```json
{"non_field_errors": "Only its author writes a review.", "error_code": "conversation_100_8"}
```

### Conversation without Order or Product

In addition to the actions mentioned above, users can also communicate with the seller without referencing any specific product or order. This applies to private messages and questions; a review always needs an order item.

#### `POST` Create a Message without Order/Product

**Path:** `/users/conversations/`

To send a message directly to the store without referencing any product or order, `conversation_type` parameter value is set to `message`.

**Example Request**

```json
curl --location 'https://{commerce_url}/users/conversations/' \
--header 'Authorization: Token 500dd3a7fa57eaef27f5ffdg4dcde4db1f15b20312e7' \
--header 'Content-Type: application/json' \
--header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpc2wTAdffecfMcBTgi9VmsAfEwI92I8TqBkeDK' \
--data '{
    "conversation_type": "message",
    "user_type": "registered",
    "message_content": "Hello, this is a message.",
    "datasource": "1",
    "content_type": "user",
    "content_id": "545383",
    "user": "545383"
}'
```

**Example Response (201 Created)**

```json
{
"id": 9,
"datasource": 1,
"user": 545383,
"subject": null,
"item_content": null,
"is_public": false,
"item_id": null,
"conversation_type": "message",
"message_content": "Hello, this is a message.",
"user_type": "registered",
"content_id": 545383,
"content_type": "user",
"rating": null
}
```

#### `POST` Create a Question without Order/Product

Path: `/users/conversations/`

To ask a question directly to the store without referencing any product or order, `conversation_type` parameter value is set to `question`.

**Example Request**

```json
curl --location 'https://{commerce_url}/users/conversations/' \
--header 'Authorization: Token 500dd3a7fa57eaef27f54dcde4db1f15b20312e7' \
--header 'Content-Type: application/json' \
--header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpc2wTAecMcBTgi9VmsAfEwI92I8TqBkeDK' \
--data '{
    "conversation_type": "question",
    "user_type": "registered",
    "message_content": "Hello, this is a question.",
    "datasource": "1",
    "content_type": "user",
    "content_id": "545383",
    "user": "545383"
}'
```

**Example Response (201 Created)**

```json
{
"id": 10,
"datasource": 1,
"user": 545383,
"subject": null,
"item_content": null,
"is_public": false,
"item_id": null,
"conversation_type": "question",
"message_content": "Hello, this is a question.",
"user_type": "registered",
"content_id": 545383,
"content_type": "user",
"rating": null
}
```

Like a product-based question, it is created with the status **pending** and becomes public only after a moderator approves it.

#### Reviews Always Need an Order Item

A review cannot be left directly to the store, or to a product, without referencing the order item it was bought with. A review request without **item\_content** and **item\_id** is refused:

**Example Request**

```json
curl --location 'https://{commerce_url}/users/conversations/' \
--header 'Authorization: Token 500dd3a7fa57eaefh27f54dcde4db1f15b20312e7' \
--header 'Content-Type: application/json' \
--header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpc2wTAecMgcBTgi9VmsAfEwI92I8TqBkeDK' \
--data '{
    "conversation_type": "review",
    "user_type": "registered",
    "message_content": "Hello, this is a review.",
    "datasource": "1",
    "content_type": "user",
    "content_id": "545383",
    "user": "545383",
    "rating": 4
}'
```

**Example Response (400 Bad Request)**

```json
{"non_field_errors": ["A review must name the order item it is about."]}
```

Sellers can neither open nor reply to a review. If a review is opened from Omnitron, it is refused with `406 Not Acceptable`:

```json
{"non_field_errors": "Only its author writes a review.", "error_code": "conversation_100_8"}
```

If a seller reply (**content\_type** set to **datasource**) is added to an existing review, through the conversations or the messages endpoint, it is refused with `406 Not Acceptable`:

```json
{"non_field_errors": "A review cannot be replied to.", "error_code": "conversation_100_9"}
```

### Adding New Messages to Conversation

If a message needs to be added to an existing conversation, the “id” value from the response returned for all created conversations above should be set in the **conversation** parameter in the body of the request, as shown in the example request below. The endpoints and other body parameters vary according to the methods as given above.

Which conversations accept a new message depends on their type:

* A private message (**message**) accepts further messages from both the user and the seller.
* A question (**question**) accepts only seller replies. The user writes the question once.
* A review (**review**) accepts no further messages at all.

Only the message fields of the request are used. The conversation keeps its own type, subject, item and rating: **conversation\_type**, **subject**, **item\_content**, **item\_id** and **rating** in the request are not applied, and the conversation fields in the response are those of the existing conversation.

Below is an example request and response for the second message added by the user to a private message conversation with **"id": 9**.

**Example Request**

```json
curl --location 'https://{commerce_url}/users/conversations/' \
--header 'Authorization: Token 500dd3a7fa57eaef2d7f54dcde4db1f15b20312e7' \
--header 'Content-Type: application/json' \
--header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpc2fwTAecMcBTgi9VmsAfEwI92I8TqBkeDK' \
--data '{
    "conversation_type": "message",
    "conversation": 9,
    "user_type": "registered",
    "message_content": "This is the second message.",
    "datasource": "1",
    "content_type": "user",
    "content_id": "545383",
    "user": "545383"
}'
```

**Example Response (201 Created)**

```json
{
"id": 9,
"datasource": 1,
"user": 545383,
"subject": null,
"item_content": null,
"is_public": false,
"item_id": null,
"conversation_type": "message",
"message_content": "This is the second message.",
"user_type": "registered",
"content_id": 545383,
"content_type": "user",
"rating": null
}
```

When the user writes in a private message that the seller has already answered, **is\_answered** switches back to **false**.

If the user tries to add a message to a review or a question, it is refused with `406 Not Acceptable`:

```json
{"non_field_errors": "A review is written once, not added to.", "error_code": "conversation_100_10"}
```

### Listing and Filtering Conversations

There are two endpoints available for listing conversation objects, one for commerce users and another for sellers. Both endpoints use the same filtering options.

* Commerce users should send their requests to `/users/conversations/`.
* Sellers should access the endpoint through `/api/v1/remote/1/conversations/` via Omnitron.

Each conversation carries its **rating** (a number from 1 to 5 on reviews, **null** otherwise) and its moderation **status** (see [Moderation](#moderation)). Commerce users see only their own conversations, including those that are still pending or were rejected. The Omnitron response additionally carries the audit trail of each conversation in the **events** field (see [Audit Trail and Reporting](#audit-trail-and-reporting)); it is never returned to commerce users.

{% hint style="warning" %}
Do not rely on the position of a message within **message\_set**. Use each message's **created\_date** and **content\_type** to tell when it was written and who wrote it.
{% endhint %}

#### `GET` Listing All Conversations

**Example Request (Commerce)**

Here is an example request for a commerce user to list their messages:

```json
curl --location 'https://{commerce_url}/users/conversations/' \
--header 'Authorization: Token b4a04e625f1f3eba3538d1fc19da9e8e8aeba285' \
--header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpc2wTAecMcBTgi9VmsAfEwI92I8TqBkeDK; sessionid=vhid5fk4in98xusm8ostv3s2d87cy19d'
```

**Example Response**

```json
{
    "count": 5,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 12,
            "subject": null,
            "user": {
                "id": 545382,
                "first_name": "Ahmet",
                "last_name": "Yılmaz",
                "email": "akinon@hotmail.com",
                "phone": null,
                "gender": null
            },
            "datasource": {
                "pk": 1,
                "name": "Test Shop",
                "slug": "test-shop",
                "title": "Test shopping",
                "supplier_code": "ard-123",
                "address": null,
                "email": null,
                "phone_number": null,
                "fax_number": null,
                "kep_address": null,
                "mersis_number": null,
                "trade_association": null,
                "extras": {},
                "price_list": 1,
                "stock_list": 1,
                "is_active": true
            },
            "item_object": {
                "pk": 1,
                "product": {
                    "pk": 1,
                    "name": "Q800T QLED 8K Smart TV",
                    "sku": "328187",
                    "absolute_url": "/product/1/",
                    "product_images": [...]
                },
                "status": "550",
                "order_number": "2410231234567"
            },
            "item_content": "orderitem",
            "message_set": [
                {
                    "id": 21,
                    "message_content": "Great picture quality, arrived quickly.",
                    "user_type": "registered",
                    "content_object": {
                        "id": 545382,
                        "first_name": "Ahmet",
                        "last_name": "Yılmaz",
                        "email": "akinon@hotmail.com",
                        "phone": null,
                        "gender": null
                    },
                    "content_type": "user",
                    "created_date": "2026-08-14T10:25:40.208173Z"
                }
            ],
            "conversation_type": "review",
            "last_message_date": "2026-08-14T10:25:40.208173Z",
            "is_public": true,
            "is_answered": false,
            "rating": 5,
            "status": "approved"
        },
        ....
    ]
}
```

**Example Request (Omnitron)**

Here is an example request for a seller to list their messages via Omnitron:

```json
curl --location 'https://{omnitron_url}/api/v1/remote/1/conversations/' \
--header 'Authorization: Token 500dd3a7fa57eaef27f54dcde4db1f15b20312e7' \
--header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpc2wTAecMcBTgi9VmsAfEwI92I8TqBkeDK; sessionid=vhid5fk4in98xusm8ostv3s2d87cy19d'
```

**Example Response**

```json
{
    "count": 12,
    "next": "https://{omnitron_url}/api/v1/remote/1/conversations/?page=2",
    "previous": null,
    "results": [
        {
            "id": 11,
            "subject": null,
            "user": {
                "id": 545382,
                "first_name": "Ahmet",
                "last_name": "Yılmaz",
                "email": "akinon@hotmail.com",
                "phone": null,
                "gender": null
            },
            "datasource": {
                "pk": 1,
                "name": "Test Shop",
                "slug": "test-shop",
                "title": "Test shopping",
                "supplier_code": "ard-123",
                "address": null,
                "email": null,
                "phone_number": null,
                "fax_number": null,
                "kep_address": null,
                "mersis_number": null,
                "trade_association": null,
                "extras": {},
                "price_list": 1,
                "stock_list": 1,
                "is_active": true
            },
            "item_object": {
                "pk": 1,
                "name": "Q800T QLED 8K Smart TV",
                "sku": "328187",
                "absolute_url": "/product/1/",
                "product_images": [...]
            },
            "item_content": "product",
            "message_set": [
                {
                    "id": 18,
                    "message_content": "Yes, all four HDMI ports support HDMI 2.1.",
                    "user_type": "registered",
                    "content_object": {
                        "id": 1,
                        "email": null,
                        "name": "Test Shop",
                        "title": "Test shopping"
                    },
                    "content_type": "datasource",
                    "created_date": "2026-08-12T13:02:11.114230Z"
                },
                {
                    "id": 17,
                    "message_content": "Does this TV support HDMI 2.1?",
                    "user_type": "registered",
                    "content_object": {
                        "id": 545382,
                        "first_name": "Ahmet",
                        "last_name": "Yılmaz",
                        "email": "akinon@hotmail.com",
                        "phone": null,
                        "gender": null
                    },
                    "content_type": "user",
                    "created_date": "2026-08-12T09:14:03.512004Z"
                }
            ],
            "conversation_type": "question",
            "last_message_date": "2026-08-12T13:02:11.114230Z",
            "is_public": true,
            "is_answered": true,
            "events": [
                {
                    "id": 31,
                    "event_type": "submitted",
                    "reason_detail": null,
                    "rejection_reason": null,
                    "rejection_reason_text": null,
                    "message_content": "Does this TV support HDMI 2.1?",
                    "user": null,
                    "request_headers": null,
                    "created_date": "2026-08-12T09:14:03.530112Z"
                },
                {
                    "id": 32,
                    "event_type": "approved",
                    "reason_detail": null,
                    "rejection_reason": null,
                    "rejection_reason_text": null,
                    "message_content": null,
                    "user": 12,
                    "request_headers": {
                        "X-Omnitron-Session": "1",
                        "X-Omnitron-User": "moderator@brand.com;moderator;57"
                    },
                    "created_date": "2026-08-12T11:40:52.901447Z"
                },
                {
                    "id": 33,
                    "event_type": "marked_answered",
                    "reason_detail": null,
                    "rejection_reason": null,
                    "rejection_reason_text": null,
                    "message_content": null,
                    "user": null,
                    "request_headers": {
                        "X-Omnitron-Session": "1",
                        "X-Omnitron-User": "seller@brand.com;seller;58"
                    },
                    "created_date": "2026-08-12T13:02:11.120876Z"
                },
                {
                    "id": 34,
                    "event_type": "replied",
                    "reason_detail": null,
                    "rejection_reason": null,
                    "rejection_reason_text": null,
                    "message_content": "Yes, all four HDMI ports support HDMI 2.1.",
                    "user": null,
                    "request_headers": {
                        "X-Omnitron-Session": "1",
                        "X-Omnitron-User": "seller@brand.com;seller;58"
                    },
                    "created_date": "2026-08-12T13:02:11.131502Z"
                }
            ],
            "rating": null,
            "status": "approved"
        },
        ....
    ]
}
```

#### `GET` Listing Specific Conversations

When listing specific conversations, you can use filter parameters to refine your search. The available filters are:

* modified\_date
* created\_date
* last\_message\_date
* user\_id
* product
* order\_item
* item\_type
* data\_source\_id
* data\_source
* product\_base\_code
* conversation\_type
* status (**pending**, **approved** or **rejected**)
* is\_public
* is\_answered
* user\_\_first\_name
* user\_\_last\_name
* order\_number

The date filters are used with the `__gt`, `__gte`, `__lt` and `__lte` lookups, for example `created_date__gte=2026-08-01`. The **product** and **product\_base\_code** filters match conversations anchored to the product itself, plus any conversation on the order items that sold the product (reviews and private messages alike). A **product** or **order\_item** that is not a number is refused with `400 Bad Request`, for example `{"product": ["Enter a number."]}`.

**Example Request (Commerce)**

Below is an example request from a user for listing results filtered by the data\_source\_id parameter for a specific seller.

```json
curl --location 'https://{commerce_url}/users/conversations/?data_source_id=1' \
--header 'Authorization: Token b4a04e625f1f3eba3538d1fc19da9e8e8aeba285' \
--header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpc2wTAecMcBTgi9VmsAfEwI92I8TqBkeDK; sessionid=vhid5fk4in98xusm8ostv3s2d87cy19d'
```

**Example Response**

```json
{
    "count": 5,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 10,
            "subject": null,
            "user": {
                "id": 545383,
                "first_name": "",
                "last_name": "",
                "email": "akinon@akinon.com",
                "phone": null,
                "gender": null
            },
            "datasource": {
                "pk": 1,
                "name": "Test Shop",
                "slug": "test-shop",
                "title": "Test shopping",
                "supplier_code": "ard-123",
                "address": null,
                "email": null,
                "phone_number": null,
                "fax_number": null,
                "kep_address": null,
                "mersis_number": null,
                "trade_association": null,
                "extras": {},
                "price_list": 1,
                "stock_list": 1,
                "is_active": true
            },
            "item_object": null,
            "item_content": null,
            "message_set": [
                {
                    "id": 15,
                    "message_content": "Hello, this is a question.",
                    "user_type": "registered",
                    "content_object": {
                        "id": 545383,
                        "first_name": "",
                        "last_name": "",
                        "email": "akinon@akinon.com",
                        "phone": null,
                        "gender": null
                    },
                    "content_type": "user",
                    "created_date": "2026-08-15T08:03:27.640981Z"
                }
            ],
            "conversation_type": "question",
            "last_message_date": "2026-08-15T08:03:27.640981Z",
            "is_public": false,
            "is_answered": false,
            "rating": null,
            "status": "pending"
        },
        ....
    ]
}
```

**Example Request - 2 (Commerce)**

Below is an example request from a user for listing results filtered by both the **data\_source\_id** and **conversation\_type** parameters for a specific seller, with **conversation\_type** set to **question**.

```json
curl --location 'https://{commerce_url}/users/conversations/?data_source_id=1&conversation_type=question' \
--header 'Authorization: Token b4a04e625f1f3eba3538d1fc19da9e8e8aeba285' \
--header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpc2wTAecMcBTgi9VmsAfEwI92I8TqBkeDK; sessionid=vhid5fk4in98xusm8ostv3s2d87cy19d'
```

**Example Request - 3 (Omnitron)**

Below is an example request from a seller for listing results filtered by both the **data\_source\_id** and **conversation\_type** parameters for a specific seller, with **conversation\_type** set to **question**.

```json
curl --location 'https://{omnitron_url}/api/v1/remote/1/conversations/?data_source_id=1&conversation_type=question' \
--header 'Authorization: Token 500dd3a7fa57eaef27f54dcde4db1f15b20312e7' \
--header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpc2wTAecMcBTgi9VmsAfEwI92I8TqBkeDK; sessionid=vhid5fk4in98xusm8ostv3s2d87cy19d'
```

{% hint style="warning" %}
Apart from these actions for conversations, there are no other actions such as deletion.
{% endhint %}

### Messages

Messages are the entities contained within conversations. As noted in the conversation section, a message cannot be created without first creating a conversation object.

While there are two distinct endpoints for creating conversations, only one endpoint is used for creating messages: `/api/v1/remote/1/messages/`. It is also possible to send messages through conversation endpoints, as illustrated in the conversation section.

When sending a request to the endpoint, the following mandatory fields must be included:

* message\_content
* conversation
* content\_type
* content\_id
* user\_type

The sender is checked against the requesting user:

* A seller reply uses **content\_type** set to **datasource**, and **content\_id** must be the ID of the seller (datasource) the conversation is with. Only staff users can write as the seller.
* A message in the user's name uses **content\_type** set to **user**, and **content\_id** must be the requesting user's own ID, unless the request is made by a staff user.

Otherwise `400 Bad Request` with `{"non_field_errors": ["Users do not match."]}` is returned; a request without credentials is answered the same way. **message\_content** can be at most 500 characters; a longer one is refused with `400 Bad Request` and `{"message_content": ["Ensure this field has no more than 500 characters."]}`.

Whether the conversation accepts the message at all follows [Conversation Types and Rules](#conversation-types-and-rules): a seller reply to a review (`conversation_100_9`), or a user message to a question or a review (`conversation_100_10`), is refused with `406 Not Acceptable` (see [Error Codes](#error-codes)).

Below is an example request in which the seller answers the question with **"id": 11**.

**Example Request**

```json
curl --location 'https://{omnitron_url}/api/v1/remote/1/messages/' \
--header 'Authorization: Token 500dd3a7fa57eaef27f54dcde4db1f15b20312e7' \
--header 'Content-Type: application/json' \
--header 'Cookie: csrftoken=zj1il0fna79t5ttgzWBGkAy7iItUAqpc2wTAecMcBTgi9VmsAfEwI92I8TqBkeDK' \
--data '{
    "user_type": "registered",
    "message_content": "Yes, all four HDMI ports support HDMI 2.1.",
    "content_type": "datasource",
    "content_id": "1",
    "conversation": "11"
}'
```

**Example Response (201 Created)**

```json
{
    "conversation": 11,
    "message_content": "Yes, all four HDMI ports support HDMI 2.1.",
    "user_type": "registered",
    "content_id": 1,
    "content_type": "datasource"
}
```

{% hint style="warning" %}
If **content\_type** is set to **datasource**, a notification email will be sent to the user, in the user's language. The conversation is also marked as answered (**is\_answered** set to **true**), a **replied** event is recorded (preceded by a **marked\_answered** event only when the conversation was not already answered), and the `conversation_replied` webhook is sent if it is configured (see [Commerce Webhooks](https://docs.akinon.com/technical-guides/commerce/commerce-webhooks.md)).
{% endhint %}

{% hint style="info" %}
Seller replies are not moderated. A reply to a question goes live together with the question: as soon as the question is approved, or immediately if it is already approved.
{% endhint %}

{% hint style="warning" %}
If a commerce user sends a message to a conversation that belongs to another user, the request is refused with `403 Forbidden` (the message is translated into the language of the request):

```
{"detail": "Bu işlemi yapmak için izniniz bulunmuyor."}
```

This check runs after the message itself is validated, so a message the conversation would not accept anyway (for example, one added to a question or a review) is answered with that `400` or `406` error instead.
{% endhint %}

### Moderation

Questions and reviews are moderated: they are hidden when they are created and appear on the storefront only after a moderator approves them from Omnitron. Private messages are not moderated and never become public.

The moderation state of a conversation is shown in its **status** field:

| Status     | Meaning                                                                                                                                                                    |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pending`  | Waiting for a moderator. Every new question and review starts here, with **is\_public** set to **false**.                                                                  |
| `approved` | Published. **is\_public** is **true**, the conversation is listed on `/public-questions/` or `/public-reviews/`, and a review counts towards the product's `review_stats`. |
| `rejected` | Turned down. **is\_public** is **false**, and the author has been sent an e-mail with the reason.                                                                          |
| `null`     | A private message, or a question or review created before moderation was introduced. Those older rows keep their previous visibility until a moderator decides on them.    |

To see the moderation queue, filter the Omnitron conversation list by status, for example `GET /api/v1/remote/1/conversations/?status=pending&conversation_type=review`.

{% hint style="warning" %}
`status=pending` lists pending conversations only. Questions and reviews created before moderation was introduced have the status **null**, so they do not appear there, although they can still be approved or rejected.
{% endhint %}

A decision can be reversed, but not repeated:

| Current status | Approve                          | Reject                                |
| -------------- | -------------------------------- | ------------------------------------- |
| `pending`      | Allowed                          | Allowed                               |
| `null`         | Allowed                          | Allowed                               |
| `approved`     | Refused (already approved)       | Allowed (takes the conversation down) |
| `rejected`     | Allowed (reverses the rejection) | Refused (already rejected)            |

#### `POST` Approve a Question or Review

**Path:** `/api/v1/remote/1/conversations/{id}/approve/`

Approving publishes the question or review. The request has no body. The approval is recorded as an **approved** event with the staff account the request was made with and, for a request sent from Omnitron, the Omnitron user who approved it (see [Audit Trail and Reporting](#audit-trail-and-reporting)). No e-mail is sent.

**Example Request**

```json
curl --location --request POST 'https://{omnitron_url}/api/v1/remote/1/conversations/12/approve/' \
--header 'Authorization: Token 500dd3a7fa57eaef27f54dcde4db1f15b20312e7'
```

**Example Response (200 OK)**

```json
{"is_public": true}
```

**Example Response (406 Not Acceptable)**

```json
{"non_field_errors": "This conversation is already approved.", "error_code": "conversation_100_4"}
```

A private message cannot be approved or rejected:

```json
{"non_field_errors": "A message is not moderated.", "error_code": "conversation_100_3"}
```

#### `POST` Reject a Question or Review

**Path:** `/api/v1/remote/1/conversations/{id}/reject/`

Rejecting hides the question or review from the storefront and removes a review from the product's `review_stats`. Rejecting an approved conversation takes it down. The request body must include:

| Field              | Type    | Description                                                                                                  |
| ------------------ | ------- | ------------------------------------------------------------------------------------------------------------ |
| `reason_detail`    | String  | The moderator's explanation, at most 500 characters. It is included in the e-mail sent to the author.        |
| `rejection_reason` | Integer | The ID of an active rejection reason: the rule the post broke (see [Rejection Reasons](#rejection-reasons)). |

**Example Request**

```json
curl --location 'https://{omnitron_url}/api/v1/remote/1/conversations/14/reject/' \
--header 'Authorization: Token 500dd3a7fa57eaef27f54dcde4db1f15b20312e7' \
--header 'Content-Type: application/json' \
--data '{
    "reason_detail": "The review contains insulting language towards the seller.",
    "rejection_reason": 1
}'
```

**Example Response (200 OK)**

```json
{"is_public": false}
```

The rejection is recorded as a **rejected** event with the staff account the request was made with, the Omnitron user who rejected it (for a request sent from Omnitron), the **reason\_detail** and the cited rejection reason. The author is then sent an e-mail stating that the post was not published, the moderator's explanation and the text of the rule it broke. The e-mail is rendered in the author's language; the default templates are written in Turkish, and only their subject line is translated. Reviews and questions use separate templates (`emails/users/review-rejected.html` and `emails/users/question-rejected.html`); see [E-mail Templates](https://docs.akinon.com/technical-guides/commerce/e-mail-templates.md) to customize or disable them. Reversing a rejection sends no e-mail.

**Example Responses (400 Bad Request)**

| Case                                             | Response body                                                               |
| ------------------------------------------------ | --------------------------------------------------------------------------- |
| **reason\_detail** is missing                    | `{"reason_detail": ["This field is required."]}`                            |
| **reason\_detail** is blank                      | `{"reason_detail": ["This field may not be blank."]}`                       |
| **reason\_detail** is longer than 500 characters | `{"reason_detail": ["Ensure this field has no more than 500 characters."]}` |
| **rejection\_reason** is missing                 | `{"rejection_reason": ["This field is required."]}`                         |
| **rejection\_reason** is unknown or inactive     | `{"rejection_reason": ["Invalid pk \"7\" - object does not exist."]}`       |

The decision itself is refused with `406 Not Acceptable`:

| Case                                  | Response body                                                                                        |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| The conversation is already rejected  | `{"non_field_errors": "This conversation is already rejected.", "error_code": "conversation_100_4"}` |
| The conversation is a private message | `{"non_field_errors": "A message is not moderated.", "error_code": "conversation_100_3"}`            |

When a request is refused, nothing changes and no e-mail is sent.

{% hint style="info" %}
A rejected review does not block its author: they can write a new review for the same order item, which goes through moderation again.
{% endhint %}

{% hint style="warning" %}
Storefront visibility can no longer be set directly. The `POST /api/v1/remote/1/conversations/{id}/update-private-status/` action is always refused: a request with **is\_public** gets `406 Not Acceptable` with `{"non_field_errors": "Storefront visibility follows moderation and cannot be set directly.", "error_code": "conversation_100_2"}`, and a request without **is\_public** gets the field error `400` `{"is_public": ["This field is required."]}` first. **is\_public** and **is\_answered** values sent in a `PUT` or `PATCH` request to a conversation are ignored. **rating** and **status** cannot be changed either. Use the approve and reject actions for visibility, and the update-answered-status action (see [Audit Trail and Reporting](#audit-trail-and-reporting)) for the answered flag.
{% endhint %}

### Rejection Reasons

Every rejection must cite one of the publishing rules the brand defines as rejection reasons. **At least one active rejection reason must exist before anything can be rejected.**

Rejection reasons are managed through `/api/v1/remote/1/conversation-rejection-reasons/`, which supports listing, creating, retrieving, updating (`PUT`, `PATCH`) and deleting. Only staff users can access it.

| Field          | Type    | Description                                                                                                                                                    |
| -------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`         | String  | A unique slug (letters, numbers, hyphens and underscores), at most 50 characters, e.g. `profanity`. It is the stable key used in reports.                      |
| `text`         | String  | The wording of the rule, at most 255 characters. It is shown to the author in the rejection e-mail.                                                            |
| `is_active`    | Boolean | Only active reasons can be cited. Defaults to **true**.                                                                                                        |
| `translations` | Object  | The **text** in other languages, keyed by language code, e.g. `{"en-us": {"text": "Contains profanity or insults"}}`. Optional; replaced as a whole when sent. |

#### `POST` Create a Rejection Reason

**Example Request**

```json
curl --location 'https://{omnitron_url}/api/v1/remote/1/conversation-rejection-reasons/' \
--header 'Authorization: Token 500dd3a7fa57eaef27f54dcde4db1f15b20312e7' \
--header 'Content-Type: application/json' \
--data '{
    "code": "profanity",
    "text": "Contains profanity or insults"
}'
```

**Example Response (201 Created)**

```json
{
    "pk": 1,
    "code": "profanity",
    "text": "Contains profanity or insults",
    "is_active": true,
    "translations": null
}
```

The rejection e-mail cites the reason in the author's language: its translation when **translations** has one for that language, the stored **text** otherwise. The API itself always returns the stored **text** next to **translations**, and **rejection\_reason\_text** on events is the stored **text** as well.

If the code is already used, the following response is returned:

```json
{"code": ["conversation rejection reason with this code already exists."]}
```

#### `GET` List Rejection Reasons

The list is paginated and ordered by **code**.

**Example Request**

```json
curl --location 'https://{omnitron_url}/api/v1/remote/1/conversation-rejection-reasons/' \
--header 'Authorization: Token 500dd3a7fa57eaef27f54dcde4db1f15b20312e7'
```

**Example Response**

```json
{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "pk": 2,
            "code": "off-topic",
            "text": "Not about the product or the purchase",
            "is_active": true,
            "translations": null
        },
        {
            "pk": 1,
            "code": "profanity",
            "text": "Contains profanity or insults",
            "is_active": true,
            "translations": {
                "en-us": {
                    "text": "Contains profanity or insults"
                }
            }
        }
    ]
}
```

#### `PATCH` Retire a Rejection Reason

A rejection reason that is no longer used is retired by setting **is\_active** to **false**. It then cannot be cited in new rejections, while past rejections keep referring to it.

**Example Request**

```json
curl --location --request PATCH 'https://{omnitron_url}/api/v1/remote/1/conversation-rejection-reasons/2/' \
--header 'Authorization: Token 500dd3a7fa57eaef27f54dcde4db1f15b20312e7' \
--header 'Content-Type: application/json' \
--data '{
    "is_active": false
}'
```

**Example Response (200 OK)**

```json
{
    "pk": 2,
    "code": "off-topic",
    "text": "Not about the product or the purchase",
    "is_active": false,
    "translations": null
}
```

#### `DELETE` Delete a Rejection Reason

A rejection reason that has never been cited can be deleted (`204 No Content`). A reason cited by at least one rejection cannot be deleted; retire it instead. Deleting a cited reason returns:

**Example Response (406 Not Acceptable)**

```json
{"non_field_errors": "Cannot delete some instances of model ... because they are referenced through protected foreign keys: ..."}
```

### Audit Trail and Reporting

Every action on a conversation is recorded as an event, so that it can be reported later. Events are read-only.

| Event type          | Written when                                                                                                                                                                                                                                                         | `user`                                                |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `submitted`         | A conversation of any type is opened, from Commerce or from Omnitron. Carries the opening message's text, and is written before any other event that message causes.                                                                                                 | `null`                                                |
| `approved`          | A question or review is approved.                                                                                                                                                                                                                                    | The staff account the request was made with           |
| `rejected`          | A question or review is rejected. Carries the **reason\_detail** and the cited rejection reason.                                                                                                                                                                     | The staff account the request was made with           |
| `replied`           | A seller message is added, through the messages endpoint or the conversations endpoint (including the first message of a private message the seller opens, which records **submitted**, **marked\_answered** and **replied** in that order). Carries the reply text. | `null`                                                |
| `marked_answered`   | **is\_answered** changes from **false** to **true**: on a seller reply (written just before **replied**), or through the update-answered-status action.                                                                                                              | `null` on a reply; the staff account otherwise        |
| `marked_unanswered` | **is\_answered** changes from **true** to **false**: when the user writes in an answered private message, or through the update-answered-status action.                                                                                                              | `null` on a user message; the staff account otherwise |

{% hint style="info" %}
The event's **user** is the staff account the request was made with. Requests sent from Omnitron all use the Omnitron integration account, so **user** is the same on every decision made in Omnitron. The person is in **request\_headers** instead: its `X-Omnitron-User` header is the Omnitron user the request was made for, as `email;username;id`. The headers are kept on every event a staff request writes, including seller replies and the answered-status changes they cause, and **request\_headers** is **null** for storefront requests and for staff requests that sent none of the recorded headers.
{% endhint %}

Each event has the following fields:

* **id** and **event\_type**,
* **reason\_detail**: the moderator's explanation (rejections only, otherwise **null**),
* **rejection\_reason**: the **code** of the cited rejection reason, and **rejection\_reason\_text**: its wording (rejections only, otherwise **null**),
* **message\_content**: the opening message for **submitted** events and the reply text for **replied** events (**null** otherwise, or if the message was deleted later; the event itself is kept),
* **user**: the ID of the staff account the request was made with, or **null** for **submitted**, **replied** and the automatic **marked\_answered** / **marked\_unanswered** events,
* **request\_headers**: the recorded headers of the staff request that wrote the event (`X-Omnitron-Session`, `X-Omnitron-User` and `X-Request-Id`, whichever were sent), or **null** for a storefront request or when none were sent. `X-Omnitron-User` is the Omnitron user as `email;username;id`; the ID is the Omnitron user ID,
* **created\_date**.

In the Omnitron conversation responses (list and detail), each conversation carries its events, oldest first, in the **events** field (see the [Omnitron listing example](#listing-and-filtering-conversations)). The trail is never part of the `conversation_replied` webhook payload (see [Commerce Webhooks](https://docs.akinon.com/technical-guides/commerce/commerce-webhooks.md)), the commerce user's `/users/conversations/` responses or the public endpoints.

#### `POST` Update the Answered Status

**Path:** `/api/v1/remote/1/conversations/{id}/update-answered-status/`

Sets **is\_answered** by hand. A change is recorded as a **marked\_answered** or **marked\_unanswered** event with the staff account the request was made with and, for a request sent from Omnitron, the Omnitron user; sending the current value records nothing.

**Example Request**

```json
curl --location 'https://{omnitron_url}/api/v1/remote/1/conversations/9/update-answered-status/' \
--header 'Authorization: Token 500dd3a7fa57eaef27f54dcde4db1f15b20312e7' \
--header 'Content-Type: application/json' \
--data '{
    "is_answered": true
}'
```

**Example Response (200 OK)**

```json
{"is_answered": true}
```

#### `GET` Listing Conversation Events

**Path:** `/api/v1/remote/1/conversation-events/`

A read-only feed of the events of all conversations, for reporting. Only staff users can access it; other requests are refused with `401` or `403`. Besides the event fields above, each result carries **conversation** (the conversation ID) and **data\_source** (the seller's slug).

The following filters can be used:

* event\_type (**submitted**, **approved**, **rejected**, **replied**, **marked\_answered**, **marked\_unanswered**)
* conversation\_id
* data\_source (the seller's slug)
* data\_source\_id
* created\_date (with the `__gt`, `__gte`, `__lt` and `__lte` lookups)
* sort (**created\_date** or **-created\_date**; newest first by default)
* page, limit

**Example Request**

Below is an example request listing the rejections of a seller since the beginning of August 2026:

```json
curl --location 'https://{omnitron_url}/api/v1/remote/1/conversation-events/?event_type=rejected&data_source_id=1&created_date__gte=2026-08-01' \
--header 'Authorization: Token 500dd3a7fa57eaef27f54dcde4db1f15b20312e7'
```

**Example Response**

```json
{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 58,
            "event_type": "rejected",
            "reason_detail": "The review contains insulting language towards the seller.",
            "rejection_reason": "profanity",
            "rejection_reason_text": "Contains profanity or insults",
            "message_content": null,
            "user": 12,
            "request_headers": {
                "X-Omnitron-Session": "1",
                "X-Omnitron-User": "moderator@brand.com;moderator;57"
            },
            "created_date": "2026-08-16T14:21:09.338120Z",
            "conversation": 14,
            "data_source": "test-shop"
        }
    ]
}
```

### Public Questions & Reviews

This section contains the endpoints where content such as questions or reviews for sellers or products can be publicly published. No authentication is required.

Only approved questions and reviews are listed, together with those created before moderation was introduced that were already public. Pending and rejected ones, and private messages, are never listed.

To protect the author's privacy, public responses identify people by display name only:

* **user** contains only **id** and **display\_name**. The display name is the first name followed by the initial of the last name, e.g. **"Ahmet Y."** (only the first name if there is no last name, only the initial if there is no first name, and an empty string if there is neither).
* In **message\_set**, **content\_object** contains **id** and **display\_name** for a message written by the user, and **id**, **display\_name** (**null**) and **title** for a reply written by the seller.

The author's e-mail address, phone number, gender and full name are not returned, and neither is the order number of a reviewed order item. The audit trail (**events**) is not returned either. The seller in **datasource** is returned as in the other conversation responses, except that its **extras** never contain **files**.

The following filters can be used to obtain more specific results when filtering conversations.

* modified\_date
* created\_date
* last\_message\_date
* user\_id
* product
* order\_item
* item\_type
* data\_source\_id
* data\_source
* product\_base\_code
* status
* is\_answered

The **product** and **product\_base\_code** filters also match reviews written on order items that sold the product, so `/public-reviews/?product=1` lists all published reviews of product 1. A **product** or **order\_item** that is not a number is refused with `400 Bad Request`.

The public listings cannot be searched by who wrote a post or which order it came from: **user\_\_first\_name**, **user\_\_last\_name** and **order\_number** are not accepted here and, like any unknown parameter, are ignored.

{% hint style="warning" %}
Do not rely on the position of a message within **message\_set**. Use each message's **created\_date** and **content\_type** to order the messages and to tell the question from the seller's reply.
{% endhint %}

#### `GET` Listing Public Questions

**Example Request**

```json
curl --location 'https://{storefront_url}/public-questions/' \
--header 'Cookie: csrftoken=nHG4iaHFpqXhMiIY0wUXAQupLFeKdCQrqE326dImB2QAV06Ua7E6kZrj29tYdLvM; osessionid=ve00sgs86u7xyydyxcorgvx4slrpok5l; sessionid=9hvt8kjd1pw4kktspyqaye3zp44bjzlu'
```

**Example Response**

```json
{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 11,
            "subject": null,
            "user": {
                "id": 545382,
                "display_name": "Ahmet Y."
            },
            "datasource": {
                "pk": 1,
                "name": "Test Shop",
                "slug": "test-shop",
                ...
            },
            "item_object": {
                "pk": 1,
                "name": "Q800T QLED 8K Smart TV",
                "sku": "328187",
                "absolute_url": "/product/1/",
                "product_images": [...]
            },
            "item_content": "product",
            "message_set": [
                {
                    "id": 18,
                    "message_content": "Yes, all four HDMI ports support HDMI 2.1.",
                    "user_type": "registered",
                    "content_object": {
                        "id": 1,
                        "display_name": null,
                        "title": "Test shopping"
                    },
                    "content_type": "datasource",
                    "created_date": "2026-08-12T13:02:11.114230Z"
                },
                {
                    "id": 17,
                    "message_content": "Does this TV support HDMI 2.1?",
                    "user_type": "registered",
                    "content_object": {
                        "id": 545382,
                        "display_name": "Ahmet Y."
                    },
                    "content_type": "user",
                    "created_date": "2026-08-12T09:14:03.512004Z"
                }
            ],
            "conversation_type": "question",
            "last_message_date": "2026-08-12T13:02:11.114230Z",
            "is_public": true,
            "is_answered": true,
            "rating": null,
            "status": "approved"
        }
    ]
}
```

#### `GET` Listing Public Reviews

**Example Request**

```json
curl --location 'https://{storefront_url}/public-reviews/?product=1' \
--header 'Cookie: csrftoken=nHG4iaHFpqXhMiIY0wUXAQupLFeKdCQrqE326dImB2QAV06Ua7E6kZrj29tYdLvM; osessionid=ve00sgs86u7xyydyxcorgvx4slrpok5l; sessionid=9hvt8kjd1pw4kktspyqaye3zp44bjzlu'
```

**Example Response**

A review has a single message, written by its author (a review created before moderation was introduced may have more). For a review, **item\_object** describes the order item the review was written on, with its product; the order number is not included.

```json
{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 12,
            "subject": null,
            "user": {
                "id": 545382,
                "display_name": "Ahmet Y."
            },
            "datasource": {
                "pk": 1,
                "name": "Test Shop",
                "slug": "test-shop",
                ...
            },
            "item_object": {
                "pk": 1,
                "product": {
                    "pk": 1,
                    "name": "Q800T QLED 8K Smart TV",
                    "sku": "328187",
                    "absolute_url": "/product/1/",
                    "product_images": [...]
                },
                "status": "550"
            },
            "item_content": "orderitem",
            "message_set": [
                {
                    "id": 21,
                    "message_content": "Great picture quality, arrived quickly.",
                    "user_type": "registered",
                    "content_object": {
                        "id": 545382,
                        "display_name": "Ahmet Y."
                    },
                    "content_type": "user",
                    "created_date": "2026-08-14T10:25:40.208173Z"
                }
            ],
            "conversation_type": "review",
            "last_message_date": "2026-08-14T10:25:40.208173Z",
            "is_public": true,
            "is_answered": false,
            "rating": 5,
            "status": "approved"
        }
    ]
}
```

### Ratings and Review Stats

A review carries a star **rating**, an integer from 1 to 5. It is required when the review is written and cannot be changed afterwards, not even from Omnitron. Questions and messages have no rating (**null**), and neither do reviews created before ratings were introduced.

Product responses on the storefront carry a `review_stats` object that summarizes the product's reviews:

* `/product/{product_id}/`: in `product.review_stats`,
* `/group-product/{product_id}/`: on the product and on each of its group products,
* `/list/`: on each product in `products`.

```json
"review_stats": {
    "review_count": 12,
    "review_average": 4.33
}
```

* **review\_count** is the number of counted reviews; it is **0** when there are none.
* **review\_average** is the average rating of the counted reviews, rounded to two decimals; it is **null** when there are none.

A review is counted when all of the following hold:

* it is public and its status is **approved** (or **null**, for a review created before moderation was introduced),
* it has a rating,
* it is written on an order item whose product is exactly this product. Ratings are not combined across variants or products that share a base code.

Pending, rejected and unrated reviews are not counted. Reviews created before moderation was introduced have no rating, which cannot be added later, so they are not counted either.

{% hint style="info" %}
The values are cached at several levels, so a review that has just been approved or rejected is not reflected in `review_stats` straight away: it can take up to about 20 minutes on product detail pages and up to about 25 minutes on listing pages.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.akinon.com/technical-guides/commerce/conversation-and-messages.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
