From 397b0bcc9d7c74e47dd8f8f464441b1d9108ccd7 Mon Sep 17 00:00:00 2001 From: Sojan Jose Date: Thu, 5 Mar 2026 08:13:52 -0800 Subject: [PATCH] feat: allow agent bots to toggle typing status (#13705) Agent bot conversations now feel more natural because AgentBot tokens can toggle typing status, so end users see a live typing indicator in the widget while the bot is preparing a reply. This keeps the interaction responsive and human-like without weakening token authorization boundaries. ## Closes - https://github.com/chatwoot/chatwoot/issues/8928 - https://linear.app/chatwoot/issue/CW-5205 ## How to test 1. Open the widget and start a conversation as a customer. 2. Connect an AgentBot to the same inbox. 3. Trigger `toggle_typing_status` with the AgentBot token (`typing_status: on`). 4. Confirm the customer sees the typing indicator in the widget. 5. Trigger `toggle_typing_status` with `typing_status: off` and confirm the indicator disappears. ## What changed - Added `toggle_typing_status` to bot-accessible conversation endpoints. - Restricted bot-accessible endpoint usage to `AgentBot` token owners only (non-user tokens like `PlatformApp` remain unauthorized). - Updated typing status flow to preserve AgentBot identity in dispatch/broadcast paths. - Added request coverage for AgentBot success and PlatformApp unauthorized behavior. - Added Swagger documentation for `POST /api/v1/accounts/{account_id}/conversations/{conversation_id}/toggle_typing_status` and regenerated swagger artifacts. --- AGENTS.md | 9 +++ .../v1/accounts/conversations_controller.rb | 2 +- .../concerns/access_token_auth_helper.rb | 4 +- app/listeners/action_cable_listener.rb | 10 ++- .../conversations/typing_status_manager.rb | 3 +- .../accounts/conversations_controller_spec.rb | 31 +++++++ spec/listeners/action_cable_listener_spec.rb | 20 +++++ .../conversation/toggle_typing_status.yml | 41 ++++++++++ swagger/paths/index.yml | 6 ++ swagger/swagger.json | 80 +++++++++++++++++++ swagger/tag_groups/application_swagger.json | 80 +++++++++++++++++++ 11 files changed, 279 insertions(+), 7 deletions(-) create mode 100644 swagger/paths/application/conversation/toggle_typing_status.yml diff --git a/AGENTS.md b/AGENTS.md index 301633d7f..2ab6373b7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -68,6 +68,15 @@ - Example: `feat(auth): add user authentication` - Don't reference Claude in commit messages +## PR Description Format + +- Start with a short, user-facing paragraph describing the product change. +- Add a `Closes` section with relevant issue links (GitHub, Linear, etc.). +- For feature PRs, add `How to test` from a product/UX standpoint. +- For bugfix PRs, use `How to reproduce` when helpful. +- Optionally add a `What changed` section for implementation highlights. +- Do not add a `How this was tested` section listing specs/commands. + ## Project-Specific - **Translations**: diff --git a/app/controllers/api/v1/accounts/conversations_controller.rb b/app/controllers/api/v1/accounts/conversations_controller.rb index ab1cae17d..52d829441 100644 --- a/app/controllers/api/v1/accounts/conversations_controller.rb +++ b/app/controllers/api/v1/accounts/conversations_controller.rb @@ -107,7 +107,7 @@ class Api::V1::Accounts::ConversationsController < Api::V1::Accounts::BaseContro end def toggle_typing_status - typing_status_manager = ::Conversations::TypingStatusManager.new(@conversation, current_user, params) + typing_status_manager = ::Conversations::TypingStatusManager.new(@conversation, Current.user, params) typing_status_manager.toggle_typing_status head :ok end diff --git a/app/controllers/concerns/access_token_auth_helper.rb b/app/controllers/concerns/access_token_auth_helper.rb index 338b290da..b7fc14e74 100644 --- a/app/controllers/concerns/access_token_auth_helper.rb +++ b/app/controllers/concerns/access_token_auth_helper.rb @@ -1,6 +1,6 @@ module AccessTokenAuthHelper BOT_ACCESSIBLE_ENDPOINTS = { - 'api/v1/accounts/conversations' => %w[toggle_status toggle_priority create update custom_attributes], + 'api/v1/accounts/conversations' => %w[toggle_status toggle_typing_status toggle_priority create update custom_attributes], 'api/v1/accounts/conversations/messages' => ['create'], 'api/v1/accounts/conversations/assignments' => ['create'] }.freeze @@ -28,7 +28,7 @@ module AccessTokenAuthHelper def validate_bot_access_token! return if Current.user.is_a?(User) - return if agent_bot_accessible? + return if @resource.is_a?(AgentBot) && agent_bot_accessible? render_unauthorized('Access to this endpoint is not authorized for bots') end diff --git a/app/listeners/action_cable_listener.rb b/app/listeners/action_cable_listener.rb index 61aa4f535..ff099618c 100644 --- a/app/listeners/action_cable_listener.rb +++ b/app/listeners/action_cable_listener.rb @@ -180,8 +180,14 @@ class ActionCableListener < BaseListener end def typing_event_listener_tokens(account, conversation, user) - current_user_token = user.is_a?(Contact) ? conversation.contact_inbox.pubsub_token : user.pubsub_token - (user_tokens(account, conversation.inbox.members) + [conversation.contact_inbox.pubsub_token]) - [current_user_token] + current_user_token = if user.is_a?(Contact) + conversation.contact_inbox.pubsub_token + elsif user.respond_to?(:pubsub_token) + user.pubsub_token + end + + tokens = user_tokens(account, conversation.inbox.members) + [conversation.contact_inbox.pubsub_token] + current_user_token.present? ? tokens - [current_user_token] : tokens end def user_tokens(account, agents) diff --git a/app/services/conversations/typing_status_manager.rb b/app/services/conversations/typing_status_manager.rb index e3e9cebc6..c18511e69 100644 --- a/app/services/conversations/typing_status_manager.rb +++ b/app/services/conversations/typing_status_manager.rb @@ -10,8 +10,7 @@ class Conversations::TypingStatusManager end def trigger_typing_event(event, is_private) - user = @user.presence || @resource - Rails.configuration.dispatcher.dispatch(event, Time.zone.now, conversation: @conversation, user: user, is_private: is_private) + Rails.configuration.dispatcher.dispatch(event, Time.zone.now, conversation: @conversation, user: @user, is_private: is_private) end def toggle_typing_status diff --git a/spec/controllers/api/v1/accounts/conversations_controller_spec.rb b/spec/controllers/api/v1/accounts/conversations_controller_spec.rb index bc7b4097f..4b3d5cc5f 100644 --- a/spec/controllers/api/v1/accounts/conversations_controller_spec.rb +++ b/spec/controllers/api/v1/accounts/conversations_controller_spec.rb @@ -647,6 +647,37 @@ RSpec.describe 'Conversations API', type: :request do .with(Conversation::CONVERSATION_TYPING_ON, kind_of(Time), { conversation: conversation, user: agent, is_private: true }) end end + + context 'when it is an authenticated bot' do + let(:agent_bot) { create(:agent_bot, account: account) } + + it 'toggles the conversation typing status' do + create(:agent_bot_inbox, inbox: conversation.inbox, agent_bot: agent_bot) + allow(Rails.configuration.dispatcher).to receive(:dispatch) + + post "/api/v1/accounts/#{account.id}/conversations/#{conversation.display_id}/toggle_typing_status", + headers: { api_access_token: agent_bot.access_token.token }, + params: { typing_status: 'on', is_private: false }, + as: :json + + expect(response).to have_http_status(:success) + expect(Rails.configuration.dispatcher).to have_received(:dispatch) + .with(Conversation::CONVERSATION_TYPING_ON, kind_of(Time), { conversation: conversation, user: agent_bot, is_private: false }) + end + end + + context 'when it is an authenticated platform app token' do + let(:platform_app) { create(:platform_app) } + + it 'returns unauthorized' do + post "/api/v1/accounts/#{account.id}/conversations/#{conversation.display_id}/toggle_typing_status", + headers: { api_access_token: platform_app.access_token.token }, + params: { typing_status: 'on', is_private: false }, + as: :json + + expect(response).to have_http_status(:unauthorized) + end + end end describe 'POST /api/v1/accounts/{account.id}/conversations/:id/update_last_seen' do diff --git a/spec/listeners/action_cable_listener_spec.rb b/spec/listeners/action_cable_listener_spec.rb index 1aecc3779..8b18f1582 100644 --- a/spec/listeners/action_cable_listener_spec.rb +++ b/spec/listeners/action_cable_listener_spec.rb @@ -94,6 +94,26 @@ describe ActionCableListener do end end + describe '#typing_on with agent bot' do + let(:event_name) { :'conversation.typing_on' } + let!(:agent_bot) { create(:agent_bot, account: account) } + let!(:event) { Events::Base.new(event_name, Time.zone.now, conversation: conversation, user: agent_bot, is_private: false) } + + it 'sends message to account admins, inbox agents and the contact' do + expect(conversation.inbox.reload.inbox_members.count).to eq(1) + expect(ActionCableBroadcastJob).to receive(:perform_later).with( + a_collection_containing_exactly( + admin.pubsub_token, agent.pubsub_token, conversation.contact_inbox.pubsub_token + ), + 'conversation.typing_on', { conversation: conversation.push_event_data, + user: agent_bot.push_event_data, + account_id: account.id, + is_private: false } + ) + listener.conversation_typing_on(event) + end + end + describe '#typing_off' do let(:event_name) { :'conversation.typing_off' } let!(:event) { Events::Base.new(event_name, Time.zone.now, conversation: conversation, user: agent, is_private: false) } diff --git a/swagger/paths/application/conversation/toggle_typing_status.yml b/swagger/paths/application/conversation/toggle_typing_status.yml new file mode 100644 index 000000000..4c3a86ae9 --- /dev/null +++ b/swagger/paths/application/conversation/toggle_typing_status.yml @@ -0,0 +1,41 @@ +tags: + - Conversations +operationId: toggle-typing-status-of-a-conversation +summary: Toggle Typing Status +description: Toggles the typing status for a conversation. +security: + - userApiKey: [] + - agentBotApiKey: [] +requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - typing_status + properties: + typing_status: + type: string + enum: ['on', 'off'] + description: Typing status to set. + example: 'on' + is_private: + type: boolean + description: Whether the typing event is for private notes. + example: false +responses: + '200': + description: Success + '401': + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/bad_request_error' + '404': + description: Conversation not found + content: + application/json: + schema: + $ref: '#/components/schemas/bad_request_error' diff --git a/swagger/paths/index.yml b/swagger/paths/index.yml index 284bb7825..3f8bab7d9 100644 --- a/swagger/paths/index.yml +++ b/swagger/paths/index.yml @@ -367,6 +367,12 @@ - $ref: '#/components/parameters/conversation_id' post: $ref: ./application/conversation/toggle_priority.yml +/api/v1/accounts/{account_id}/conversations/{conversation_id}/toggle_typing_status: + parameters: + - $ref: '#/components/parameters/account_id' + - $ref: '#/components/parameters/conversation_id' + post: + $ref: ./application/conversation/toggle_typing_status.yml /api/v1/accounts/{account_id}/conversations/{conversation_id}/custom_attributes: parameters: diff --git a/swagger/swagger.json b/swagger/swagger.json index adde81e9f..d721affa4 100644 --- a/swagger/swagger.json +++ b/swagger/swagger.json @@ -4938,6 +4938,86 @@ } } }, + "/api/v1/accounts/{account_id}/conversations/{conversation_id}/toggle_typing_status": { + "parameters": [ + { + "$ref": "#/components/parameters/account_id" + }, + { + "$ref": "#/components/parameters/conversation_id" + } + ], + "post": { + "tags": [ + "Conversations" + ], + "operationId": "toggle-typing-status-of-a-conversation", + "summary": "Toggle Typing Status", + "description": "Toggles the typing status for a conversation.", + "security": [ + { + "userApiKey": [] + }, + { + "agentBotApiKey": [] + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "typing_status" + ], + "properties": { + "typing_status": { + "type": "string", + "enum": [ + "on", + "off" + ], + "description": "Typing status to set.", + "example": "on" + }, + "is_private": { + "type": "boolean", + "description": "Whether the typing event is for private notes.", + "example": false + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Success" + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/bad_request_error" + } + } + } + }, + "404": { + "description": "Conversation not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/bad_request_error" + } + } + } + } + } + } + }, "/api/v1/accounts/{account_id}/conversations/{conversation_id}/custom_attributes": { "parameters": [ { diff --git a/swagger/tag_groups/application_swagger.json b/swagger/tag_groups/application_swagger.json index 748722875..844be0350 100644 --- a/swagger/tag_groups/application_swagger.json +++ b/swagger/tag_groups/application_swagger.json @@ -3481,6 +3481,86 @@ } } }, + "/api/v1/accounts/{account_id}/conversations/{conversation_id}/toggle_typing_status": { + "parameters": [ + { + "$ref": "#/components/parameters/account_id" + }, + { + "$ref": "#/components/parameters/conversation_id" + } + ], + "post": { + "tags": [ + "Conversations" + ], + "operationId": "toggle-typing-status-of-a-conversation", + "summary": "Toggle Typing Status", + "description": "Toggles the typing status for a conversation.", + "security": [ + { + "userApiKey": [] + }, + { + "agentBotApiKey": [] + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "typing_status" + ], + "properties": { + "typing_status": { + "type": "string", + "enum": [ + "on", + "off" + ], + "description": "Typing status to set.", + "example": "on" + }, + "is_private": { + "type": "boolean", + "description": "Whether the typing event is for private notes.", + "example": false + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Success" + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/bad_request_error" + } + } + } + }, + "404": { + "description": "Conversation not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/bad_request_error" + } + } + } + } + } + } + }, "/api/v1/accounts/{account_id}/conversations/{conversation_id}/custom_attributes": { "parameters": [ {