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

# Conversations API — List, Create, and Update Threads

> REST API endpoints to list, retrieve, create, and update conversations in your Sahut inbox. Includes request parameters and response field definitions.

The Conversations API lets you read and manage conversation threads in your Sahut inbox programmatically. Use it to pull conversation data into your reporting tools, create conversations from external triggers, or update conversation status and assignments.

## List conversations

Retrieve a paginated list of conversations in your workspace.

```
GET /conversations
```

### Query parameters

<ParamField query="status" type="string">
  Filter by status. One of: `open`, `pending`, `resolved`, `snoozed`. Omit to return all statuses.
</ParamField>

<ParamField query="channel_id" type="string">
  Filter by channel ID. Returns only conversations from that channel.
</ParamField>

<ParamField query="assignee_id" type="string">
  Filter by assigned agent ID. Use `unassigned` to get conversations with no assignee.
</ParamField>

<ParamField query="page" type="integer">
  Page number for pagination. Default: `1`.
</ParamField>

<ParamField query="per_page" type="integer">
  Number of results per page. Default: `25`. Max: `100`.
</ParamField>

### Example request

```bash theme={null}
curl "https://api.sahut.id/v1/conversations?status=open&per_page=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example response

```json theme={null}
{
  "data": [
    {
      "id": "conv_01HX2B9K3M5N7P",
      "status": "open",
      "channel": {
        "id": "ch_01HX1A8J2L4M6N",
        "type": "whatsapp",
        "name": "WhatsApp Utama"
      },
      "contact": {
        "id": "ct_01HX3C0L4N6P8Q",
        "name": "Budi Santoso",
        "phone": "+628123456789"
      },
      "assignee": {
        "id": "usr_01HX0Z7I1K3L5M",
        "name": "Sari Dewi"
      },
      "labels": ["follow-up"],
      "created_at": "2024-03-15T08:30:00Z",
      "updated_at": "2024-03-15T09:15:00Z"
    }
  ],
  "meta": {
    "total": 47,
    "page": 1,
    "per_page": 10,
    "total_pages": 5
  }
}
```

## Get a conversation

Retrieve a single conversation by its ID.

```
GET /conversations/{id}
```

### Path parameters

<ParamField path="id" type="string" required>
  The conversation ID (e.g., `conv_01HX2B9K3M5N7P`).
</ParamField>

### Example request

```bash theme={null}
curl https://api.sahut.id/v1/conversations/conv_01HX2B9K3M5N7P \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Create a conversation

Start a new conversation. This creates an outbound conversation — useful for proactive outreach.

```
POST /conversations
```

### Request body

<ParamField body="contact_id" type="string" required>
  ID of the contact to start the conversation with.
</ParamField>

<ParamField body="channel_id" type="string" required>
  ID of the channel to use for this conversation.
</ParamField>

<ParamField body="message" type="object">
  Optional initial message to send. Include `content` (string) for a text message, or `template_id` for a WhatsApp template message.
</ParamField>

<ParamField body="assignee_id" type="string">
  Agent ID to assign the conversation to immediately.
</ParamField>

### Example request

```bash theme={null}
curl -X POST https://api.sahut.id/v1/conversations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "ct_01HX3C0L4N6P8Q",
    "channel_id": "ch_01HX1A8J2L4M6N",
    "message": {
      "content": "Halo Budi, ada yang bisa kami bantu?"
    }
  }'
```

## Update a conversation

Change a conversation's status, assignee, or labels.

```
PATCH /conversations/{id}
```

### Request body

<ParamField body="status" type="string">
  New status. One of: `open`, `pending`, `resolved`, `snoozed`.
</ParamField>

<ParamField body="assignee_id" type="string">
  Agent ID to assign to. Pass `null` to unassign.
</ParamField>

<ParamField body="team_id" type="string">
  Team ID to assign to.
</ParamField>

<ParamField body="labels" type="array">
  Array of label names to set on the conversation. Replaces existing labels.
</ParamField>

### Example request

```bash theme={null}
curl -X PATCH https://api.sahut.id/v1/conversations/conv_01HX2B9K3M5N7P \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "resolved",
    "labels": ["resolved-billing"]
  }'
```