Documents the missing account-level label CRUD endpoints in Chatwoot's
Swagger output so label management is discoverable alongside the
existing contact and conversation label APIs.
Fixes: none
Closes: none
Why
The account-level label API already exists in Chatwoot, but it was
missing from the published Swagger spec. That made label management
harder to discover even though contact and conversation label assignment
endpoints were already documented.
What this change does
- adds a `Labels` tag to the application Swagger docs
- adds the label resource and create/update payload schemas
- documents `GET/POST /api/v1/accounts/{account_id}/labels`
- documents `GET/PATCH/DELETE /api/v1/accounts/{account_id}/labels/{id}`
- regenerates the compiled Swagger JSON artifacts
Validation
- rebuilt the Swagger JSON from the source YAML
- verified the new label endpoints appear in `swagger/swagger.json`
- verified the new label endpoints appear in
`swagger/tag_groups/application_swagger.json`
- started the local Rails server and confirmed `/swagger` and
`/swagger/swagger.json` return `200 OK`
This PR adds a new standalone `GET
/api/v2/accounts/:id/reports/outgoing_messages_count` endpoint that
returns outgoing message counts grouped by agent, team, inbox, or label.
- Add API documentation for inbox, agent, and team summary report
endpoints
- These endpoints return conversation statistics grouped by
inbox/agent/team for a given date range
Endpoints documented:
GET /api/v2/accounts/{account_id}/summary_reports/inbox │ Conversation
stats grouped by inbox │
GET /api/v2/accounts/{account_id}/summary_reports/agent │ Conversation
stats grouped by agent │
GET /api/v2/accounts/{account_id}/summary_reports/team │ Conversation
stats grouped by team │
Query parameters (all endpoints):
- since - Start timestamp (Unix)
- until - End timestamp (Unix)
- business_hours - Calculate metrics using business hours only
Response fields:
- id - Inbox/Agent/Team ID
- conversations_count - Total conversations in date range
- resolved_conversations_count - Resolved conversations in date range
- avg_resolution_time - Average resolution time (seconds)
- avg_first_response_time - Average first response time (seconds)
- avg_reply_time - Average reply time (seconds)
New API Documentation
GET
/api/v2/accounts/{account_id}/reports/first_response_time_distribution
- Returns first response time distribution grouped by channel type
- Shows conversation counts in time buckets: 0-1h, 1-4h, 4-8h, 8-24h,
24h+
- Parameters: since, until (Unix timestamps)
GET /api/v2/accounts/{account_id}/reports/inbox_label_matrix
- Returns a matrix of conversation counts for inbox-label combinations
- Parameters: since, until, inbox_ids[], label_ids[]
Fixes
- Removed unused business_hours boolean parameter from
/api/v2/accounts/{account_id}/summary_reports/channel
- Updated ReDoc script from unstable @next to stable @2.1.5 version to
fix empty swagger page
This API gives you how many conversations exist per channel, broken down
by status in a given time period. The max time period is capped to 6
months for now.
**Input Params:**
- **since:** Unix timestamp (seconds) - start of date range
- **until:** Unix timestamp (seconds) - end of date range
**Response Payload:**
```json
{
"Channel::Sms": {
"resolved": 85,
"snoozed": 10,
"open": 5,
"pending": 5,
"total": 100
},
"Channel::Email": {
"resolved": 72,
"snoozed": 15,
"open": 13,
"pending": 13,
"total": 100
},
"Channel::WebWidget": {
"resolved": 90,
"snoozed": 7,
"open": 3,
"pending": 3,
"total": 100
}
}
```
**Definitons:**
resolved = Number of conversations created within the selected time
period that are currently marked as resolved.
snoozed = Number of conversations created within the selected time
period that are currently marked as snoozed.
pending = Number of conversations created within the selected time
period that are currently marked as pending.
open = Number of conversations created within the selected time period
that are currently open.
total = Total number of conversations created within the selected time
period, across all statuses.
# Pull Request Template
## Description
Updates the public swagger spec to be OpenAPI 3.0.4 compliant. Regarding
#7893, I'm investigating the use of
[oas_rails](https://github.com/a-chacon/oas_rails) to auto-generate the
documentation along with correct expected payloads.
Mostly fixes#10531, related to #7893
## Type of change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality not to work as expected)
- [ ] This change requires a documentation update
## How Has This Been Tested?
Copied spec into swagger editor, reviewed outputs:
Note that this shows two errors with the `DELETE` endpoints as
technically these should not have a `requestBody` - in which case we
should be making use of another HTTP verb or another endpoint.
## Checklist:
- [x] My code follows the style guidelines of this project
- [x] I have performed a self-review of my code
- [x] I have commented on my code, particularly in hard-to-understand
areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] Any dependent changes have been merged and published in downstream
modules
---------
Co-authored-by: Daniel Jimenez <devildan.knex@gmail.com>
Co-authored-by: Daniel Jimenez <daniel.jimenez@spark64.com>
Currently, the swagger spec doesn't follow the Swagger 2.0 specification. So, I facing 4 errors when trying generate the Golang client for chatwoot.
Due to the spec, the binary field should use format: binary beside type: string
Signed-off-by: Giau. Tran Minh <hello@giautm.dev>
Co-authored-by: Sojan Jose <sojan@pepalo.com>
This change targets the public API and is related to the Inbox with channel type API.
Exposes public inbox details under /public/api/v1/inboxes/{inbox_identifier}. This allows access to feature flags and business hours configured for the inbox.
ref: #5514
This change allows the admin user to fetch conversation metrics for an account, agents, and filter conversation metrics for a specific agent.
Fixes#4305
* Added the documentation for the conversation APIs - 8 endpoints
* Added descriptions for the existing endpoints
* Added new resource models and updated some parts of the contact API
