OpenAPI Specification
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 pe
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/chatwoot/refs/heads/main/openapi/chatwoot-reports-api-openapi.yml