ChatMessages

Introduction

ChatMessages are the content of a ChatConversation. A message has a concrete type, can contain rich text, require a reading confirmation, or relate to another intratool resource selected from the supported relatable types.

The text field uses the shared Rich Text HTML format.

Model Definition

Alias

chatMessage

Relations

Key	Relation	Type	Relation Field(s)
user	User	Belongs to	user_id
chatConversation	ChatConversation	Belongs to	chat_conversation_id
language	Language	Belongs to	lang_id
relatable	Relatable	Morph to	relatable_type, relatable_id
seenUsers	ChatMessageSeenUsers	Has many	chat_message_seen_users.chat_message_id
reactions	Reactions	Morph many	reactions.reactable_type, reactions.reactable_id
currentReaction	CurrentReaction	Morph one	reactions.reactable_type, reactions.reactable_id, reactions.user_id
translations	Translations	Morph many	translations.translatable_type, translations.translatable_id

Types

• default - A standard message.

• voiceMessage - A voice message.

Relatable types

• chatFile - Relate a ChatFile.

• chatMessage - Relate another ChatMessage.

• 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.

• survey - Relate a Survey.

• taskAssignment - Relate a TaskAssignment.

• taskExecution - Relate a TaskExecution.

• taskTemplate - Relate a TaskTemplate.

• taskTemplateComposition - Relate a TaskTemplateComposition.

Computed Properties

• hash - The hashed id of the ChatMessage.

Capabilities

• Targetables - Message visibility and eligible recipients follow the parent ChatConversation; messages do not have independent Entity Permissions.

• URL context - Message URLs resolve to access-checked context information.

• Translations - The text field is translatable.

• Notifications - Creating a message can notify eligible participants who have not muted or archived the conversation; messages requiring confirmation use a dedicated notification type.

• Reactions - Users can add one current emoji reaction and retrieve individual or summarized reactions.

• Seen and read tracking - The API tracks message visibility and explicit reading confirmations per user.

List

List ChatMessages from conversations available to the current authenticated User.

Definition

GET /api/chat/messages

Example Request

PHP

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

Example Response

[
  {
    "id": 1,
    "user_id": 3,
    "chat_conversation_id": 1,
    "forwarded_id": null,
    "lang_id": "en-US",
    "type": "default",
    "relatable_type": null,
    "relatable_id": null,
    "text": "<p>Welcome to the project chat.</p>",
    "reading_confirmation": false,
    "created_at": "2026-08-06 09:35:00",
    "updated_at": "2026-08-06 09:35:00",
    "deleted_at": null,
    "hash": "vkn978r25g37681dqwzem4px"
  },
  {
    "id": 2,
    "user_id": 4,
    "chat_conversation_id": 2,
    "forwarded_id": null,
    "lang_id": "en-US",
    "type": "default",
    "relatable_type": "infoboardPost",
    "relatable_id": 1,
    "text": "<p>Please review the linked announcement.</p>",
    "reading_confirmation": true,
    "created_at": "2026-08-06 09:40:00",
    "updated_at": "2026-08-06 09:40:00",
    "deleted_at": null,
    "hash": "q6n1vx8m4p2kr9dw5e7z0yla"
  }
]

Count

Count ChatMessages from conversations available to the current authenticated User.

Definition

GET /api/chat/messages/count

Example Request

PHP

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

Example Response

1

List by conversation

List ChatMessages for a ChatConversation.

Definition

GET /api/chat/conversations/{chatConversation}/messages

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/messages', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);

Example Response

[
  {
    "id": 1,
    "user_id": 3,
    "chat_conversation_id": 1,
    "forwarded_id": null,
    "lang_id": "en-US",
    "type": "default",
    "relatable_type": null,
    "relatable_id": null,
    "text": "<p>Welcome to the project chat.</p>",
    "reading_confirmation": false,
    "created_at": "2026-08-06 09:35:00",
    "updated_at": "2026-08-06 09:35:00",
    "deleted_at": null,
    "hash": "vkn978r25g37681dqwzem4px"
  },
  {
    "id": 2,
    "user_id": 4,
    "chat_conversation_id": 1,
    "forwarded_id": null,
    "lang_id": "en-US",
    "type": "default",
    "relatable_type": "infoboardPost",
    "relatable_id": 1,
    "text": "<p>Please review the linked announcement.</p>",
    "reading_confirmation": true,
    "created_at": "2026-08-06 09:40:00",
    "updated_at": "2026-08-06 09:40:00",
    "deleted_at": null,
    "hash": "q6n1vx8m4p2kr9dw5e7z0yla"
  }
]

Count by conversation

Count ChatMessages for a ChatConversation.

Definition

GET /api/chat/conversations/{chatConversation}/messages/count

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/messages/count', [
    'headers' => ['Authorization' => "Bearer {accessToken}"]
]);

Example Response

1

Show

Show one ChatMessage by ID or hash.

Definition

GET /api/chat/messages/{chatMessage}

Route Parameters

Parameter	Type	Description
chatMessage	integer | string	ChatMessage ID or hash.

Example Request

PHP

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

Example Response

{
  "id": 1,
  "user_id": 3,
  "chat_conversation_id": 1,
  "forwarded_id": null,
  "lang_id": "en-US",
  "type": "default",
  "relatable_type": null,
  "relatable_id": null,
  "text": "<p>Welcome to the project chat.</p>",
  "reading_confirmation": false,
  "created_at": "2026-08-06 09:35:00",
  "updated_at": "2026-08-06 09:35:00",
  "deleted_at": null,
  "hash": "vkn978r25g37681dqwzem4px"
}

