> For the complete documentation index, see [llms.txt](https://api-docs.myhappyforce.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.myhappyforce.com/docs/api-reference/conversations-stats-resource.md).

# Conversations Stats Resource

## Aggregated conversation statistics

> Returns aggregated counts for the conversations summary box: totals by lifecycle state (open/closed), by last-message author (pendingReply/replied), by read state (unread/read), a breakdown of the closed conversations by close reason, plus average first-response and resolution times and the number assigned to the caller. The filters accepted here mirror the conversation list endpoint (minus pagination), so the summary stays coherent with the visible list. All counts are computed over the FULL filtered set — each axis does not ignore its own filter — so open + closed == total and the sum of byCloseReason == closed.

```json
{"openapi":"3.1.0","info":{"title":"Happyforce API","version":"v1"},"tags":[],"servers":[{"url":"{url}","description":"API URL","variables":{"url":{"description":"API Environment","enum":["https://api.happyforce.com","https://staging.happyforce.com","http://localhost:9000"],"default":"https://api.happyforce.com"}}}],"security":[{"companyAPISessionId":[]}],"components":{"securitySchemes":{"companyAPISessionId":{"type":"apiKey","description":"SessionId","name":"SessionId","in":"header"}},"schemas":{"UserType":{"type":"string","description":"Type of user in the system, either an employee or a company user (admin, manager, etc).","enum":["EMPLOYEE","COMPANY_USER"]},"ConversationState":{"type":"string","enum":["OPEN","CLOSED"]},"ConversationReadState":{"type":"string","enum":["UNREAD","READ"]},"ConversationStatsDTO":{"type":"object","description":"Aggregated conversation counts for the dashboard summary box.","properties":{"total":{"type":"integer","format":"int64","description":"Total conversations in the filtered scope."},"open":{"type":"integer","format":"int64","description":"Conversations in the OPEN lifecycle state (not closed)."},"closed":{"type":"integer","format":"int64","description":"Conversations in the CLOSED lifecycle state."},"pendingReply":{"type":"integer","format":"int64","description":"Conversations whose last message is from the employee, i.e. awaiting a company reply."},"replied":{"type":"integer","format":"int64","description":"Conversations whose last message is from the company, i.e. already replied."},"unread":{"type":"integer","format":"int64","description":"Conversations unread from the dashboard user's point of view."},"read":{"type":"integer","format":"int64","description":"Conversations read from the dashboard user's point of view."},"byCloseReason":{"type":"object","additionalProperties":{"type":"integer","format":"int64"},"description":"Breakdown of the closed conversations by close reason. Every ConversationCloseReason key is always present, with value 0 when none. The values sum to 'closed'."},"avgFirstResponseHours":{"type":"number","format":"double","description":"Average hours from creation to the first company reply. Null when no conversation has been replied to in scope."},"avgResolutionHours":{"type":"number","format":"double","description":"Average hours from creation to close. Null when no conversation is closed in scope."},"ownedByMe":{"type":"integer","format":"int64","description":"Conversations assigned to the requesting user."}}}}},"paths":{"/api/v1/company/stats/conversations":{"get":{"tags":["conversations-stats-resource"],"summary":"Aggregated conversation statistics","description":"Returns aggregated counts for the conversations summary box: totals by lifecycle state (open/closed), by last-message author (pendingReply/replied), by read state (unread/read), a breakdown of the closed conversations by close reason, plus average first-response and resolution times and the number assigned to the caller. The filters accepted here mirror the conversation list endpoint (minus pagination), so the summary stays coherent with the visible list. All counts are computed over the FULL filtered set — each axis does not ignore its own filter — so open + closed == total and the sum of byCloseReason == closed.","operationId":"getConversationsStats","parameters":[{"name":"lastMessageFrom","in":"query","description":"Filter by the author type of the last message: EMPLOYEE or COMPANY_USER; omitted for any.","required":false,"schema":{"$ref":"#/components/schemas/UserType"}},{"name":"from","in":"query","description":"Inclusive lower bound for the conversation's last activity, format ddMMyyyy.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"Inclusive upper bound for the conversation's last activity, format ddMMyyyy.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"ownerId","in":"query","description":"Restrict to conversations owned by these assignees (admins only; ignored for managers).","required":false,"schema":{"type":"string"}},{"name":"personEncryptedId","in":"query","description":"Restrict to conversations of a single participant, given as the person's encrypted id.","required":false,"schema":{"type":"string"}},{"name":"types","in":"query","description":"Restrict to these origin types: COMMENT and/or ENGAGEMENT_STATUS; omitted for any.","required":false,"schema":{"type":"array","items":{"type":"string","enum":["COMMENT","ENGAGEMENT_STATUS"]},"uniqueItems":true}},{"name":"state","in":"query","description":"Filter by lifecycle state: OPEN, CLOSED, or omitted for both.","required":false,"schema":{"$ref":"#/components/schemas/ConversationState"}},{"name":"readState","in":"query","description":"Filter by read state from the requesting dashboard user's point of view: READ, UNREAD, or omitted for both.","required":false,"schema":{"$ref":"#/components/schemas/ConversationReadState"}}],"responses":{"200":{"description":"The aggregated statistics for the filtered scope","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ConversationStatsDTO"}}}},"403":{"description":"The caller does not have a role allowed to view conversations"}}}}}}
```
