openapi: 3.0.3 info: title: Chatwoot Account AgentBots Reports API description: This is the API documentation for Chatwoot server. version: 1.1.0 termsOfService: https://www.chatwoot.com/terms-of-service/ contact: email: hello@chatwoot.com license: name: MIT License url: https://opensource.org/licenses/MIT servers: - url: https://app.chatwoot.com/ tags: - name: Reports description: Analytics and reporting APIs paths: /api/v1/accounts/{account_id}/reporting_events: parameters: - $ref: '#/components/parameters/account_id' get: tags: - Reports operationId: get-account-reporting-events summary: Account Reporting Events security: - userApiKey: [] description: Get paginated reporting events for the account. This endpoint returns reporting events such as first response time, resolution time, and other metrics. Only administrators can access this endpoint. Results are paginated with 25 items per page. parameters: - $ref: '#/components/parameters/page' - in: query name: since schema: type: string description: The timestamp from where events should start (Unix timestamp in seconds) - in: query name: until schema: type: string description: The timestamp from where events should stop (Unix timestamp in seconds) - in: query name: inbox_id schema: type: number description: Filter events by inbox ID - in: query name: user_id schema: type: number description: Filter events by user/agent ID - in: query name: name schema: type: string description: Filter events by event name (e.g., first_response, resolution, reply_time) responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/reporting_events_list_response' '403': description: Access denied - Only administrators can access this endpoint content: application/json: schema: $ref: '#/components/schemas/bad_request_error' /api/v2/accounts/{account_id}/reports: parameters: - $ref: '#/components/parameters/account_id' - $ref: '#/components/parameters/report_metric' - $ref: '#/components/parameters/report_type' - in: query name: id schema: type: string description: The Id of specific object in case of agent/inbox/label - in: query name: since schema: type: string description: The timestamp from where report should start. - in: query name: until schema: type: string description: The timestamp from where report should stop. get: tags: - Reports operationId: list-all-conversation-statistics summary: Get Account reports security: - userApiKey: [] description: Get Account reports for a specific type, metric and date range responses: '200': description: Success content: application/json: schema: type: array description: Array of date based conversation statistics items: type: object properties: value: type: string timestamp: type: number '404': description: reports not found content: application/json: schema: $ref: '#/components/schemas/bad_request_error' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/bad_request_error' /api/v2/accounts/{account_id}/reports/summary: parameters: - $ref: '#/components/parameters/account_id' - $ref: '#/components/parameters/report_type' - in: query name: id schema: type: string description: The Id of specific object in case of agent/inbox/label - in: query name: since schema: type: string description: The timestamp from where report should start. - in: query name: until schema: type: string description: The timestamp from where report should stop. get: tags: - Reports operationId: list-all-conversation-statistics-summary summary: Get Account reports summary security: - userApiKey: [] description: Get Account reports summary for a specific type and date range responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/account_summary' '404': description: reports not found content: application/json: schema: $ref: '#/components/schemas/bad_request_error' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/bad_request_error' /api/v2/accounts/{account_id}/reports/conversations: parameters: - $ref: '#/components/parameters/account_id' - in: query name: type schema: type: string enum: - account required: true description: Type of report get: tags: - Reports operationId: get-account-conversation-metrics summary: Account Conversation Metrics security: - userApiKey: [] description: Get conversation metrics for Account responses: '200': description: Success content: application/json: schema: type: object description: Object of account conversation metrics properties: open: type: number unattended: type: number unassigned: type: number '404': description: reports not found content: application/json: schema: $ref: '#/components/schemas/bad_request_error' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/bad_request_error' /api/v2/accounts/{account_id}/reports/conversations/: parameters: - $ref: '#/components/parameters/account_id' - in: query name: type schema: type: string enum: - agent required: true description: Type of report - in: query name: user_id schema: type: string description: The numeric ID of the user get: tags: - Reports operationId: get-agent-conversation-metrics summary: Agent Conversation Metrics security: - userApiKey: [] description: Get conversation metrics for Agent responses: '200': description: Success content: application/json: schema: type: array description: Array of agent based conversation metrics items: $ref: '#/components/schemas/agent_conversation_metrics' '404': description: reports not found content: application/json: schema: $ref: '#/components/schemas/bad_request_error' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/bad_request_error' /api/v2/accounts/{account_id}/summary_reports/channel: parameters: - $ref: '#/components/parameters/account_id' - in: query name: since schema: type: string description: The timestamp from where report should start (Unix timestamp). - in: query name: until schema: type: string description: The timestamp from where report should stop (Unix timestamp). get: tags: - Reports operationId: get-channel-summary-report summary: Get conversation statistics grouped by channel type security: - userApiKey: [] description: 'Get conversation counts grouped by channel type and status for a given date range. Returns statistics for each channel type including open, resolved, pending, snoozed, and total conversation counts. **Note:** This API endpoint is available only in Chatwoot version 4.10.0 and above. The date range is limited to a maximum of 6 months. ' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/channel_summary' '400': description: Date range exceeds 6 months limit content: application/json: schema: $ref: '#/components/schemas/bad_request_error' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/bad_request_error' /api/v2/accounts/{account_id}/summary_reports/inbox: parameters: - $ref: '#/components/parameters/account_id' - in: query name: since schema: type: string description: The timestamp from where report should start (Unix timestamp). - in: query name: until schema: type: string description: The timestamp from where report should stop (Unix timestamp). - in: query name: business_hours schema: type: boolean description: Whether to calculate metrics using business hours only. get: tags: - Reports operationId: get-inbox-summary-report summary: Get conversation statistics grouped by inbox security: - userApiKey: [] description: 'Get conversation statistics grouped by inbox for a given date range. Returns metrics for each inbox including conversation counts, resolution counts, average first response time, average resolution time, and average reply time. ' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/inbox_summary' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/bad_request_error' /api/v2/accounts/{account_id}/summary_reports/agent: parameters: - $ref: '#/components/parameters/account_id' - in: query name: since schema: type: string description: The timestamp from where report should start (Unix timestamp). - in: query name: until schema: type: string description: The timestamp from where report should stop (Unix timestamp). - in: query name: business_hours schema: type: boolean description: Whether to calculate metrics using business hours only. get: tags: - Reports operationId: get-agent-summary-report summary: Get conversation statistics grouped by agent security: - userApiKey: [] description: 'Get conversation statistics grouped by agent for a given date range. Returns metrics for each agent including conversation counts, resolution counts, average first response time, average resolution time, and average reply time. ' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/agent_summary' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/bad_request_error' /api/v2/accounts/{account_id}/summary_reports/team: parameters: - $ref: '#/components/parameters/account_id' - in: query name: since schema: type: string description: The timestamp from where report should start (Unix timestamp). - in: query name: until schema: type: string description: The timestamp from where report should stop (Unix timestamp). - in: query name: business_hours schema: type: boolean description: Whether to calculate metrics using business hours only. get: tags: - Reports operationId: get-team-summary-report summary: Get conversation statistics grouped by team security: - userApiKey: [] description: 'Get conversation statistics grouped by team for a given date range. Returns metrics for each team including conversation counts, resolution counts, average first response time, average resolution time, and average reply time. ' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/team_summary' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/bad_request_error' /api/v2/accounts/{account_id}/reports/first_response_time_distribution: parameters: - $ref: '#/components/parameters/account_id' - in: query name: since schema: type: string description: The timestamp from where report should start (Unix timestamp). - in: query name: until schema: type: string description: The timestamp from where report should stop (Unix timestamp). get: tags: - Reports operationId: get-first-response-time-distribution summary: Get first response time distribution by channel security: - userApiKey: [] description: 'Get the distribution of first response times grouped by channel type. Returns conversation counts in different time buckets (0-1h, 1-4h, 4-8h, 8-24h, 24h+) for each channel type. **Note:** This API endpoint is available only in Chatwoot version 4.11.0 and above. ' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/first_response_time_distribution' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/bad_request_error' /api/v2/accounts/{account_id}/reports/inbox_label_matrix: parameters: - $ref: '#/components/parameters/account_id' - in: query name: since schema: type: string description: The timestamp from where report should start (Unix timestamp). - in: query name: until schema: type: string description: The timestamp from where report should stop (Unix timestamp). - in: query name: inbox_ids schema: type: array items: type: integer description: Filter by specific inbox IDs. - in: query name: label_ids schema: type: array items: type: integer description: Filter by specific label IDs. get: tags: - Reports operationId: get-inbox-label-matrix summary: Get inbox-label matrix report security: - userApiKey: [] description: 'Get a matrix showing the count of conversations for each inbox-label combination. Returns a list of inboxes, labels, and a 2D matrix where each cell contains the count of conversations in a specific inbox that have a specific label applied. **Note:** This API endpoint is available only in Chatwoot version 4.11.0 and above. ' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/inbox_label_matrix' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/bad_request_error' /api/v2/accounts/{account_id}/reports/outgoing_messages_count: parameters: - $ref: '#/components/parameters/account_id' - in: query name: since schema: type: string description: The timestamp from where report should start (Unix timestamp). - in: query name: until schema: type: string description: The timestamp from where report should stop (Unix timestamp). get: tags: - Reports operationId: get-outgoing-messages-count summary: Get outgoing messages count grouped by entity security: - userApiKey: [] description: 'Get the count of outgoing messages grouped by a specified entity (agent, team, inbox, or label). When grouped by agent, messages sent by bots (AgentBot, Captain::Assistant) are excluded. **Note:** This API endpoint is available only in Chatwoot version 4.11.0 and above. ' parameters: - in: query name: group_by required: true schema: type: string enum: - agent - team - inbox - label description: The entity to group outgoing message counts by. responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/outgoing_messages_count' '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/bad_request_error' components: schemas: agent_conversation_metrics: type: object properties: id: type: number name: type: string email: type: string thumbnail: type: string availability: type: string metric: type: object properties: open: type: number unattended: type: number team_summary: type: array description: Team summary report containing conversation statistics grouped by team. items: type: object properties: id: type: number description: The team ID conversations_count: type: number description: Number of conversations assigned to the team during the date range resolved_conversations_count: type: number description: Number of conversations resolved by the team during the date range avg_resolution_time: nullable: true type: number description: Average time (in seconds) to resolve conversations. Null if no data available. avg_first_response_time: nullable: true type: number description: Average time (in seconds) for the first response. Null if no data available. avg_reply_time: nullable: true type: number description: Average time (in seconds) between replies. Null if no data available. example: - id: 1 conversations_count: 250 resolved_conversations_count: 200 avg_resolution_time: 2800 avg_first_response_time: 240 avg_reply_time: 500 - id: 2 conversations_count: 180 resolved_conversations_count: 150 avg_resolution_time: 2400 avg_first_response_time: 200 avg_reply_time: 450 bad_request_error: title: data type: object properties: description: type: string errors: type: array items: $ref: '#/components/schemas/request_error' request_error: type: object properties: field: type: string message: type: string code: type: string account_summary: type: object properties: avg_first_response_time: type: string avg_resolution_time: type: string conversations_count: type: number incoming_messages_count: type: number outgoing_messages_count: type: number resolutions_count: type: number previous: type: object properties: avg_first_response_time: type: string avg_resolution_time: type: string conversations_count: type: number incoming_messages_count: type: number outgoing_messages_count: type: number resolutions_count: type: number agent_summary: type: array description: Agent summary report containing conversation statistics grouped by agent. items: type: object properties: id: type: number description: The agent (user) ID conversations_count: type: number description: Number of conversations assigned to the agent during the date range resolved_conversations_count: type: number description: Number of conversations resolved by the agent during the date range avg_resolution_time: nullable: true type: number description: Average time (in seconds) to resolve conversations. Null if no data available. avg_first_response_time: nullable: true type: number description: Average time (in seconds) for the first response. Null if no data available. avg_reply_time: nullable: true type: number description: Average time (in seconds) between replies. Null if no data available. example: - id: 1 conversations_count: 150 resolved_conversations_count: 120 avg_resolution_time: 3600 avg_first_response_time: 300 avg_reply_time: 600 - id: 2 conversations_count: 75 resolved_conversations_count: 60 avg_resolution_time: 1800 avg_first_response_time: 180 avg_reply_time: 420 reporting_events_list_response: type: object properties: meta: $ref: '#/components/schemas/reporting_event_meta' payload: type: array items: $ref: '#/components/schemas/reporting_event' description: List of reporting events outgoing_messages_count: type: array description: Outgoing messages count report grouped by entity (agent, team, inbox, or label). items: type: object properties: id: type: number description: The ID of the grouped entity (agent, team, inbox, or label). name: type: string description: The name of the grouped entity. outgoing_messages_count: type: number description: The total number of outgoing messages for this entity in the given time range. example: - id: 1 name: Agent One outgoing_messages_count: 42 - id: 2 name: Agent Two outgoing_messages_count: 18 inbox_summary: type: array description: Inbox summary report containing conversation statistics grouped by inbox. items: type: object properties: id: type: number description: The inbox ID conversations_count: type: number description: Number of conversations created in the inbox during the date range resolved_conversations_count: type: number description: Number of conversations resolved in the inbox during the date range avg_resolution_time: nullable: true type: number description: Average time (in seconds) to resolve conversations. Null if no data available. avg_first_response_time: nullable: true type: number description: Average time (in seconds) for the first response. Null if no data available. avg_reply_time: nullable: true type: number description: Average time (in seconds) between replies. Null if no data available. example: - id: 1 conversations_count: 150 resolved_conversations_count: 120 avg_resolution_time: 3600 avg_first_response_time: 300 avg_reply_time: 600 - id: 2 conversations_count: 75 resolved_conversations_count: 60 avg_resolution_time: 1800 avg_first_response_time: 180 avg_reply_time: 420 inbox_label_matrix: type: object description: Inbox-label matrix report showing the count of conversations for each inbox-label combination. properties: inboxes: type: array description: List of inboxes included in the report items: type: object properties: id: type: number description: The inbox ID name: type: string description: The inbox name labels: type: array description: List of labels included in the report items: type: object properties: id: type: number description: The label ID title: type: string description: The label title matrix: type: array description: 2D array where matrix[i][j] represents the count of conversations in inboxes[i] with labels[j] items: type: array items: type: number example: inboxes: - id: 1 name: Website Chat - id: 2 name: Email Support labels: - id: 1 title: bug - id: 2 title: feature-request - id: 3 title: urgent matrix: - - 10 - 5 - 3 - - 8 - 12 - 2 reporting_event: type: object properties: id: type: number description: ID of the reporting event name: type: string description: Name of the event (e.g., first_response, resolution, reply_time) value: type: number format: double description: Value of the metric in seconds value_in_business_hours: type: number format: double description: Value of the metric in seconds, calculated only for business hours event_start_time: type: string format: date-time description: The timestamp when the event started event_end_time: type: string format: date-time description: The timestamp when the event ended account_id: type: number description: ID of the account conversation_id: nullable: true type: number description: ID of the conversation inbox_id: nullable: true type: number description: ID of the inbox user_id: nullable: true type: number description: ID of the user/agent created_at: type: string format: date-time description: The timestamp when the reporting event was created updated_at: type: string format: date-time description: The timestamp when the reporting event was last updated first_response_time_distribution: type: object description: First response time distribution report grouped by channel type. Shows the count of conversations with first response times in different time buckets. additionalProperties: type: object description: First response time distribution for a specific channel type (e.g., Channel::WebWidget, Channel::Api) properties: 0-1h: type: number description: Number of conversations with first response time less than 1 hour 1-4h: type: number description: Number of conversations with first response time between 1-4 hours 4-8h: type: number description: Number of conversations with first response time between 4-8 hours 8-24h: type: number description: Number of conversations with first response time between 8-24 hours 24h+: type: number description: Number of conversations with first response time greater than 24 hours example: Channel::WebWidget: 0-1h: 150 1-4h: 80 4-8h: 45 8-24h: 30 24h+: 15 Channel::Api: 0-1h: 75 1-4h: 40 4-8h: 20 8-24h: 10 24h+: 5 channel_summary: type: object description: Channel summary report containing conversation counts grouped by channel type and status. Available in version 4.10.0+. additionalProperties: type: object description: Conversation statistics for a specific channel type (e.g., Channel::WebWidget, Channel::Api) properties: open: type: number description: Number of open conversations resolved: type: number description: Number of resolved conversations pending: type: number description: Number of pending conversations snoozed: type: number description: Number of snoozed conversations total: type: number description: Total number of conversations example: Channel::WebWidget: open: 10 resolved: 20 pending: 5 snoozed: 2 total: 37 Channel::Api: open: 5 resolved: 15 pending: 3 snoozed: 1 total: 24 reporting_event_meta: type: object properties: count: type: integer description: Total number of reporting events current_page: type: integer description: Current page number total_pages: type: integer description: Total number of pages parameters: report_metric: in: query name: metric schema: type: string enum: - conversations_count - incoming_messages_count - outgoing_messages_count - avg_first_response_time - avg_resolution_time - resolutions_count required: true description: The type of metric report_type: in: query name: type schema: type: string enum: - account - agent - inbox - label - team required: true description: Type of report page: in: query name: page schema: type: integer default: 1 required: false description: The page parameter account_id: in: path name: account_id schema: type: integer required: true description: The numeric ID of the account securitySchemes: userApiKey: type: apiKey in: header name: api_access_token description: This token can be obtained by visiting the profile page or via rails console. Provides access to endpoints based on the user permissions levels. This token can be saved by an external system when user is created via API, to perform activities on behalf of the user. agentBotApiKey: type: apiKey in: header name: api_access_token description: This token should be provided by system admin or obtained via rails console. This token can be used to build bot integrations and can only access limited apis. platformAppApiKey: type: apiKey in: header name: api_access_token description: This token can be obtained by the system admin after creating a platformApp. This token should be used to provision agent bots, accounts, users and their roles. x-tagGroups: - name: Platform tags: - Accounts - Account Users - AgentBots - Users - name: Application tags: - Account AgentBots - Account - Agents - Audit Logs - Canned Responses - Contacts - Contact Labels - Conversation Assignments - Conversation Labels - Conversations - Custom Attributes - Custom Filters - Inboxes - Integrations - Labels - Messages - Profile - Reports - Teams - Webhooks - Automation Rule - Help Center - name: Client tags: - Contacts API - Conversations API - Messages API - name: Others tags: - CSAT Survey Page