> ## Documentation Index
> Fetch the complete documentation index at: https://docs.woes.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversations

> Planned conversation, message, note, assignment, and issue categories for the Woes public API.

Conversation APIs will expose the shared support workflow across channels. Live chat, Discord, and future email intake should appear as channel values on one conversation model.

## Planned resources

| Resource               | Description                                                 |
| ---------------------- | ----------------------------------------------------------- |
| Conversations          | The parent support record across channels.                  |
| Messages               | Customer, operator, and agent-visible message history.      |
| Participants           | Customer, operator, agent, and channel participant details. |
| Assignments            | Owner or team responsible for follow-up.                    |
| Status                 | Conversation lifecycle state.                               |
| Tags and custom fields | Triage labels and structured context.                       |
| Private notes          | Operator-only investigation context.                        |
| Linked issues          | Product work connected to a support case.                   |
| Handoff events         | Automation stop points and operator takeover state.         |

## Common workflows

<Steps>
  <Step title="Create or receive a conversation">
    A message enters through live chat, Discord, or a future supported channel.
  </Step>

  <Step title="Attach context">
    Woes associates identity, channel, tags, custom fields, and message history.
  </Step>

  <Step title="Route or respond">
    The agent, an operator, a macro, or an automation moves the case forward.
  </Step>

  <Step title="Resolve or link to product work">
    The team resolves the case or connects it to an issue for follow-up.
  </Step>
</Steps>

## Customer-facing vs operator-only data

| Data                    | Customer-facing? | Notes                                           |
| ----------------------- | ---------------- | ----------------------------------------------- |
| Customer messages       | Yes              | Part of the conversation record.                |
| Operator replies        | Usually          | Sent to the customer unless saved as notes.     |
| Agent answers           | Usually          | Should include grounded support behavior.       |
| Private notes           | No               | Operator-only investigation context.            |
| Debug traces            | No               | Keep internal diagnostics out of customer APIs. |
| Cross-workspace records | No               | Must never be returned.                         |

## Integration examples

* Show conversation state in a customer dashboard.
* Sync resolved conversations to an internal warehouse.
* Link repeated conversations to a product issue.
* Build response-time and routing analytics.
* Trigger internal workflows when handoff is requested.