> 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/retrieve-a-conversation.md).

# Retrieve a conversation

Returns a single conversation of any kind, in the same form as a list item — including its `rating`, its moderation `status` and its audit trail (`events`, oldest first).

```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":{"Conversation":{"type":"object","description":"A conversation as the seller panel sees it — the customer's contact details, the messages, the item it is about, the moderation state and the audit trail.","properties":{"id":{"type":"integer","description":"The conversation identifier."},"subject":{"type":["string","null"],"description":"The subject line."},"user":{"$ref":"#/components/schemas/ConversationUser"},"datasource":{"$ref":"#/components/schemas/DataSource"},"item_object":{"description":"The item the conversation is about, shaped by `item_content`. `null` when it is about nothing.","anyOf":[{"$ref":"#/components/schemas/ConversationItemOrderItem"},{"$ref":"#/components/schemas/ConversationItemProduct"},{"type":"null"}]},"item_content":{"type":["string","null"],"enum":["product","orderitem",null],"description":"What the conversation is about — a product, an order item, or nothing (`null`)."},"message_set":{"type":"array","description":"The messages of the conversation, newest first.","items":{"$ref":"#/components/schemas/ConversationMessage"}},"conversation_type":{"$ref":"#/components/schemas/ConversationType"},"last_message_date":{"type":["string","null"],"format":"date-time","description":"When the latest message was posted."},"is_public":{"type":"boolean","description":"Whether the conversation is shown on the storefront. Follows moderation, and is `false` on every private message opened since moderation was introduced. Private messages are never listed on the storefront, whatever the value."},"is_answered":{"type":"boolean","description":"Whether the last word was the seller's. Set by seller replies and customer messages, or by hand through `update-answered-status/`."},"events":{"type":"array","description":"The audit trail of the conversation, oldest first. Returned by these administrative endpoints only — never to customers or in the `conversation_replied` webhook payload.","items":{"$ref":"#/components/schemas/ConversationEvent"}},"rating":{"type":["integer","null"],"minimum":1,"maximum":5,"description":"The star rating of a review, 1 to 5. `null` on questions and private messages, and on reviews written before ratings existed."},"status":{"description":"The moderation status. `null` on private messages and on reviews or questions written before moderation existed.","oneOf":[{"$ref":"#/components/schemas/ConversationStatus"},{"type":"null"}]}}},"ConversationUser":{"type":"object","description":"The customer who owns the conversation, with their contact details.","properties":{"id":{"type":"integer","description":"The customer's user identifier."},"first_name":{"type":"string","description":"The customer's first name. May be empty."},"last_name":{"type":"string","description":"The customer's last name. May be empty."},"email":{"type":"string","description":"The customer's e-mail address — where rejection and reply e-mails are sent."},"phone":{"type":["string","null"],"description":"The customer's phone number."},"gender":{"type":["string","null"],"enum":["male","female","not_to_say",null],"description":"The customer's gender."}}},"DataSource":{"type":"object","description":"A data source — the commercial and legal identity of a seller / supplier, bound to the price and stock lists it sells under.","properties":{"pk":{"type":"integer","readOnly":true,"description":"The unique identifier of the data source."},"name":{"type":"string","maxLength":64,"description":"The seller's display name. Unique across all data sources."},"slug":{"type":["string","null"],"maxLength":64,"description":"A URL-safe identifier. Unique when set."},"title":{"type":["string","null"],"maxLength":255,"description":"The seller's full / legal name."},"supplier_code":{"type":"string","maxLength":50,"description":"The seller's unique business code."},"address":{"type":["string","null"],"description":"Postal address."},"email":{"type":["string","null"],"format":"email","description":"Contact e-mail address."},"phone_number":{"type":["string","null"],"maxLength":128,"description":"Contact phone number."},"fax_number":{"type":["string","null"],"maxLength":128,"description":"Fax number."},"kep_address":{"type":["string","null"],"format":"email","description":"Registered electronic-mail (KEP) address."},"mersis_number":{"type":["string","null"],"maxLength":16,"description":"Central Registry (MERSIS) number."},"trade_association":{"type":["string","null"],"maxLength":255,"description":"Trade association / chamber the seller belongs to."},"extras":{"type":"object","description":"Free-form JSON for extra, integration-specific data."},"price_list":{"type":["integer","null"],"description":"The identifier of the price list supplying this seller's prices."},"stock_list":{"type":["integer","null"],"description":"The identifier of the stock list supplying this seller's stock."},"is_active":{"type":"boolean","description":"Whether the data source is active."}}},"ConversationItemOrderItem":{"type":"object","description":"The order item a conversation is about (`item_content` is `orderitem`).","properties":{"pk":{"type":"integer","description":"The order item identifier."},"product":{"$ref":"#/components/schemas/ConversationItemProduct"},"status":{"$ref":"#/components/schemas/OrderStatus"},"order_number":{"type":"string","description":"The number of the order the item belongs to."}}},"ConversationItemProduct":{"type":"object","description":"The product a conversation is about (`item_content` is `product`), or the product an order item sold.","properties":{"pk":{"type":"integer","description":"The product identifier."},"name":{"type":"string","description":"The product name."},"sku":{"type":"string","description":"The product SKU."},"absolute_url":{"type":"string","description":"The product's storefront URL path."},"product_images":{"type":"array","description":"The product's images.","items":{"$ref":"#/components/schemas/ConversationProductImage"}}}},"ConversationProductImage":{"type":"object","description":"An image of the product a conversation is about.","properties":{"pk":{"type":"integer","description":"The image identifier."},"product":{"type":"integer","description":"The identifier of the product the image belongs to."},"image":{"type":["string","null"],"description":"URL of the image file."},"order":{"type":"integer","description":"The display order of the image."},"image_path":{"type":["string","null"],"description":"The storage path of the image file."},"height":{"type":["integer","null"],"description":"The image height in pixels."},"width":{"type":["integer","null"],"description":"The image width in pixels."}}},"OrderStatus":{"type":"string","description":"The lifecycle status of an order. Values are numeric strings that increase as the order progresses through its lifecycle.\n\n| Value | Name | Description |\n|-------|------|-------------|\n| `50` | `cancellation_waiting` | Cancellation requested, pending. |\n| `100` | `cancelled` | Order cancelled. |\n| `200` | `waiting` | Order created; payment not yet confirmed. |\n| `300` | `payment_waiting` | Payment initiated, awaiting confirmation. |\n| `350` | `confirmation_waiting` | Awaiting manual confirmation. |\n| `400` | `approved` | Payment confirmed; order approved for fulfilment. |\n| `430` | `waiting_for_substitute` | Waiting for a substitute product. |\n| `450` | `preparing` | Order being prepared / packed. |\n| `500` | `shipped` | Order dispatched to carrier. |\n| `510` | `shipped_and_informed` | Order shipped and customer notified. |\n| `520` | `ready_for_pickup` | Ready for in-store collection. |\n| `540` | `attempted_delivery` | Delivery attempted; recipient unavailable. |\n| `544` | `review_started` | Trade-in review started. |\n| `545` | `review_waiting` | Trade-in review waiting. |\n| `546` | `waiting_for_payment` | Waiting for trade-in payment. |\n| `547` | `paid` | Trade-in payment received. |\n| `550` | `delivered` | Order delivered to customer. |\n| `600` | `refunded` | Order refunded. |\n| `700` | `merged` | Add-on order merged into main order. |","enum":["50","100","200","300","350","400","430","450","500","510","520","540","544","545","546","547","550","600","700"]},"ConversationMessage":{"type":"object","description":"One message of a conversation.","properties":{"id":{"type":"integer","description":"The message identifier."},"message_content":{"type":"string","description":"The message text."},"user_type":{"type":["string","null"],"enum":["guest","registered",null],"description":"Whether the author wrote as a guest or as a registered user."},"content_object":{"$ref":"#/components/schemas/ConversationMessageAuthor"},"content_type":{"type":"string","enum":["user","datasource"],"description":"Who wrote the message — the customer (`user`) or the seller (`datasource`)."},"created_date":{"type":"string","format":"date-time","description":"When the message was posted."}}},"ConversationMessageAuthor":{"type":"object","description":"The author of a message. The keys present depend on who wrote it:\n* a customer (`content_type: user`) — `id`, `email`, `first_name`, `last_name`, `phone`, `gender`\n* the seller (`content_type: datasource`) — `id`, `email`, `name`, `title`","properties":{"id":{"type":"integer","description":"The identifier of the user or data source that wrote the message."},"email":{"type":["string","null"],"description":"The author's e-mail address."},"first_name":{"type":"string","description":"Customer authors only. The first name."},"last_name":{"type":"string","description":"Customer authors only. The last name."},"phone":{"type":["string","null"],"description":"Customer authors only. The phone number."},"gender":{"type":["string","null"],"description":"Customer authors only. The gender as a display label, translated to the request language (for example `female`)."},"name":{"type":"string","description":"Seller authors only. The data source's display name."},"title":{"type":["string","null"],"description":"Seller authors only. The data source's full / legal name."}}},"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"]},"ConversationEvent":{"type":"object","description":"One entry of a conversation's audit trail.","properties":{"id":{"type":"integer","description":"The event identifier."},"event_type":{"$ref":"#/components/schemas/ConversationEventType"},"reason_detail":{"type":["string","null"],"maxLength":500,"description":"The moderator's own explanation. Set on `rejected` events; `null` otherwise."},"rejection_reason":{"type":["string","null"],"description":"The `code` of the cited rejection reason — the stable key to group rejections by. Set on `rejected` events; `null` otherwise."},"rejection_reason_text":{"type":["string","null"],"description":"The current wording (`text`) of the cited rejection reason. Set on `rejected` events; `null` otherwise."},"message_content":{"type":["string","null"],"description":"The text of the message the event refers to — the opening message on `submitted` events, the reply on `replied` events. `null` on other events, and once the message has been deleted."},"user":{"type":["integer","null"],"description":"The identifier of the staff account the request was made with — on `approved`, `rejected` and on answered-flag changes made through `update-answered-status/`. Through the Omnitron remote proxy this is the Omnitron integration account (the same id for every moderator), so it does not identify the individual moderator; see `request_headers`. `null` on `submitted` and `replied` events and on automatic answered-status changes (those caused by a seller reply or a customer message)."},"request_headers":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"The audited headers of the staff request that wrote the event — `X-Omnitron-Session`, `X-Omnitron-User` and `X-Request-Id`, whichever were sent. Through the Omnitron remote proxy, `X-Omnitron-User` is the Omnitron user the request was made for, as `email;username;id`, where the id is the Omnitron user id. `null` for storefront requests and for staff requests that sent none of these headers."},"created_date":{"type":"string","format":"date-time","description":"When the event was recorded."}}},"ConversationEventType":{"type":"string","description":"What happened to a conversation. See **Event Types** under **Conversation Events**.","enum":["submitted","approved","rejected","replied","marked_answered","marked_unanswered"]},"ConversationStatus":{"type":"string","description":"Where a moderated conversation stands. Private messages, and reviews or questions written before moderation existed, carry `null` instead.\n* `pending` — waiting in the moderation queue\n* `approved` — published on the storefront\n* `rejected` — turned down; the author was e-mailed the reason","enum":["pending","approved","rejected"]},"Error":{"type":"object","description":"An error response.","properties":{"detail":{"type":"string","description":"A human-readable description of the error."}},"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}/":{"get":{"tags":["Conversations"],"operationId":"retrieveConversation","summary":"Retrieve a conversation","description":"Returns a single conversation of any kind, in the same form as a list item — including its `rating`, its moderation `status` and its audit trail (`events`, oldest first).","responses":{"200":{"description":"The requested conversation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/ConversationNotFound"}}}}}}
```


---

# 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/retrieve-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.
