> For the complete documentation index, see [llms.txt](https://docs.api.intratool.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.api.intratool.de/api-reference/chat/chat-conversations.md).

# ChatConversations

## Introduction

`ChatConversations` contain [ChatMessages](/api-reference/chat/chat-messages.md) and define the users and departments participating in a direct or group conversation.

A conversation may also relate to another intratool resource selected from the supported [relatable types](#relatable-types).

## Model Definition

**Alias**

`chatConversation`

**Relations**

| Key                            | Relation                                                                               | Type            | Relation Field(s)                                                 |
| ------------------------------ | -------------------------------------------------------------------------------------- | --------------- | ----------------------------------------------------------------- |
| `user`                         | [User](/api-reference/users.md)                                                        | Belongs to      | `user_id`                                                         |
| `language`                     | [Language](/api-reference/languages.md)                                                | Belongs to      | `lang_id`                                                         |
| `relatable`                    | [Relatable](#relatable-types)                                                          | Morph to        | `relatable_type`, `relatable_id`                                  |
| `departments`                  | [Departments](/api-reference/departments.md)                                           | Belongs to many | `department_chat_conversation`                                    |
| `users`                        | [Users](/api-reference/users.md)                                                       | Belongs to many | `user_chat_conversation`                                          |
| `chatMessages`                 | [ChatMessages](/api-reference/chat/chat-messages.md)                                   | Has many        | `chat_messages.chat_conversation_id`                              |
| `latestChatMessage`            | [ChatMessage](/api-reference/chat/chat-messages.md)                                    | Has one         | `chat_messages.chat_conversation_id`                              |
| `chatUserConversationSettings` | [ChatUserConversationSettings](/api-reference/chat/chat-user-conversation-settings.md) | Has one         | `chat_user_conversation_settings.chat_conversation_id`, `user_id` |
| `chatConversationEvents`       | [ChatConversationEvents](/api-reference/chat/chat-conversation-events.md)              | Has many        | `chat_conversation_events.chat_conversation_id`                   |
| `translations`                 | [Translations](/api-reference/translations.md)                                         | Morph many      | `translations.translatable_type`, `translations.translatable_id`  |

**Relatable types**

* `filemanagerDirectory` - Relate a [FilemanagerDirectory](/api-reference/filemanager/filemanager-directories.md).
* `filemanagerFile` - Relate a [FilemanagerFile](/api-reference/filemanager/filemanager-files.md).
* `form` - Relate a [Form](/api-reference/forms/forms.md).
* `formMessage` - Relate a [FormMessage](/api-reference/forms/form-messages.md).
* `infoboardComment` - Relate an [InfoboardComment](/api-reference/infoboard/infoboard-comments.md).
* `infoboardPost` - Relate an [InfoboardPost](/api-reference/infoboard/infoboard-posts.md).
* `manualChapter` - Relate a [ManualChapter](/api-reference/manual/manual-chapters.md).
* `manualEntry` - Relate a [ManualEntry](/api-reference/manual/manual-entries.md).
* `report` - Relate a `Report`.
* `taskAssignment` - Relate a [TaskAssignment](/api-reference/tasks-2/task-assignments.md).
* `taskExecution` - Relate a [TaskExecution](/api-reference/tasks-2/task-executions.md).
* `taskTemplate` - Relate a [TaskTemplate](/api-reference/tasks-2/task-templates.md).
* `taskTemplateComposition` - Relate a `TaskTemplateComposition`.

**Computed Properties**

* `hash` - The hashed `id` of the `ChatConversation`.

**Capabilities**

* [Targetables](/introduction/resource-capabilities/targetables.md) - `assign_mode`, `users`, and `departments` define the conversation participants and visibility after the `chat-show` module permission check; they do not create Entity Permissions.
* [URL context](/introduction/resource-capabilities/url-context.md) - Conversation URLs resolve to access-checked context information.
* [Translations](/introduction/resource-capabilities/translations.md) - The `title` field is translatable.
* [Notifications](/introduction/resource-capabilities/notifications.md) - Creating a conversation or adding participants can notify eligible participants who have not muted or archived it.

## List

List `ChatConversations` the current authenticated [User](/api-reference/users.md) owns or is targeted by.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/chat/conversations`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/chat/conversations', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
[
  {
    "id": 1,
    "user_id": 3,
    "lang_id": "en-US",
    "relatable_type": null,
    "relatable_id": null,
    "group": true,
    "title": "Project launch",
    "locked_at": null,
    "assign_mode": "any_of",
    "created_at": "2026-08-06 09:30:00",
    "updated_at": "2026-08-06 09:30:00",
    "deleted_at": null,
    "hash": "wrv2jd6x8g1nmlk4o970mqen"
  },
  {
    "id": 2,
    "user_id": 4,
    "lang_id": "en-US",
    "relatable_type": null,
    "relatable_id": null,
    "group": false,
    "title": null,
    "locked_at": null,
    "assign_mode": "any_of",
    "created_at": "2026-08-06 09:31:00",
    "updated_at": "2026-08-06 09:31:00",
    "deleted_at": null,
    "hash": "q6n1vx8m4p2kr9dw5e7z0yla"
  }
]
```

## Count

Count `ChatConversations` the current authenticated [User](/api-reference/users.md) owns or is targeted by.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/chat/conversations/count`

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/chat/conversations/count', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
1
```

## Show

Show one `ChatConversation` by ID or hash.

**Definition**

<mark style="color:green;">`GET`</mark> `/api/chat/conversations/{chatConversation}`

**Route Parameters**

| Parameter          | Type                  | Description                  |
| ------------------ | --------------------- | ---------------------------- |
| `chatConversation` | `integer` \| `string` | ChatConversation ID or hash. |

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('GET', '/api/chat/conversations/1', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "id": 1,
  "user_id": 3,
  "lang_id": "en-US",
  "relatable_type": null,
  "relatable_id": null,
  "group": true,
  "title": "Project launch",
  "locked_at": null,
  "assign_mode": "any_of",
  "created_at": "2026-08-06 09:30:00",
  "updated_at": "2026-08-06 09:30:00",
  "deleted_at": null,
  "hash": "wrv2jd6x8g1nmlk4o970mqen"
}
```

## Create

Create a new `ChatConversation`.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/chat/conversations`

**Request Keys**

| Key              | Type                 | Default         | Description                                                                             |
| ---------------- | -------------------- | --------------- | --------------------------------------------------------------------------------------- |
| `lang_id`        | `string`             | system language | Language key for the translatable title.                                                |
| `relatable_type` | `string` \| `null`   | `null`          | [Relatable type](#relatable-types) of the related entity. Required with `relatable_id`. |
| `relatable_id`   | `integer` \| `null`  | `null`          | ID of the related entity. Required with `relatable_type`.                               |
| `group`          | `boolean`            | `false`         | Whether the conversation is a group conversation.                                       |
| `title`          | `string` \| `null`   | `null`          | Conversation title. Required when `group` is `true`.                                    |
| `locked_at`      | `datetime` \| `null` | `null`          | Date from which the conversation is locked.                                             |
| `user_ids`       | `array`              | `[]`            | IDs of [Users](/api-reference/users.md) targeted by the conversation.                   |
| `department_ids` | `array`              | `[]`            | IDs of [Departments](/api-reference/departments.md) targeted by the conversation.       |

**Behavior**

* The authenticated user becomes the owner; a client-provided `user_id` is ignored.
* `assign_mode` is set to `any_of` and cannot be selected during creation.
* At least one existing target must be supplied across `user_ids` and `department_ids`; both arrays cannot be empty.

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/chat/conversations', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'group' => true,
        'title' => 'Project launch',
        'user_ids' => [4]
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 1,
    "user_id": 3,
    "lang_id": "en-US",
    "group": true,
    "title": "Project launch",
    "assign_mode": "any_of",
    "created_at": "2026-08-06 09:30:00",
    "updated_at": "2026-08-06 09:30:00",
    "hash": "wrv2jd6x8g1nmlk4o970mqen"
  }
}
```

## Update

Update an existing `ChatConversation`.

**Definition**

<mark style="color:blue;">`PUT`</mark> `/api/chat/conversations/{chatConversation}`

**Route Parameters**

| Parameter          | Type                  | Description                  |
| ------------------ | --------------------- | ---------------------------- |
| `chatConversation` | `integer` \| `string` | ChatConversation ID or hash. |

**Request Keys**

| Key              | Type                 | Description                                                                           |
| ---------------- | -------------------- | ------------------------------------------------------------------------------------- |
| `user_id`        | `integer`            | New owner ID. Only the current owner can transfer ownership.                          |
| `lang_id`        | `string`             | New language key for the translatable title.                                          |
| `relatable_type` | `string` \| `null`   | New [relatable type](#relatable-types). Required with `relatable_id`.                 |
| `relatable_id`   | `integer` \| `null`  | New related entity ID. Required with `relatable_type`.                                |
| `group`          | `boolean`            | Whether the conversation is a group conversation.                                     |
| `title`          | `string` \| `null`   | New conversation title.                                                               |
| `locked_at`      | `datetime` \| `null` | New date from which the conversation is locked.                                       |
| `user_ids`       | `array`              | New IDs of [Users](/api-reference/users.md) targeted by the conversation.             |
| `department_ids` | `array`              | New IDs of [Departments](/api-reference/departments.md) targeted by the conversation. |

**Behavior**

* Only the conversation owner can update it.
* The existing `assign_mode` is retained. Supplying `user_ids` or `department_ids` replaces the corresponding targets.
* The resulting combined user and department targets must remain valid for the retained `assign_mode`; with `any_of`, at least one target must remain.

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/chat/conversations/1', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'title' => 'Project launch planning'
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 1,
    "user_id": 3,
    "lang_id": "en-US",
    "relatable_type": null,
    "relatable_id": null,
    "group": true,
    "title": "Project launch planning",
    "locked_at": null,
    "assign_mode": "any_of",
    "created_at": "2026-08-06 09:30:00",
    "updated_at": "2026-08-06 09:50:00",
    "deleted_at": null,
    "hash": "wrv2jd6x8g1nmlk4o970mqen"
  }
}
```

## Update notifications

Update unread [Notifications](/api-reference/notifications.md) for a `ChatConversation` and its [ChatMessages](/api-reference/chat/chat-messages.md).

**Definition**

<mark style="color:blue;">`PUT`</mark> `/api/chat/conversations/{chatConversation}/notifications`

**Route Parameters**

| Parameter          | Type                  | Description                  |
| ------------------ | --------------------- | ---------------------------- |
| `chatConversation` | `integer` \| `string` | ChatConversation ID or hash. |

**Request Keys**

| Key       | Type       | Description                                                       |
| --------- | ---------- | ----------------------------------------------------------------- |
| `seen_at` | `datetime` | Date used to mark matching unread notifications as seen.          |
| `read_at` | `datetime` | Date used to mark matching unread notifications as read and seen. |

**Behavior**

At least one of `seen_at` or `read_at` is required. Standard result-control filters can restrict the matching notifications. The response data is the number of updated notifications.

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/chat/conversations/1/notifications', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'read_at' => '2026-08-06 10:00:00'
    ]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": 4
}
```

## Mark notifications unread

Mark the latest matching [ChatMessage](/api-reference/chat/chat-messages.md) notification in a `ChatConversation` unread for the current authenticated [User](/api-reference/users.md).

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/chat/conversations/{chatConversation}/notifications/unread`

