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

# Conversation Events

A **read-only** reporting feed of the conversation audit trail — one record for every submission, moderation decision, seller reply and answered-flag change on any conversation, kept for legal reporting. Edits made through `PUT` or `PATCH` are not recorded. The same records appear, per conversation and oldest first, in the `events` field of the conversations returned by `GET /conversations/` and `GET /conversations/{id}/`. They are never shown to customers.

Events are written by the platform; nothing in this API creates, updates or deletes them. A record outlives the message it refers to: `message_content` then becomes `null`.

### Event Types

| `event_type`        | Recorded when                                                                                                                                                                                                                                                                | `user`                                                                                           |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `submitted`         | A conversation of any kind is opened, on the storefront or through this API. Carries `message_content` — the opening message — and is recorded before the events that message causes, so a private message the seller opens reads `submitted`, `marked_answered`, `replied`. | `null`                                                                                           |
| `approved`          | A review or question is approved.                                                                                                                                                                                                                                            | The staff account the request was made with                                                      |
| `rejected`          | A review or question is rejected. Carries `reason_detail`, `rejection_reason` and `rejection_reason_text`.                                                                                                                                                                   | The staff account the request was made with                                                      |
| `replied`           | A seller message is added. Carries `message_content`.                                                                                                                                                                                                                        | `null`                                                                                           |
| `marked_answered`   | `is_answered` changes from `false` to `true` — through a seller reply (recorded just before `replied`) or through `update-answered-status/`.                                                                                                                                 | `null` for a reply; the staff account the request was made with for the manual action            |
| `marked_unanswered` | `is_answered` changes from `true` to `false` — through a customer message on a private conversation or through `update-answered-status/`.                                                                                                                                    | `null` for a customer message; the staff account the request was made with for the manual action |

No `marked_*` event is recorded when the flag already had the requested value.

`user` is the staff account the request was made with. Through the Omnitron remote proxy that is the Omnitron integration account — the same id for every moderator — so `user` does not identify the individual moderator. `submitted`, `replied` and automatic answered-status events have `user: null`.

`request_headers` names the person. It holds 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` (the id is the Omnitron user id, not a commerce user id). It is kept on every event a staff request writes — decisions, `update-answered-status/` changes, and the `submitted`, `replied` and `marked_*` events of a message staff post through `POST /conversations/` or `POST /messages/`. It is `null` for requests made by customers, whose headers are never kept, and for staff requests that sent none of these headers.

### Filtering & Ordering

| Parameter                                                                        | Match     | Notes                                        |
| -------------------------------------------------------------------------------- | --------- | -------------------------------------------- |
| `conversation_id`                                                                | Exact     | One conversation's trail.                    |
| `event_type`                                                                     | Exact     | One of the event types above.                |
| `data_source` / `data_source_id`                                                 | Exact     | The conversation's seller, by slug or by id. |
| `created_date__gt`, `created_date__gte`, `created_date__lt`, `created_date__lte` | Date-time | A reporting period.                          |

Results are ordered by `created_date` descending (newest first) by default; pass `?sort=created_date` to reverse. Group rejections by `rejection_reason` — the cited reason's stable code — rather than by its wording, which may be revised.


---

# 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/conversation-events.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.
