# Conversations

Conversations are per-contact message threads spanning all channels (SMS, email,
WhatsApp, etc.). A contact has at most one open conversation per location. New
inbound or outbound messages auto-create the conversation if it does not exist.

## List conversations for a contact

`GET /api/contacts/{contact_id}/conversations`

Lists the conversations of one contact, ordered by most recent activity.
There is typically
one per contact-location pair, but historical conversations remain queryable.

### Path parameters

- `contact_id` (integer, required) — Contact ID.

### Example request

```bash
curl --request GET \
    --get "https://klozzo.com/api/contacts/42/conversations" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
```

### Response `200`

```json
{
    "data": [
        {
            "id": 17,
            "contact_id": 42,
            "location_id": 1,
            "last_message_at": "2026-06-05T13:42:00+00:00",
            "last_channel": "whatsapp",
            "unread_count": 3
        }
    ]
}
```

## Open or fetch a conversation for a contact

`POST /api/contacts/{contact_id}/conversations`

Opens a conversation for one contact, or hands back the one that already
exists. Idempotent: returns the existing conversation for the contact-location pair
when one already exists (200), or creates and returns a fresh one (201).

### Path parameters

- `contact_id` (integer, required) — Contact ID.

### Example request

```bash
curl --request POST \
    "https://klozzo.com/api/contacts/42/conversations" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
```

### Response `200` — already existed

```json
{
    "data": {
        "id": 17,
        "contact_id": 42,
        "location_id": 1,
        "last_message_at": "2026-06-05T13:42:00+00:00",
        "last_channel": "whatsapp",
        "unread_count": 3
    }
}
```

### Response `201` — newly created

```json
{
    "data": {
        "id": 17,
        "contact_id": 42,
        "location_id": 1,
        "last_message_at": null,
        "last_channel": null,
        "unread_count": 0
    }
}
```

## Fetch a conversation

`GET /api/conversations/{id}`

Returns one conversation by id: the thread, the contact it belongs to and
its channel. Use it to check
the state of a thread you were handed the id of; to read the messages,
call `GET /api/conversations/{id}/messages`, which is paginated because a
WhatsApp thread is not.

### Path parameters

- `id` (integer, required) — Conversation ID.

### Example request

```bash
curl --request GET \
    --get "https://klozzo.com/api/conversations/17" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
```

### Response `200`

```json
{
    "data": {
        "id": 17,
        "contact_id": 42,
        "location_id": 1,
        "last_message_at": "2026-06-05T13:42:00+00:00",
        "last_channel": "whatsapp",
        "unread_count": 3
    }
}
```

### Response `403` — The contact behind it is not visible to you

```json
{
    "message": "This action is unauthorized."
}
```

### Response `404` — Does not exist, or belongs to another location

```json
{
    "message": "No query results for model."
}
```