> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce-openapis/admin/conversations/update-a-conversation.md).

# Update a conversation

Fully updates a conversation's own fields. `datasource` and `conversation_type` must be present.

* `conversation_type` cannot change. Sending `review` or `question` — even the conversation's current kind — is refused with `406` and `conversation_100_8` (`Only its author writes a review.`, or `question`), and sending `message` for a review or question with `conversation_100_14` (`A review cannot be turned into another type.`). A private message accepts `message`. Because a full update requires the field, **a review or question cannot be updated with `PUT`**; use `PATCH` and leave `conversation_type` out.
* `is_public`, `is_answered`, `user` and `last_message_date` are read-only: they are accepted, ignored and returned unchanged. Visibility moves only through `approve/` and `reject/`, the answered flag through `update-answered-status/`, and `last_message_date` with the messages themselves; the customer a conversation belongs to cannot be changed.
* `rating` and `status` are not part of this payload. Values sent for them are ignored, and the response does not include them.
* `item_content` is the numeric identifier of the content type (product or order item), not its name.
* The kind and the item it ends up with are checked against each other — a review must stay on an order item, a question on a product, a private message on an order item or nothing. Violations answer `conversation_100_5` (`A message cannot be about a product.`).
* The item must exist (`conversation_100_12`) and, when it names a seller, belong to the `datasource` sent (`conversation_100_13`); see **Conversation Kinds**.

Rule violations are answered with `406` and `{"non_field_errors": "<message>", "error_code": "<code>"}`. No event is recorded for an edit.