**Route Parameters**

| Parameter          | Type                  | Description                  |
| ------------------ | --------------------- | ---------------------------- |
| `chatConversation` | `integer` \| `string` | ChatConversation ID or hash. |

**Behavior**

* The user must be allowed to view the conversation.
* Only the latest matching chat-message notification is considered. Its `read_at` value is cleared when it is currently read, while `seen_at` is preserved.
* Repeating the request is idempotent. Response data is `1` when a notification changed and `0` when no change was required.

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/chat/conversations/1/notifications/unread', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": 1
}
```

## Leave

Remove the current authenticated [User](/api-reference/users.md) from a `ChatConversation`.

**Definition**

<mark style="color:yellow;">`POST`</mark> `/api/chat/conversations/{chatConversation}/leave`

**Route Parameters**

| Parameter          | Type                  | Description                  |
| ------------------ | --------------------- | ---------------------------- |
| `chatConversation` | `integer` \| `string` | ChatConversation ID or hash. |

**Behavior**

* The owner cannot leave their own conversation.
* The authenticated user must be assigned directly to the conversation. Access through a targeted department alone does not allow the user to leave.

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/chat/conversations/1/leave', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": {
    "id": 1,
    "user_id": 3,
    "lang_id": "en-US",
    "relatable_type": null,
    "relatable_id": null,
    "group": true,
    "title": "Project launch planning",
    "locked_at": null,
    "assign_mode": "any_of",
    "created_at": "2026-08-06 09:30:00",
    "updated_at": "2026-08-06 09:50:00",
    "deleted_at": null,
    "hash": "wrv2jd6x8g1nmlk4o970mqen"
  }
}
```

## Delete

Delete an existing `ChatConversation`.

**Definition**

<mark style="color:red;">`DELETE`</mark> `/api/chat/conversations/{chatConversation}`

**Route Parameters**

| Parameter          | Type                  | Description                  |
| ------------------ | --------------------- | ---------------------------- |
| `chatConversation` | `integer` \| `string` | ChatConversation ID or hash. |

**Behavior**

Only the conversation owner can delete it.

**Example Request**

{% tabs %}
{% tab title="PHP" %}

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('DELETE', '/api/chat/conversations/1', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);
```

{% endtab %}
{% endtabs %}

**Example Response**

```json
{
  "status": "success",
  "data": null
}
```