internal-chat : add doc

docs/espocrm-extensions/internal-chat/administration.md

@@ -0,0 +1,90 @@
+---
+icon: material/cog
+title: Administration - Internal Chat
+description: Access modes, feature toggles, limits, integrations, and user settings for Internal Chat.
+---
+
+# Administration
+
+Most extension behavior is controlled from `Administration => Internal Chat`.
+
+[Image placeholder: Administration settings]
+
+---
+
+## Settings Layout
+
+The administration screen is organized into these areas:
+
+- Access
+- Editing & Deletion
+- Polling
+- User Search
+- Limits
+- Conversation Features
+- Message Features
+- General Features
+
+This keeps access rules, limits, and feature toggles in one place without spreading configuration across multiple screens.
+
+---
+
+## What You Can Control
+
+From `Administration => Internal Chat`, administrators can control:
+
+- who can access the chat internally and in the portal
+- whether user and team lookups follow EspoCRM ACL or use the extension's ignore-ACL lookup mode
+- edit and delete grace periods
+- room and room-list polling intervals
+- message length and attachment limits
+- allowed attachment types and insert-from-source options
+- conversation features such as pinning, hiding, muting, deleting, and team-based group creation
+- message features such as reactions, reply, forward, stars, threads, quick reactions, and broadcast mentions
+- general features such as emoji button, attachments, GIF picker, custom statuses, typing indicators, read receipts, polls, scheduled messages, record previews, and portal support
+
+---
+
+## Access and Permissions
+
+If **Access Mode** or **Portal Access Mode** is left on EspoCRM ACL, access follows the `InternalChat` scope permission in roles.
+
+The lookup settings also matter for how the new conversation screen behaves:
+
+- internal user lookup
+- portal user lookup
+- team lookup
+
+These options determine whether chat selection follows normal EspoCRM ACL visibility or uses the extension's ignore-ACL lookup mode.
+
+---
+
+## User Settings
+
+Users can open the chat settings screen and adjust:
+
+- sound notifications
+- popup notification mode
+- floating widget visibility
+- notification badge pulsation
+- conversation list mode
+- emoji skin tone
+
+These are personal preferences, separate from the admin feature toggles.
+
+---
+
+## Integrations and Operational Notes
+
+- `Administration => Integrations => Klipy` is used only for the GIF picker.
+- The installer creates the required Internal Chat scheduled jobs automatically.
+- Scheduled jobs must be running if you want scheduled messages and automatic custom-status expiry to work.
+- The Event action depends on both the chat setting and the user's calendar create permission.
+
+---
+
+## See Also
+
+- [Internal Chat Overview](index.md)
+- [Conversations & Messaging](conversations-and-messaging.md)
+- [Collaboration Features](collaboration-features.md)

docs/espocrm-extensions/internal-chat/collaboration-features.md

@@ -0,0 +1,83 @@
+---
+icon: material/account-group
+title: Collaboration Features - Internal Chat
+description: Threads, polls, scheduled messages, previews, presence, notifications, and portal chat support in Internal Chat.
+---
+
+# Collaboration Features
+
+Beyond basic messaging, Internal Chat adds a set of collaboration tools that keep follow-up work inside EspoCRM instead of moving it to another system.
+
+---
+
+## Threads
+
+Internal Chat supports **Google-Chat-style threads**. Replies live under a root message, while the main room shows the root message together with its reply count.
+
+This keeps side discussions attached to the original message without filling the main timeline.
+
+---
+
+## Polls and Scheduled Messages
+
+- Create poll messages with single-answer or multiple-answer voting.
+- Schedule messages for later using quick presets or a custom date and time.
+- Review scheduled items from the dedicated **Scheduled** shortcut.
+- Edit, reschedule, send now, or cancel scheduled messages before they are sent.
+
+These workflows are controlled from `Administration => Internal Chat`.
+
+
+<img width="447" height="727" alt="Image" src="https://github.com/user-attachments/assets/f10f8bcd-73a3-4657-9a4b-600be088b018" />
+
+
+---
+
+## Record and Link Previews
+
+- Internal EspoCRM record links can render preview cards inside chat.
+- External `http` and `https` links can render preview cards from page metadata.
+- The composer can also offer an **Event** action that opens the EspoCRM calendar dialog and posts the saved event link back to the room.
+
+Record previews respect ACL. Users without access do not see the record details.
+
+
+<img width="451" height="727" alt="Image" src="https://github.com/user-attachments/assets/acb2a98c-79b7-485f-b000-d8528423fd56" />
+
+
+---
+
+## Presence and Notifications
+
+- Presence states: **online**, **busy**, **away**, and **offline**
+- Custom emoji + text statuses with optional expiry
+- Typing indicators
+- Read receipts
+- Sound notifications
+- Browser notifications
+- In-app popup notifications
+
+Users can also adjust floating-widget visibility, badge animation, list density, popup mode, and emoji skin tone from the chat settings screen.
+
+[Image placeholder: Presence and notification settings]
+
+---
+
+## Portal Support and Notes
+
+Portal users can access Internal Chat when portal support is enabled in `Administration => Internal Chat`.
+
+Notes:
+
+- GIF search requires a configured Klipy API key.
+- Scheduled sending and automatic custom-status expiry depend on EspoCRM scheduled jobs.
+- The Event action also depends on the user having permission to create calendar events.
+- The code clearly supports portal chat access, but popup notifications are defined separately and are not documented here as a portal-specific feature.
+
+---
+
+## See Also
+
+- [Internal Chat Overview](index.md)
+- [Conversations & Messaging](conversations-and-messaging.md)
+- [Administration](administration.md)

