ChatConversations

Introduction

ChatConversations contain ChatMessages 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.

Model Definition

Alias

chatConversation

Relations

Key	Relation	Type	Relation Field(s)
user	User	Belongs to	user_id
language	Language	Belongs to	lang_id
relatable	Relatable	Morph to	relatable_type, relatable_id
departments	Departments	Belongs to many	department_chat_conversation
users	Users	Belongs to many	user_chat_conversation
chatMessages	ChatMessages	Has many	chat_messages.chat_conversation_id
latestChatMessage	ChatMessage	Has one	chat_messages.chat_conversation_id
chatUserConversationSettings	ChatUserConversationSettings	Has one	chat_user_conversation_settings.chat_conversation_id, user_id
chatConversationEvents	ChatConversationEvents	Has many	chat_conversation_events.chat_conversation_id
translations	Translations	Morph many	translations.translatable_type, translations.translatable_id

Relatable types

• filemanagerDirectory - Relate a FilemanagerDirectory.

• filemanagerFile - Relate a FilemanagerFile.

• form - Relate a Form.

• formMessage - Relate a FormMessage.

• infoboardComment - Relate an InfoboardComment.

• infoboardPost - Relate an InfoboardPost.

• manualChapter - Relate a ManualChapter.

• manualEntry - Relate a ManualEntry.

• report - Relate a Report.

• taskAssignment - Relate a TaskAssignment.

• taskExecution - Relate a TaskExecution.

• taskTemplate - Relate a TaskTemplate.

• taskTemplateComposition - Relate a TaskTemplateComposition.

Computed Properties

• hash - The hashed id of the ChatConversation.

Capabilities

• Targetables - 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 - Conversation URLs resolve to access-checked context information.

• Translations - The title field is translatable.

• Notifications - Creating a conversation or adding participants can notify eligible participants who have not muted or archived it.

List

List ChatConversations the current authenticated User owns or is targeted by.

Definition

GET /api/chat/conversations

Example Request

PHP

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

Example Response

[
  {
    "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 owns or is targeted by.

Definition

GET /api/chat/conversations/count

Example Request

PHP

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

Example Response

1

Show

Show one ChatConversation by ID or hash.

Definition

GET /api/chat/conversations/{chatConversation}

Route Parameters

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

Example Request

PHP

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

Example Response

{
  "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

POST /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 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 targeted by the conversation.
department_ids	array	[]	IDs of Departments 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.

• The distinct participant count must fit the configured conversation limit. It includes the owner, directly targeted users, and users whose current role belongs to a targeted department. Overlapping selections count each user once; inactive users count, while deleted users do not. Exceeding the limit produces a validation error for assign_mode.

Example Request

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]
    ]
]);

Example Response

{
  "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

PUT /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. 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 targeted by the conversation.
department_ids	array	New IDs of Departments 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.

• The participant limit is checked against the resulting owner and targets, including unchanged targets. A conversation already above the limit can be updated while its participant count stays the same or decreases; increasing that count is rejected.

Example Request

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'
    ]
]);

Example Response

{
  "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 for a ChatConversation and its ChatMessages.

Definition

PUT /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

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'
    ]
]);

Example Response

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

Mark notifications unread

Mark the latest matching ChatMessage notification in a ChatConversation unread for the current authenticated User.

Definition

POST /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

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}"]
]);

Example Response

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

Leave

Remove the current authenticated User from a ChatConversation.

Definition

POST /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

PHP

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

Example Response

{
  "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

DELETE /api/chat/conversations/{chatConversation}

Route Parameters

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

Behavior

Only the conversation owner can delete it. Deletion removes notifications for the conversation and its messages and clears their outstanding push deliveries.

Example Request

PHP

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

Example Response

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