|# Chat
|
|OBP provides a built-in Chat / Messaging API that allows users and applications to communicate within the platform.
|
|Chat is the persistent, human-facing side of messaging: rooms, threads, reactions and read markers, all stored in the database. Messages between AI agents belong somewhere else. For short-lived agent-to-agent messages, discovery and presence, see [Signal Channels](http://localhost:5174/glossary#Signal-Channels), which are Redis-backed, are never written to the database, and expire when a channel goes quiet.
|
|Chat Rooms can be scoped to a specific Bank (bank-level) or be system-wide (system-level).
|
|## Key Concepts
|
|### Chat Rooms
|A Chat Room is a named space where participants exchange messages.
|
|A system-level room called **general** is created automatically at startup with **is_open_room = true** — meaning every authenticated user can read and send messages without needing an explicit Participant record.
|
|Each room has:
|- A unique **joining key** (UUID) that can be shared to invite others. The key can be refreshed to revoke access.
|- A **name** that is unique within its scope (per bank, or globally for system-level rooms).
|- An optional **bank_id** — if set, the room is scoped to that bank. If empty, it is a system-level room.
|- An **is_open_room** flag — if true, all authenticated users are treated as implicit participants without needing a database record. They can read and send messages but have no special permissions.
|
|### Participants
|A Participant is a user or consumer (application/bot) that belongs to a Chat Room. Participants can:
|- Send and read messages.
|- Have a granular **permissions** list that controls what management actions they can perform.
|- Optionally specify a **webhook_url** to receive HTTP POST notifications for room events (new messages, mentions, etc.).
|
|Participants join rooms by presenting the room's joining key. The room creator automatically receives all permissions.
|
|### Participant Permissions
|Permissions are stored as a list on each Participant record. Possible values:
|- **can_delete_message** — delete any message in the room
|- **can_remove_participant** — remove other participants from the room
|- **can_refresh_joining_key** — regenerate the room's joining key
|- **can_update_room** — edit the room name and description
|- **can_manage_permissions** — grant or revoke permissions for other participants, and add participants directly
|
|Any participant can send messages, read messages, and add emoji reactions without special permissions. A participant can also remove themselves (leave the room) without needing the can_remove_participant permission.
|
|### OBP-Level Roles
|In addition to room-level permissions, OBP Roles provide platform-wide moderation:
|- **CanDeleteBankChatRoom** — delete any chat room within a bank
|- **CanDeleteSystemChatRoom** — delete any system-level chat room
|- **CanArchiveBankChatRoom** — archive any chat room within a bank
|- **CanArchiveSystemChatRoom** — archive any system-level chat room
|
|Bank-scoped roles apply per bank; system-scoped roles apply to system-level chat rooms. Both kinds apply regardless of room-level permissions.
|
|### Consumer / Bot Participation
|API Consumers (applications) can participate in chat rooms alongside human users. A Participant record stores either a user_id or a consumer_id (not both). This enables automated assistants, notification bots, and integrations.
|
|### Messages
|Messages support:
|- **@mentions** — the mentioned_user_ids field tracks which users are referenced in a message.
|- **Threading** — a message can reference a thread_id (the root message) to form a conversation thread.
|- **Editing** — only the sender can edit their own message.
|- **Soft deletion** — messages are marked as deleted rather than removed, preserving audit trails.
|- **Emoji reactions** — participants can react to messages with emoji. Each user can add a given emoji to a message only once.
|
|### Typing Indicators
|Typing state is ephemeral and stored in Redis with a short TTL (5 seconds). No database records are created.
|
|### Polling
|Clients retrieve new messages by polling the GET messages endpoint with a **since** parameter (timestamp). This avoids the complexity of WebSocket infrastructure while providing a simple, reliable mechanism for near-real-time updates.
|
|### gRPC Streaming (real-time)
|For clients that need true real-time updates without polling, OBP exposes a **ChatStreamService** over gRPC (see `chat.proto`, package `code.obp.grpc.chat.g1`). It provides four server-streaming / bidirectional RPCs:
|- **StreamMessages(StreamMessagesRequest) → stream ChatMessageEvent** — push new/edited/deleted messages for a given chat room as they happen.
|- **StreamTyping(stream TypingEvent) → stream TypingIndicator** — bidirectional stream: clients send their own typing state, server fans out typing indicators from other participants.
|- **StreamPresence(StreamPresenceRequest) → stream PresenceEvent** — online/offline updates for participants in a room.
|- **StreamUnreadCounts(StreamUnreadCountsRequest) → stream UnreadCountEvent** — per-room unread counters for the authenticated user.
|
|gRPC calls are authenticated via the same credentials as REST (see `AuthInterceptor`). The REST polling endpoints remain the canonical API; the gRPC streams are an optional push channel for clients that want lower latency and less request overhead.
|
|## API Endpoints
|
|All chat REST endpoints are available in two forms:
|- **Bank-scoped**: /banks/BANK_ID/chat-rooms/...
|- **System-level**: /chat-rooms/...
|
|See the API Explorer for the full list of Chat endpoints, tagged with **Chat**. For the real-time streaming surface, see `chat.proto` / `ChatStreamServiceImpl`.
|