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.

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.

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
}

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.

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
}