For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

Belongs to

user_id

language

Belongs to

lang_id

relatable

Morph to

relatable_type, relatable_id

departments

Belongs to many

department_chat_conversation

users

Belongs to many

user_chat_conversation

chatMessages

Has many

chat_messages.chat_conversation_id

latestChatMessage

Has one

chat_messages.chat_conversation_id

chatUserConversationSettings

Has one

chat_user_conversation_settings.chat_conversation_id, user_id

chatConversationEvents

Has many

chat_conversation_events.chat_conversation_id

translations

Morph many

translations.translatable_type, translations.translatable_id

Relatable types

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

Example Response

Count

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

Definition

GET /api/chat/conversations/count

Example Request

Example Response

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

Example Response

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

Example Response

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

Example Response

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

Example Response

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

Example Response

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

Example Response

Last updated