Create

Create a new ChatMessage.

Definition

POST /api/chat/messages

Request Keys

Key	Type	Default	Description
chat_conversation_id*	integer	-	ID of the related ChatConversation.
lang_id	string	system language	Language key for the translatable text.
type*	string	-	Type of the ChatMessage.
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.
text	string | null	null	Message content. Required when no related entity is supplied.
reading_confirmation	boolean	false	Whether users must explicitly confirm that they read the message.

Keys with * are required.

Behavior

The authenticated user becomes the message author; a client-provided user_id is ignored. Messages cannot be created in a locked conversation.

Example Request

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('POST', '/api/chat/messages', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'chat_conversation_id' => 1,
        'type' => 'default',
        'text' => '<p>Welcome to the project chat.</p>'
    ]
]);

Example Response

{
  "status": "success",
  "data": {
    "id": 1,
    "user_id": 3,
    "chat_conversation_id": 1,
    "forwarded_id": null,
    "lang_id": "en-US",
    "type": "default",
    "relatable_type": null,
    "relatable_id": null,
    "text": "<p>Welcome to the project chat.</p>",
    "reading_confirmation": false,
    "created_at": "2026-08-06 09:35:00",
    "updated_at": "2026-08-06 09:35:00",
    "deleted_at": null,
    "hash": "vkn978r25g37681dqwzem4px"
  }
}

Forward

Forward a ChatMessage to another ChatConversation.

Definition

POST /api/chat/messages/{chatMessage}/forward

Route Parameters

Parameter	Type	Description
chatMessage	integer | string	Source ChatMessage ID or hash.

Request Keys

Key	Type	Default	Description
chat_conversation_id*	integer	-	ID of the target ChatConversation.

Keys with * are required.

Behavior

The new message retains the content of the source message, stores the source ID in forwarded_id, and uses the authenticated user as its author. Related chat files are copied to the target conversation. The target conversation must be unlocked.

Example Request

PHP

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

Example Response

{
  "status": "success",
  "data": {
    "id": 2,
    "user_id": 3,
    "chat_conversation_id": 2,
    "forwarded_id": 1,
    "lang_id": "en-US",
    "type": "default",
    "relatable_type": null,
    "relatable_id": null,
    "text": "<p>Welcome to the project chat.</p>",
    "reading_confirmation": false,
    "created_at": "2026-08-06 10:05:00",
    "updated_at": "2026-08-06 10:05:00",
    "deleted_at": null,
    "hash": "yd6er2o0pz12v6lgnw54qmv7"
  }
}

Reset

Reset supported relations of a ChatMessage.

Definition

POST /api/chat/messages/{chatMessage}/reset

Route Parameters

Parameter	Type	Description
chatMessage	integer | string	ChatMessage ID or hash.

Request Keys

Key	Type	Default	Description
reactions	boolean	false	Set to true to remove all message reactions.

Behavior

At least one resettable relation must be set to true. Only the conversation owner can reset message relations.

Example Request

PHP

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

Example Response

{
  "status": "success",
  "data": {
    "id": 1,
    "user_id": 3,
    "chat_conversation_id": 1,
    "forwarded_id": null,
    "lang_id": "en-US",
    "type": "default",
    "relatable_type": null,
    "relatable_id": null,
    "text": "<p>Welcome to the project chat.</p>",
    "reading_confirmation": false,
    "created_at": "2026-08-06 09:35:00",
    "updated_at": "2026-08-06 09:35:00",
    "deleted_at": null,
    "hash": "vkn978r25g37681dqwzem4px"
  }
}

Update

Update an existing ChatMessage.

Definition

PUT /api/chat/messages/{chatMessage}

Route Parameters

Parameter	Type	Description
chatMessage	integer | string	ChatMessage ID or hash.

Request Keys

Key	Type	Description
lang_id	string	New language key for the translatable text.
type	string	New type of the ChatMessage.
relatable_type	string | null	New relatable type. Required with relatable_id.
relatable_id	integer | null	New related entity ID. Required with relatable_type.
text	string | null	New message content. Required when no related entity is supplied.
reading_confirmation	boolean	Whether users must explicitly confirm that they read the message.

Behavior

Only the message author can update it, and only within 15 minutes of creation while the conversation is unlocked. user_id and chat_conversation_id cannot be changed by this endpoint.

Example Request

PHP

$client = new GuzzleHttp\Client(['base_uri' => 'https://{tenant}.intratool.de']);
$response = $client->request('PUT', '/api/chat/messages/1', [
    'headers' => ['Authorization' => "Bearer {accessToken}"],
    'json' => [
        'text' => '<p>Welcome to the project launch chat.</p>'
    ]
]);

Example Response

{
  "status": "success",
  "data": {
    "id": 1,
    "user_id": 3,
    "chat_conversation_id": 1,
    "forwarded_id": null,
    "lang_id": "en-US",
    "type": "default",
    "relatable_type": null,
    "relatable_id": null,
    "text": "<p>Welcome to the project launch chat.</p>",
    "reading_confirmation": false,
    "created_at": "2026-08-06 09:35:00",
    "updated_at": "2026-08-06 09:45:00",
    "deleted_at": null,
    "hash": "vkn978r25g37681dqwzem4px"
  }
}

Delete

Delete an existing ChatMessage.

Definition

DELETE /api/chat/messages/{chatMessage}

Route Parameters

Parameter	Type	Description
chatMessage	integer | string	ChatMessage ID or hash.

Behavior

Only the message author can delete it while the conversation is unlocked. Deleting a message clears its text before soft deletion.

Example Request

PHP

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

Example Response

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