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

# Conversations

Manage conversations with your customers. Conversations represent a thread of messages between agents and customers.

## List Conversations

<Endpoint method="GET" path="/api/v1/conversations">
  List all conversations for your tenant
</Endpoint>

<ParamField query="status" type="string" optional>
  Filter by status: `open`, `closed`, `pending`
</ParamField>

<ParamField query="priority" type="string" optional>
  Filter by priority: `low`, `medium`, `high`, `urgent`
</ParamField>

<ParamField query="assignedTo" type="string" optional>
  Filter by assigned user ID
</ParamField>

<ParamField query="inboxId" type="string" optional>
  Filter by inbox ID
</ParamField>

<ParamField query="customerId" type="string" optional>
  Filter by customer ID
</ParamField>

<ParamField query="page" type="string" optional>
  Page number (default: 1)
</ParamField>

<ParamField query="limit" type="string" optional>
  Items per page (default: 50, max: 100)
</ParamField>

<ResponseField name="success" type="boolean">
  true
</ResponseField>

<ResponseField name="data" type="array">
  Array of conversation objects
</ResponseField>

<ResponseField name="pagination.total" type="number">
  Total number of conversations
</ResponseField>

<ResponseField name="pagination.page" type="number">
  Current page number
</ResponseField>

<ResponseField name="pagination.limit" type="number">
  Items per page
</ResponseField>

<ResponseField name="pagination.totalPages" type="number">
  Total number of pages
</ResponseField>

## Get Conversation

<Endpoint method="GET" path="/api/v1/conversations/:id">
  Get details of a specific conversation
</Endpoint>

<ParamField path="id" type="string" required>
  Conversation ID
</ParamField>

<ResponseField name="success" type="boolean">
  true
</ResponseField>

<ResponseField name="data._id" type="string">
  Conversation ID
</ResponseField>

<ResponseField name="data.subject" type="string">
  Conversation subject
</ResponseField>

<ResponseField name="data.status" type="string">
  Status: `open`, `closed`, `pending`
</ResponseField>

<ResponseField name="data.priority" type="string">
  Priority: `low`, `medium`, `high`, `urgent`
</ResponseField>

<ResponseField name="data.customerId" type="object">
  Customer information (populated)
</ResponseField>

<ResponseField name="data.assignedTo" type="object">
  Assigned user information (populated)
</ResponseField>

<ResponseField name="data.channel" type="string">
  Channel: `email`, `chat`, `phone`, `whatsapp`
</ResponseField>

<ResponseField name="data.source" type="string">
  Source: `widget`, `phone`, `api`, `email`
</ResponseField>

## Create Conversation

<Endpoint method="POST" path="/api/v1/conversations">
  Create a new conversation
</Endpoint>

<ParamField body="subject" type="body" required>
  Conversation subject
</ParamField>

<ParamField body="inboxId" type="body" required>
  Inbox ID to assign conversation to
</ParamField>

<ParamField body="customerId" type="body" optional>
  Customer ID (if creating conversation for existing customer)
</ParamField>

<ParamField body="channel" type="body" optional>
  Channel: `email`, `chat`, `phone`, `whatsapp` (default: `email`)
</ParamField>

<ParamField body="priority" type="body" optional>
  Priority: `low`, `medium`, `high`, `urgent` (default: `medium`)
</ParamField>

<ResponseField name="success" type="boolean">
  true
</ResponseField>

<ResponseField name="data" type="object">
  Created conversation object
</ResponseField>

## Update Conversation

<Endpoint method="PUT" path="/api/v1/conversations/:id">
  Update a conversation
</Endpoint>

<ParamField path="id" type="string" required>
  Conversation ID
</ParamField>

<ParamField body="subject" type="body" optional>
  Update subject
</ParamField>

<ParamField body="status" type="body" optional>
  Update status: `open`, `closed`, `pending`
</ParamField>

<ParamField body="priority" type="body" optional>
  Update priority: `low`, `medium`, `high`, `urgent`
</ParamField>

<ParamField body="assignedTo" type="body" optional>
  Assign to user ID (set to `null` to unassign)
</ParamField>

<ResponseField name="success" type="boolean">
  true
</ResponseField>

<ResponseField name="data" type="object">
  Updated conversation object
</ResponseField>

## Delete Conversation

<Endpoint method="DELETE" path="/api/v1/conversations/:id">
  Delete a conversation
</Endpoint>

<ParamField path="id" type="string" required>
  Conversation ID
</ParamField>

<ParamField body="reason" type="body" optional>
  Reason for deletion
</ParamField>

<ResponseField name="success" type="boolean">
  true
</ResponseField>

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<Warning>
  This action cannot be undone! Deleting a conversation will permanently remove it and all associated messages.
</Warning>

## Required Permissions

* `read:conversations` - Required for GET requests
* `write:conversations` - Required for POST, PUT, DELETE requests