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

@@ -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**:

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

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

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)

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

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

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) }

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'

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:

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": [
         {

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": [
         {