docs/espocrm-extensions/internal-chat/conversations-and-messaging.md

@@ -0,0 +1,71 @@
+---
+icon: material/forum
+title: Conversations & Messaging - Internal Chat
+description: Direct chat, group chat, composer tools, attachments, message actions, and room navigation in Internal Chat.
+---
+
+# Conversations & Messaging
+
+Internal Chat uses the same room model in both the floating widget and the full-page `/#InternalChat` view, so users can move between quick chat and full-screen work without changing context.
+
+[Image placeholder: Main chat room]
+
+---
+
+## Conversations
+
+- Start **direct chats** from the new conversation screen.
+- Create **group chats** with selected members.
+- When enabled, the new group flow can include **portal users** and a **Teams** tab for bulk-adding team members.
+- Group chats support rename, member management, admin assignment, and leave actions.
+- Rooms can be pinned, muted, hidden, marked unread, unhidden, or deleted where permitted.
+- Hidden rooms reappear automatically when a new message arrives.
+
+Most conversation controls are managed from `Administration => Internal Chat`.
+
+
+<img width="448" height="728" alt="Image" src="https://github.com/user-attachments/assets/726f13c1-4e68-4b4e-9ad3-86b5c44743bd" />
+
+
+---
+
+## Composer
+
+- Rich-text controls for bold, italic, underline, strikethrough, lists, quotes, links, and code.
+- Attachments by file picker, drag-and-drop, and paste.
+- Emoji picker, emoji autocomplete, and quick reactions.
+- Optional GIF picker.
+- Optional insert-from-source menu for configured attachment sources.
+- In-room message search with result navigation and highlighting.
+
+Attachment limits, allowed file types, and related toggles are configured from `Administration => Internal Chat`.
+
+---
+
+## Message Actions
+
+- React to messages with emoji.
+- Reply with a quoted preview.
+- Forward messages to another conversation.
+- Copy message text.
+- Star messages for quick access later.
+- Pin important messages inside a room.
+- Edit or delete your own messages within the configured grace period.
+
+These actions can be enabled or disabled from `Administration => Internal Chat`, and edit or delete limits are enforced by the backend.
+
+---
+
+## Room List
+
+The room list supports shortcut views for **Mentions**, **Starred**, **Unread**, **Groups**, **Archive**, and **Scheduled**. It also shows unread counts, mention badges, pinned rooms, muted rooms, and conversation search.
+
+Pinned conversations are limited per user, and the code currently enforces a maximum of 3 pinned rooms.
+
+---
+
+## See Also
+
+- [Internal Chat Overview](index.md)
+- [Collaboration Features](collaboration-features.md)
+- [Administration](administration.md)

docs/espocrm-extensions/internal-chat/index.md

@@ -0,0 +1,65 @@
+---
+icon: material/chat
+title: Internal Chat - EspoCRM
+description: Add direct and group chat, attachments, threads, polls, scheduled messages, presence, and portal chat support to EspoCRM.
+---
+
+# Internal Chat
+
+<!-- DOC:OVERVIEW START -->
+
+## Overview
+
+**Internal Chat** adds an embedded chat workspace to EspoCRM with a floating widget and a full-page view at `/#InternalChat`. It supports direct and group conversations, attachments, reactions, replies, forwards, threads, polls, scheduled messages, presence, and optional portal access, while keeping the data inside EspoCRM.
+
+The extension works without an external chat service. Klipy is optional and only used for GIF search. The package also includes translations for 26 languages.
+
+[Image placeholder: Internal Chat overview]
+
+<!-- DOC:OVERVIEW END -->
+
+---
+
+<!-- DOC:FEATURES START -->
+
+## Key Features
+
+- **Direct and Group Chat**: Start one-to-one conversations, create group chats, and optionally build groups from EspoCRM teams.
+- **Chat Workspace**: Use the floating widget from anywhere or switch to the full-page `/#InternalChat` view.
+- **Rich Messaging**: Send formatted messages with attachments, emoji, mentions, replies, forwards, pins, and message search.
+- **Collaboration Tools**: Use threads, polls, scheduled messages, record previews, and link previews inside chat.
+- **Presence and Notifications**: Track presence, custom statuses, typing indicators, read receipts, and message notifications.
+- **Admin Control**: Manage access, limits, polling, and feature toggles from `Administration => Internal Chat`.
+
+<!-- DOC:FEATURES END -->
+
+---
+
+<!-- DOC:USAGE START -->
+
+## Table of Contents
+
+- [Conversations & Messaging](conversations-and-messaging.md) - Main chat UI, direct and group conversations, group management, composer behavior, attachments, and message actions.
+- [Collaboration Features](collaboration-features.md) - Threads, polls, scheduled messages, previews, presence, notifications, and portal support notes.
+- [Administration](administration.md) - Access modes, settings groups, limits, user preferences, optional integrations, and operational notes.
+
+<!-- DOC:USAGE END -->
+
+---
+
+## Requires
+
+- EspoCRM >= 8.0.0
+- PHP >= 8.1
+
+---
+
+## Installation
+
+1. Download the extension package.
+2. Upload it from `Administration => Extensions`.
+3. Open `Administration => Internal Chat` to review access, limits, and enabled features.
+4. If you want GIF search, configure `Administration => Integrations => Klipy`.
+5. Make sure EspoCRM scheduled jobs are running for scheduled messages and automatic custom-status expiry.
+
+The installer registers the required Internal Chat scheduled jobs automatically.