```json
{"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"tags":[{"name":"Conversations","description":"Administrative endpoints for **conversations** — the reviews, product questions and private messages exchanged between customers and sellers (data sources). The seller panel uses them to work the moderation queue, answer questions, write to customers and read what happened to each conversation.\n\n## Core Capabilities\n\n**1. Conversation Listing & Filtering**\n* Retrieve a paginated list of conversations of every kind. Each carries the customer's contact details, the messages, the item it is about, the star `rating`, the moderation `status` and the audit trail (`events`).\n* Filter by moderation status, kind, visibility, answered flag, product, order item, order number, seller, customer and date ranges. `?status=pending` is the moderation queue.\n\n**2. Moderation**\n* Approve a review or question to publish it on the storefront, or reject it citing one of the **Conversation Rejection Reasons** together with a free-text explanation. A rejection e-mails the author.\n* Storefront visibility (`is_public`) follows moderation and cannot be set directly.\n\n**3. Answering & Private Messages**\n* Open a private message to a customer, and post seller replies to questions and private messages — here or through **Conversation Messages** (`POST /messages/`).\n* Mark a conversation answered or unanswered by hand.\n\n**4. Audit Trail**\n* Every submission, approval, rejection, seller reply and answered-flag change is recorded as an event. The trail is embedded in every conversation the list and detail endpoints return and is also available as one feed through **Conversation Events**. It is never shown to customers.\n\n## Conversation Kinds\n\n| `conversation_type` | Written by | About (`item_content`) | `rating` | Moderated | Seller may reply | Customer may add messages |\n|---------------------|------------|------------------------|----------|-----------|------------------|---------------------------|\n| `review` | The customer, on the storefront | An order item they bought (`orderitem`) | Required, 1–5 | Yes | No | No — written once |\n| `question` | The customer, on the storefront | A product (`product`) or nothing | Not allowed | Yes | Yes | No — written once |\n| `message` | The customer on the storefront, or the seller through this API | An order item (`orderitem`), or nothing | Not allowed | No | Yes | Yes |\n\nOnly a private message can be opened through this API. Reviews and questions are always written by their author on the storefront, and the panel cannot change a conversation into one.\n\nThe item must exist and, when it names a seller, belong to the conversation's `datasource`. An order item names the seller that fulfilled it (its own `datasource`, or failing that its product's); a product names its `data_source`. An item that names no seller — as on a single-seller deployment — is accepted with any `datasource`.\n\n## Moderation Status\n\n| `status` | Meaning | `is_public` |\n|----------|---------|-------------|\n| `pending` | Submitted and waiting in the moderation queue. Every new review and question starts here. | `false` |\n| `approved` | Published on the storefront. | `true` |\n| `rejected` | Turned down; the author was e-mailed the reason. | `false` |\n| `null` | A private message, which is never moderated and never listed on the storefront — or a review or question written before moderation existed, which keeps the visibility it had. | unchanged |\n\nEvery new conversation is created with `is_public: false`. Only approval sets it to `true`, and only rejection sets it back.\n\n## Allowed Transitions\n\n| Current `status` | `POST .../approve/` | `POST .../reject/` |\n|------------------|---------------------|--------------------|\n| `pending` | → `approved` | → `rejected` |\n| `null` (older review or question) | → `approved` | → `rejected` |\n| `approved` | Refused — already approved | → `rejected` (take-down) |\n| `rejected` | → `approved` (reversal) | Refused — already rejected |\n\nA decision can be reversed but not repeated, so an author is never mailed twice for the same rejection. Private messages can be neither approved nor rejected.\n\n## Filtering & Ordering\n\n| Parameter | Match | Notes |\n|-----------|-------|-------|\n| `status` | Exact | `pending`, `approved` or `rejected`. Private messages and older conversations have no status and match none of them. |\n| `conversation_type` | Exact | `review`, `question` or `message`. |\n| `is_public`, `is_answered` | Exact | `true` or `false`. |\n| `product` | Product id | Conversations about the product itself **and** conversations about any order item that sold it. |\n| `product_base_code` | Base code | The same two anchors, for every product with the base code. |\n| `order_item` | Order item id | Conversations about that order item. |\n| `order_number` | Order number | Conversations about any order item of that order. |\n| `item_type` | Exact | `product` or `orderitem`. |\n| `data_source` / `data_source_id` | Exact | The seller, by slug or by id. |\n| `user_id` | Exact | The customer who owns the conversation. |\n| `user__first_name`, `user__last_name` | Case-insensitive partial | The customer's name. |\n| `created_date__*`, `modified_date__*`, `last_message_date__*` | `gt`, `gte`, `lt`, `lte` | Date ranges. |\n\nResults are ordered by `last_message_date`, most recent first. Use `sort` to change the ordering. An invalid value for a choice filter, or a `product` or `order_item` that is not a number, is rejected with `400` — for example `{\"product\": [\"Enter a number.\"]}`.\n\n## Errors\n\nError messages are translated to the request language, so match on the HTTP status and the field key or `error_code` rather than on the text. The body shape depends on the rule that failed:\n\n| Status | Shape | Returned for |\n|--------|-------|--------------|\n| `400` | `{\"<field>\": [\"<message>\"]}` / `{\"non_field_errors\": [\"<message>\"]}` | Request validation — a missing or malformed field, an identifier that does not exist, a message longer than 500 characters, or an author the caller may not write as. |\n| `406` | `{\"non_field_errors\": \"<message>\", \"error_code\": \"<code>\"}` — a string, not a list | A rule of the conversation's kind or state. The codes are listed below. |\n\n| `error_code` | Refused because |\n|--------------|-----------------|\n| `conversation_100_1` | An identical conversation — same customer, seller, subject, kind and item — already exists, published or not. A rejected one does not count. |\n| `conversation_100_2` | Storefront visibility cannot be set directly; every valid call to `update-private-status/`. |\n| `conversation_100_3` | A private message cannot be approved or rejected. |\n| `conversation_100_4` | The conversation already has the requested moderation status. |\n| `conversation_100_5` | The item does not fit the kind; see **Conversation Kinds**. |\n| `conversation_100_6` | A review has no `rating`. |\n| `conversation_100_7` | A question or private message carries a `rating`. |\n| `conversation_100_8` | A review or question is opened through this API, or `review` or `question` is sent as `conversation_type` on an edit. |\n| `conversation_100_9` | A seller message is added to a review. |\n| `conversation_100_10` | A customer message is added to a review or question. |\n| `conversation_100_11` | A customer message is added to a moderated conversation that has been decided. Reviews and questions refuse every added customer message with `conversation_100_10` first. |\n| `conversation_100_12` | The item named by `item_content` and `item_id` does not exist. |\n| `conversation_100_13` | The item belongs to another seller than the conversation's `datasource`. |\n| `conversation_100_14` | An edit sends a `conversation_type` other than the conversation's own — for example to turn a review into a private message. |\n\nMessages name the kind, item or status by its API value — for example `A review cannot be replied to.`, `This orderitem belongs to another seller.` or `This conversation is already approved.`\n\n## Dynamic Settings & Environment Variables\n\n| Key | Type | Default | Effect |\n|-----|------|---------|--------|\n| `DISABLED_EMAIL_TEMPLATES` | object — template key → boolean | Every template enabled, except the order-preparing e-mail | `emails/users/review-rejected` and `emails/users/question-rejected` switch off the rejection e-mail; `emails/users/conversation-replied` switches off the e-mail sent for a seller reply. The endpoints answer the same way either way; only the e-mail is skipped. |\n| `EMAIL_BCC_AND_CC` | object — template key → `{\"cc\": [email], \"bcc\": [email]}` | Every template key mapped to `{\"cc\": [], \"bcc\": []}` | Copy recipients added to the rejection and reply e-mails, looked up by the same template keys. |\n| `REVIEW_REQUIRES_PURCHASE` | boolean | `true` | Storefront only: whether a customer's review needs a delivered order item. It has no effect on these endpoints, which cannot open a review. |\n\n**Environment variables:** `NO_REPLY_EMAIL` is the `From` address of the rejection and reply e-mails. Both are sent in the customer's language, falling back to the language of the request."}],"servers":[{"description":"Omnitron Remote Proxy (external access — recommended)","url":"https://{omnitron_url}/api/v1/remote/{channel_id}","variables":{"omnitron_url":{"default":"sandbox.akinon.com","description":"Omnitron server URL (e.g., {omnitron.akinon.com})"},"channel_id":{"default":"1","description":"The channel identifier the remote request is routed through"}}},{"description":"Commerce API Server (internal / direct access only)","url":"https://{commerce_url}/api/v1","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Internal commerce server URL, reachable only from within the Omnitron network"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Token credential sent in the Authorization header, in the form: `Token <your-token>`. Requires a staff (admin) account."}},"schemas":{"ConversationUpdateRequest":{"description":"The body of a full conversation update. `datasource` and `conversation_type` are required.","allOf":[{"$ref":"#/components/schemas/ConversationPatchRequest"},{"type":"object","required":["datasource","conversation_type"]}]},"ConversationPatchRequest":{"type":"object","description":"The editable fields of a conversation. `is_public`, `is_answered`, `rating` and `status` are not editable here: values sent for them are ignored.","properties":{"user":{"type":"integer","readOnly":true,"description":"The identifier of the customer who owns the conversation. Read-only; a value sent is ignored."},"datasource":{"type":"integer","description":"The identifier of the seller (data source)."},"subject":{"type":["string","null"],"maxLength":500,"description":"The subject line."},"conversation_type":{"type":"string","enum":["message"],"description":"The kind of conversation. Only `message` is accepted; `review` and `question` are refused."},"item_content":{"type":["integer","null"],"description":"The numeric identifier of the content type the conversation is about (the product or the order item content type), or `null`."},"item_id":{"type":["integer","null"],"minimum":0,"description":"The identifier of the item the conversation is about."},"last_message_date":{"type":["string","null"],"format":"date-time","readOnly":true,"description":"When the latest message was posted. Read-only; a value sent is ignored."},"extras":{"type":["object","null"],"description":"Free-form JSON for extra, integration-specific data.","additionalProperties":true}}},"ConversationUpdateResponse":{"type":"object","description":"The conversation record after an update. Identifiers are returned for related records; `rating` and `status` are not included.","properties":{"id":{"type":"integer","description":"The conversation identifier."},"created_date":{"type":"string","format":"date-time","description":"When the conversation was created."},"modified_date":{"type":"string","format":"date-time","description":"When the conversation was last modified."},"subject":{"type":["string","null"],"description":"The subject line."},"item_id":{"type":["integer","null"],"description":"The identifier of the item the conversation is about."},"last_message_date":{"type":["string","null"],"format":"date-time","description":"When the latest message was posted."},"is_public":{"type":"boolean","description":"Storefront visibility. Read-only here."},"conversation_type":{"$ref":"#/components/schemas/ConversationType"},"extras":{"type":["object","null"],"description":"Free-form JSON for extra, integration-specific data.","additionalProperties":true},"is_answered":{"type":"boolean","description":"Whether the last word was the seller's. Read-only here."},"user":{"type":"integer","description":"The identifier of the customer who owns the conversation."},"datasource":{"type":"integer","description":"The identifier of the seller (data source)."},"item_content":{"type":["integer","null"],"description":"The numeric identifier of the content type the conversation is about."}}},"ConversationType":{"type":"string","description":"The kind of conversation. See **Conversation Kinds** under **Conversations**.\n* `review` — a customer's rated verdict on an order item they bought; moderated\n* `question` — a customer's question about a product; moderated\n* `message` — private correspondence between one customer and one seller; never moderated and never listed on the storefront","enum":["message","question","review"]},"ValidationError":{"type":"object","description":"Returned when the request contains invalid or missing data. Errors are grouped by the field they apply to: each key is the name of a field from the request and its value is a list of one or more messages describing what is wrong with that field. Messages that do not belong to any single field are grouped under `non_field_errors`.","properties":{"non_field_errors":{"type":"array","description":"Error messages that apply to the request as a whole rather than to a specific field.","items":{"type":"string"}}},"additionalProperties":{"type":"array","description":"The list of error messages for the field named by the key.","items":{"type":"string"}}},"Error":{"type":"object","description":"An error response.","properties":{"detail":{"type":"string","description":"A human-readable description of the error."}},"additionalProperties":true},"ConversationBusinessError":{"type":"object","description":"Returned with `406` when a conversation request is valid in form but breaks a rule of the conversation's kind or state. Unlike validation errors, `non_field_errors` is a single string, not a list.\n\nThe message is translated, so match on `error_code` rather than on the message text. The codes are listed under **Errors** in the **Conversations** section introduction.","properties":{"non_field_errors":{"type":"string","description":"A human-readable message describing the rule that was broken, translated to the request language."},"error_code":{"type":"string","description":"A stable code identifying the rule, `conversation_100_1` to `conversation_100_14`."}},"additionalProperties":true}},"responses":{"Unauthorized":{"description":"Authentication credentials were not provided or are invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The authenticated user does not have administrator privileges.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ConversationNotFound":{"description":"No conversation exists with the given identifier. An identifier that is not a number is answered with `Not found.` instead.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/conversations/{id}/":{"put":{"tags":["Conversations"],"operationId":"updateConversation","summary":"Update a conversation","description":"Fully updates a conversation's own fields. `datasource` and `conversation_type` must be present.\n\n* `conversation_type` cannot change. Sending `review` or `question` — even the conversation's current kind — is refused with `406` and `conversation_100_8` (`Only its author writes a review.`, or `question`), and sending `message` for a review or question with `conversation_100_14` (`A review cannot be turned into another type.`). A private message accepts `message`. Because a full update requires the field, **a review or question cannot be updated with `PUT`**; use `PATCH` and leave `conversation_type` out.\n* `is_public`, `is_answered`, `user` and `last_message_date` are read-only: they are accepted, ignored and returned unchanged. Visibility moves only through `approve/` and `reject/`, the answered flag through `update-answered-status/`, and `last_message_date` with the messages themselves; the customer a conversation belongs to cannot be changed.\n* `rating` and `status` are not part of this payload. Values sent for them are ignored, and the response does not include them.\n* `item_content` is the numeric identifier of the content type (product or order item), not its name.\n* The kind and the item it ends up with are checked against each other — a review must stay on an order item, a question on a product, a private message on an order item or nothing. Violations answer `conversation_100_5` (`A message cannot be about a product.`).\n* The item must exist (`conversation_100_12`) and, when it names a seller, belong to the `datasource` sent (`conversation_100_13`); see **Conversation Kinds**.\n\nRule violations are answered with `406` and `{\"non_field_errors\": \"<message>\", \"error_code\": \"<code>\"}`. No event is recorded for an edit.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationUpdateRequest"}}}},"responses":{"200":{"description":"The updated conversation record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationUpdateResponse"}}}},"400":{"description":"The request contains invalid or missing data. Errors are field-keyed lists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/ConversationNotFound"},"406":{"description":"The update would move the conversation onto a kind, item or seller it may not have. `non_field_errors` is a single string, not a list; match on `error_code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationBusinessError"}}}}}}}}}
```


---

# 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://apidocs.akinon.com/commerce-openapis/admin/conversations/update-a-conversation.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.
