> 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-resource.md).

# Conversations Resource

## GET /api/v1/company/conversations/{conversationId}

>

```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":{"ConversationDTO":{"allOf":[{"$ref":"#/components/schemas/ConversationHeaderDTO"},{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["COMMENT","ENGAGEMENT_STATUS"]},"name":{"type":"string"},"commentId":{"type":"string"},"updated":{"type":"boolean"},"updatedOn":{"type":"string","format":"date-time"},"title":{"type":"string","deprecated":true},"hierarchyName":{"type":"string","deprecated":true},"imagePath":{"type":"string"},"owned":{"type":"boolean"},"closed":{"type":"boolean","description":"Whether the conversation is closed. Posting a message while closed reopens the conversation, so the composer should stay enabled."},"closedOn":{"type":"string","format":"date-time","description":"Date the conversation was closed, when closed is true"},"closeReason":{"$ref":"#/components/schemas/ConversationCloseReason","description":"Reason the conversation was closed, when closed is true. Clients translate the enum to a localized label."},"closeReasonNote":{"type":"string","description":"Free-text note accompanying the close reason, when provided"},"stateHistory":{"type":"array","description":"Chronological history of lifecycle transitions (closes and reopens). Present when the conversation has been closed at least once.","items":{"$ref":"#/components/schemas/ConversationStateChangeDTO"}},"allowedCloseReasons":{"type":"array","description":"Close reasons the current user may use to close THIS conversation, given their role in it (participant vs owner). The client should offer exactly these; the backend validates against the same set.","items":{"$ref":"#/components/schemas/ConversationCloseReason"}},"signature":{"$ref":"#/components/schemas/SignatureDTO"},"messages":{"type":"array","description":"Messages in this conversation","items":{"$ref":"#/components/schemas/ConversationMessageDTO"}}}}],"description":"Full conversation: header fields plus list of messages."},"ConversationHeaderDTO":{"type":"object","description":"Conversation header: id, type, name, comment id, updated, dates, owner, closed state, signature, and messages.","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["COMMENT","ENGAGEMENT_STATUS"]},"name":{"type":"string"},"commentId":{"type":"string"},"updated":{"type":"boolean"},"updatedOn":{"type":"string","format":"date-time"},"title":{"type":"string","deprecated":true},"hierarchyName":{"type":"string","deprecated":true},"imagePath":{"type":"string"},"owned":{"type":"boolean"},"closed":{"type":"boolean","description":"Whether the conversation is closed. Posting a message while closed reopens the conversation, so the composer should stay enabled."},"closedOn":{"type":"string","format":"date-time","description":"Date the conversation was closed, when closed is true"},"closeReason":{"$ref":"#/components/schemas/ConversationCloseReason","description":"Reason the conversation was closed, when closed is true. Clients translate the enum to a localized label."},"closeReasonNote":{"type":"string","description":"Free-text note accompanying the close reason, when provided"},"stateHistory":{"type":"array","description":"Chronological history of lifecycle transitions (closes and reopens). Present when the conversation has been closed at least once.","items":{"$ref":"#/components/schemas/ConversationStateChangeDTO"}},"allowedCloseReasons":{"type":"array","description":"Close reasons the current user may use to close THIS conversation, given their role in it (participant vs owner). The client should offer exactly these; the backend validates against the same set.","items":{"$ref":"#/components/schemas/ConversationCloseReason"}},"signature":{"$ref":"#/components/schemas/SignatureDTO"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ConversationMessageDTO"}}}},"ConversationCloseReason":{"type":"string","enum":["RESOLVED","HANDLED","NO_ACTION_NEEDED","DUPLICATE","NOT_INTERESTED","PREFER_NOT_TO_CONTINUE","OTHER"]},"ConversationStateChangeDTO":{"type":"object","description":"A single conversation lifecycle transition (close or reopen): when it happened, the resulting state, who acted, and the close reason/note for close transitions.","properties":{"date":{"type":"string","format":"date-time","description":"When the transition happened"},"state":{"$ref":"#/components/schemas/ConversationState","description":"Resulting state: CLOSED on a close, OPEN on a reopen"},"actor":{"type":"string","description":"Id of the user who performed the transition. Omitted for employee actions on anonymous conversations."},"userType":{"$ref":"#/components/schemas/UserType","description":"Whether the actor acted as an employee or a company user (manager/admin)"},"reason":{"$ref":"#/components/schemas/ConversationCloseReason","description":"Close reason for CLOSED transitions; null for reopens. Clients translate the enum to a localized label."},"note":{"type":"string","description":"Free-text close note, when provided. Omitted for employee actions on anonymous conversations."}}},"ConversationState":{"type":"string","enum":["OPEN","CLOSED"]},"UserType":{"type":"string","description":"Type of user in the system, either an employee or a company user (admin, manager, etc).","enum":["EMPLOYEE","COMPANY_USER"]},"SignatureDTO":{"type":"object","description":"Signature (author) of a comment: id, name, description, and profile image.","properties":{"id":{"type":"string","description":"User ID of the signer"},"name":{"type":"string","description":"Display name of the signer"},"description":{"type":"string","description":"Optional description (e.g. role)"},"profileImagePath":{"type":"string","description":"URL or path to the profile image"}}},"ConversationMessageDTO":{"type":"object","description":"Single message in a conversation: date, text, user type, seen, owned, anonymous, signature.","properties":{"date":{"type":"string","format":"date-time","description":"Message date and time"},"message":{"type":"string","description":"Message text"},"userType":{"$ref":"#/components/schemas/UserType","description":"Type of user who sent the message"},"seen":{"type":"boolean","description":"Whether the message has been seen"},"owned":{"type":"boolean","description":"Whether the message is from the current user"},"signature":{"$ref":"#/components/schemas/SignatureDTO","description":"Signature when not anonymous"},"anonymous":{"type":"boolean"}}}}},"paths":{"/api/v1/company/conversations/{conversationId}":{"get":{"tags":["conversations-resource"],"operationId":"getConversation","parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ConversationDTO"}}}}}}}}}
```

## PUT /api/v1/company/conversations/{conversationId}

>

```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":{"ConversationDTO":{"allOf":[{"$ref":"#/components/schemas/ConversationHeaderDTO"},{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["COMMENT","ENGAGEMENT_STATUS"]},"name":{"type":"string"},"commentId":{"type":"string"},"updated":{"type":"boolean"},"updatedOn":{"type":"string","format":"date-time"},"title":{"type":"string","deprecated":true},"hierarchyName":{"type":"string","deprecated":true},"imagePath":{"type":"string"},"owned":{"type":"boolean"},"closed":{"type":"boolean","description":"Whether the conversation is closed. Posting a message while closed reopens the conversation, so the composer should stay enabled."},"closedOn":{"type":"string","format":"date-time","description":"Date the conversation was closed, when closed is true"},"closeReason":{"$ref":"#/components/schemas/ConversationCloseReason","description":"Reason the conversation was closed, when closed is true. Clients translate the enum to a localized label."},"closeReasonNote":{"type":"string","description":"Free-text note accompanying the close reason, when provided"},"stateHistory":{"type":"array","description":"Chronological history of lifecycle transitions (closes and reopens). Present when the conversation has been closed at least once.","items":{"$ref":"#/components/schemas/ConversationStateChangeDTO"}},"allowedCloseReasons":{"type":"array","description":"Close reasons the current user may use to close THIS conversation, given their role in it (participant vs owner). The client should offer exactly these; the backend validates against the same set.","items":{"$ref":"#/components/schemas/ConversationCloseReason"}},"signature":{"$ref":"#/components/schemas/SignatureDTO"},"messages":{"type":"array","description":"Messages in this conversation","items":{"$ref":"#/components/schemas/ConversationMessageDTO"}}}}],"description":"Full conversation: header fields plus list of messages."},"ConversationHeaderDTO":{"type":"object","description":"Conversation header: id, type, name, comment id, updated, dates, owner, closed state, signature, and messages.","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["COMMENT","ENGAGEMENT_STATUS"]},"name":{"type":"string"},"commentId":{"type":"string"},"updated":{"type":"boolean"},"updatedOn":{"type":"string","format":"date-time"},"title":{"type":"string","deprecated":true},"hierarchyName":{"type":"string","deprecated":true},"imagePath":{"type":"string"},"owned":{"type":"boolean"},"closed":{"type":"boolean","description":"Whether the conversation is closed. Posting a message while closed reopens the conversation, so the composer should stay enabled."},"closedOn":{"type":"string","format":"date-time","description":"Date the conversation was closed, when closed is true"},"closeReason":{"$ref":"#/components/schemas/ConversationCloseReason","description":"Reason the conversation was closed, when closed is true. Clients translate the enum to a localized label."},"closeReasonNote":{"type":"string","description":"Free-text note accompanying the close reason, when provided"},"stateHistory":{"type":"array","description":"Chronological history of lifecycle transitions (closes and reopens). Present when the conversation has been closed at least once.","items":{"$ref":"#/components/schemas/ConversationStateChangeDTO"}},"allowedCloseReasons":{"type":"array","description":"Close reasons the current user may use to close THIS conversation, given their role in it (participant vs owner). The client should offer exactly these; the backend validates against the same set.","items":{"$ref":"#/components/schemas/ConversationCloseReason"}},"signature":{"$ref":"#/components/schemas/SignatureDTO"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ConversationMessageDTO"}}}},"ConversationCloseReason":{"type":"string","enum":["RESOLVED","HANDLED","NO_ACTION_NEEDED","DUPLICATE","NOT_INTERESTED","PREFER_NOT_TO_CONTINUE","OTHER"]},"ConversationStateChangeDTO":{"type":"object","description":"A single conversation lifecycle transition (close or reopen): when it happened, the resulting state, who acted, and the close reason/note for close transitions.","properties":{"date":{"type":"string","format":"date-time","description":"When the transition happened"},"state":{"$ref":"#/components/schemas/ConversationState","description":"Resulting state: CLOSED on a close, OPEN on a reopen"},"actor":{"type":"string","description":"Id of the user who performed the transition. Omitted for employee actions on anonymous conversations."},"userType":{"$ref":"#/components/schemas/UserType","description":"Whether the actor acted as an employee or a company user (manager/admin)"},"reason":{"$ref":"#/components/schemas/ConversationCloseReason","description":"Close reason for CLOSED transitions; null for reopens. Clients translate the enum to a localized label."},"note":{"type":"string","description":"Free-text close note, when provided. Omitted for employee actions on anonymous conversations."}}},"ConversationState":{"type":"string","enum":["OPEN","CLOSED"]},"UserType":{"type":"string","description":"Type of user in the system, either an employee or a company user (admin, manager, etc).","enum":["EMPLOYEE","COMPANY_USER"]},"SignatureDTO":{"type":"object","description":"Signature (author) of a comment: id, name, description, and profile image.","properties":{"id":{"type":"string","description":"User ID of the signer"},"name":{"type":"string","description":"Display name of the signer"},"description":{"type":"string","description":"Optional description (e.g. role)"},"profileImagePath":{"type":"string","description":"URL or path to the profile image"}}},"ConversationMessageDTO":{"type":"object","description":"Single message in a conversation: date, text, user type, seen, owned, anonymous, signature.","properties":{"date":{"type":"string","format":"date-time","description":"Message date and time"},"message":{"type":"string","description":"Message text"},"userType":{"$ref":"#/components/schemas/UserType","description":"Type of user who sent the message"},"seen":{"type":"boolean","description":"Whether the message has been seen"},"owned":{"type":"boolean","description":"Whether the message is from the current user"},"signature":{"$ref":"#/components/schemas/SignatureDTO","description":"Signature when not anonymous"},"anonymous":{"type":"boolean"}}}}},"paths":{"/api/v1/company/conversations/{conversationId}":{"put":{"tags":["conversations-resource"],"operationId":"setConversationSeen_1","parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ConversationDTO"}}}}}}}}}
```

## Close a conversation

> Marks the conversation as closed, recording who closed it, when, and why. A closed conversation blocks new messages and is excluded from pending counts and reminders. The reason is required and must be allowed for the caller's role; reason OTHER also requires a note. Idempotent: closing an already-closed conversation has no effect. A manager/admin owner can later reopen it by posting a message with reopen=true, which clears the close reason.

```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":{"ConversationCloseRequestDTO":{"type":"object","description":"Request body to close a conversation: the reason (required) and an optional note (required when reason is OTHER).","properties":{"reason":{"$ref":"#/components/schemas/ConversationCloseReason","description":"Why the conversation is being closed. Must be a reason allowed for an employee."},"note":{"type":"string","description":"Free-text detail. Required when reason is OTHER, otherwise optional."}},"required":["reason"]},"ConversationCloseReason":{"type":"string","enum":["RESOLVED","HANDLED","NO_ACTION_NEEDED","DUPLICATE","NOT_INTERESTED","PREFER_NOT_TO_CONTINUE","OTHER"]},"ConversationDTO":{"allOf":[{"$ref":"#/components/schemas/ConversationHeaderDTO"},{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["COMMENT","ENGAGEMENT_STATUS"]},"name":{"type":"string"},"commentId":{"type":"string"},"updated":{"type":"boolean"},"updatedOn":{"type":"string","format":"date-time"},"title":{"type":"string","deprecated":true},"hierarchyName":{"type":"string","deprecated":true},"imagePath":{"type":"string"},"owned":{"type":"boolean"},"closed":{"type":"boolean","description":"Whether the conversation is closed. Posting a message while closed reopens the conversation, so the composer should stay enabled."},"closedOn":{"type":"string","format":"date-time","description":"Date the conversation was closed, when closed is true"},"closeReason":{"$ref":"#/components/schemas/ConversationCloseReason","description":"Reason the conversation was closed, when closed is true. Clients translate the enum to a localized label."},"closeReasonNote":{"type":"string","description":"Free-text note accompanying the close reason, when provided"},"stateHistory":{"type":"array","description":"Chronological history of lifecycle transitions (closes and reopens). Present when the conversation has been closed at least once.","items":{"$ref":"#/components/schemas/ConversationStateChangeDTO"}},"allowedCloseReasons":{"type":"array","description":"Close reasons the current user may use to close THIS conversation, given their role in it (participant vs owner). The client should offer exactly these; the backend validates against the same set.","items":{"$ref":"#/components/schemas/ConversationCloseReason"}},"signature":{"$ref":"#/components/schemas/SignatureDTO"},"messages":{"type":"array","description":"Messages in this conversation","items":{"$ref":"#/components/schemas/ConversationMessageDTO"}}}}],"description":"Full conversation: header fields plus list of messages."},"ConversationHeaderDTO":{"type":"object","description":"Conversation header: id, type, name, comment id, updated, dates, owner, closed state, signature, and messages.","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["COMMENT","ENGAGEMENT_STATUS"]},"name":{"type":"string"},"commentId":{"type":"string"},"updated":{"type":"boolean"},"updatedOn":{"type":"string","format":"date-time"},"title":{"type":"string","deprecated":true},"hierarchyName":{"type":"string","deprecated":true},"imagePath":{"type":"string"},"owned":{"type":"boolean"},"closed":{"type":"boolean","description":"Whether the conversation is closed. Posting a message while closed reopens the conversation, so the composer should stay enabled."},"closedOn":{"type":"string","format":"date-time","description":"Date the conversation was closed, when closed is true"},"closeReason":{"$ref":"#/components/schemas/ConversationCloseReason","description":"Reason the conversation was closed, when closed is true. Clients translate the enum to a localized label."},"closeReasonNote":{"type":"string","description":"Free-text note accompanying the close reason, when provided"},"stateHistory":{"type":"array","description":"Chronological history of lifecycle transitions (closes and reopens). Present when the conversation has been closed at least once.","items":{"$ref":"#/components/schemas/ConversationStateChangeDTO"}},"allowedCloseReasons":{"type":"array","description":"Close reasons the current user may use to close THIS conversation, given their role in it (participant vs owner). The client should offer exactly these; the backend validates against the same set.","items":{"$ref":"#/components/schemas/ConversationCloseReason"}},"signature":{"$ref":"#/components/schemas/SignatureDTO"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ConversationMessageDTO"}}}},"ConversationStateChangeDTO":{"type":"object","description":"A single conversation lifecycle transition (close or reopen): when it happened, the resulting state, who acted, and the close reason/note for close transitions.","properties":{"date":{"type":"string","format":"date-time","description":"When the transition happened"},"state":{"$ref":"#/components/schemas/ConversationState","description":"Resulting state: CLOSED on a close, OPEN on a reopen"},"actor":{"type":"string","description":"Id of the user who performed the transition. Omitted for employee actions on anonymous conversations."},"userType":{"$ref":"#/components/schemas/UserType","description":"Whether the actor acted as an employee or a company user (manager/admin)"},"reason":{"$ref":"#/components/schemas/ConversationCloseReason","description":"Close reason for CLOSED transitions; null for reopens. Clients translate the enum to a localized label."},"note":{"type":"string","description":"Free-text close note, when provided. Omitted for employee actions on anonymous conversations."}}},"ConversationState":{"type":"string","enum":["OPEN","CLOSED"]},"UserType":{"type":"string","description":"Type of user in the system, either an employee or a company user (admin, manager, etc).","enum":["EMPLOYEE","COMPANY_USER"]},"SignatureDTO":{"type":"object","description":"Signature (author) of a comment: id, name, description, and profile image.","properties":{"id":{"type":"string","description":"User ID of the signer"},"name":{"type":"string","description":"Display name of the signer"},"description":{"type":"string","description":"Optional description (e.g. role)"},"profileImagePath":{"type":"string","description":"URL or path to the profile image"}}},"ConversationMessageDTO":{"type":"object","description":"Single message in a conversation: date, text, user type, seen, owned, anonymous, signature.","properties":{"date":{"type":"string","format":"date-time","description":"Message date and time"},"message":{"type":"string","description":"Message text"},"userType":{"$ref":"#/components/schemas/UserType","description":"Type of user who sent the message"},"seen":{"type":"boolean","description":"Whether the message has been seen"},"owned":{"type":"boolean","description":"Whether the message is from the current user"},"signature":{"$ref":"#/components/schemas/SignatureDTO","description":"Signature when not anonymous"},"anonymous":{"type":"boolean"}}}}},"paths":{"/api/v1/company/conversations/{conversationId}/close":{"put":{"tags":["conversations-resource"],"summary":"Close a conversation","description":"Marks the conversation as closed, recording who closed it, when, and why. A closed conversation blocks new messages and is excluded from pending counts and reminders. The reason is required and must be allowed for the caller's role; reason OTHER also requires a note. Idempotent: closing an already-closed conversation has no effect. A manager/admin owner can later reopen it by posting a message with reopen=true, which clears the close reason.","operationId":"closeConversation_1","parameters":[{"name":"conversationId","in":"path","description":"Id of the conversation to close","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/ConversationCloseRequestDTO"}}},"required":true},"responses":{"200":{"description":"Conversation closed; returns the updated conversation","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ConversationDTO"}}}},"400":{"description":"Reason is missing, or reason is OTHER without a note","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ConversationDTO"}}}},"403":{"description":"The caller does not own the conversation, or the reason is not allowed for the caller's role","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ConversationDTO"}}}}}}}}}
```

## POST /api/v1/company/conversations/starters

> Get's conversation starters for a given context

```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":{"ConversationStartersRequestDTO":{"type":"object","properties":{"personKey":{"type":"string"},"commentId":{"type":"string"},"statusDate":{"type":"string","format":"date"},"originType":{"type":"string","enum":["COMMENT","ENGAGEMENT_STATUS"]}}},"ConversationStarterDTO":{"type":"object","properties":{"starter":{"type":"string"},"reason":{"type":"string"}}}}},"paths":{"/api/v1/company/conversations/starters":{"post":{"tags":["conversations-resource"],"description":"Get's conversation starters for a given context","operationId":"getConversationStarters","parameters":[{"name":"numSuggestions","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":3}}],"requestBody":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/ConversationStartersRequestDTO"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ConversationStarterDTO"}}}}}}}}}}
```

## Post a message to a conversation

> Appends a message to an existing conversation. Posting to a closed conversation is rejected unless reopen=true, in which case the conversation is reopened and the message is posted in the same operation.

```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":{"ConversationMessageDTO":{"type":"object","description":"Single message in a conversation: date, text, user type, seen, owned, anonymous, signature.","properties":{"date":{"type":"string","format":"date-time","description":"Message date and time"},"message":{"type":"string","description":"Message text"},"userType":{"$ref":"#/components/schemas/UserType","description":"Type of user who sent the message"},"seen":{"type":"boolean","description":"Whether the message has been seen"},"owned":{"type":"boolean","description":"Whether the message is from the current user"},"signature":{"$ref":"#/components/schemas/SignatureDTO","description":"Signature when not anonymous"},"anonymous":{"type":"boolean"}}},"UserType":{"type":"string","description":"Type of user in the system, either an employee or a company user (admin, manager, etc).","enum":["EMPLOYEE","COMPANY_USER"]},"SignatureDTO":{"type":"object","description":"Signature (author) of a comment: id, name, description, and profile image.","properties":{"id":{"type":"string","description":"User ID of the signer"},"name":{"type":"string","description":"Display name of the signer"},"description":{"type":"string","description":"Optional description (e.g. role)"},"profileImagePath":{"type":"string","description":"URL or path to the profile image"}}},"ConversationDTO":{"allOf":[{"$ref":"#/components/schemas/ConversationHeaderDTO"},{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["COMMENT","ENGAGEMENT_STATUS"]},"name":{"type":"string"},"commentId":{"type":"string"},"updated":{"type":"boolean"},"updatedOn":{"type":"string","format":"date-time"},"title":{"type":"string","deprecated":true},"hierarchyName":{"type":"string","deprecated":true},"imagePath":{"type":"string"},"owned":{"type":"boolean"},"closed":{"type":"boolean","description":"Whether the conversation is closed. Posting a message while closed reopens the conversation, so the composer should stay enabled."},"closedOn":{"type":"string","format":"date-time","description":"Date the conversation was closed, when closed is true"},"closeReason":{"$ref":"#/components/schemas/ConversationCloseReason","description":"Reason the conversation was closed, when closed is true. Clients translate the enum to a localized label."},"closeReasonNote":{"type":"string","description":"Free-text note accompanying the close reason, when provided"},"stateHistory":{"type":"array","description":"Chronological history of lifecycle transitions (closes and reopens). Present when the conversation has been closed at least once.","items":{"$ref":"#/components/schemas/ConversationStateChangeDTO"}},"allowedCloseReasons":{"type":"array","description":"Close reasons the current user may use to close THIS conversation, given their role in it (participant vs owner). The client should offer exactly these; the backend validates against the same set.","items":{"$ref":"#/components/schemas/ConversationCloseReason"}},"signature":{"$ref":"#/components/schemas/SignatureDTO"},"messages":{"type":"array","description":"Messages in this conversation","items":{"$ref":"#/components/schemas/ConversationMessageDTO"}}}}],"description":"Full conversation: header fields plus list of messages."},"ConversationHeaderDTO":{"type":"object","description":"Conversation header: id, type, name, comment id, updated, dates, owner, closed state, signature, and messages.","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["COMMENT","ENGAGEMENT_STATUS"]},"name":{"type":"string"},"commentId":{"type":"string"},"updated":{"type":"boolean"},"updatedOn":{"type":"string","format":"date-time"},"title":{"type":"string","deprecated":true},"hierarchyName":{"type":"string","deprecated":true},"imagePath":{"type":"string"},"owned":{"type":"boolean"},"closed":{"type":"boolean","description":"Whether the conversation is closed. Posting a message while closed reopens the conversation, so the composer should stay enabled."},"closedOn":{"type":"string","format":"date-time","description":"Date the conversation was closed, when closed is true"},"closeReason":{"$ref":"#/components/schemas/ConversationCloseReason","description":"Reason the conversation was closed, when closed is true. Clients translate the enum to a localized label."},"closeReasonNote":{"type":"string","description":"Free-text note accompanying the close reason, when provided"},"stateHistory":{"type":"array","description":"Chronological history of lifecycle transitions (closes and reopens). Present when the conversation has been closed at least once.","items":{"$ref":"#/components/schemas/ConversationStateChangeDTO"}},"allowedCloseReasons":{"type":"array","description":"Close reasons the current user may use to close THIS conversation, given their role in it (participant vs owner). The client should offer exactly these; the backend validates against the same set.","items":{"$ref":"#/components/schemas/ConversationCloseReason"}},"signature":{"$ref":"#/components/schemas/SignatureDTO"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ConversationMessageDTO"}}}},"ConversationCloseReason":{"type":"string","enum":["RESOLVED","HANDLED","NO_ACTION_NEEDED","DUPLICATE","NOT_INTERESTED","PREFER_NOT_TO_CONTINUE","OTHER"]},"ConversationStateChangeDTO":{"type":"object","description":"A single conversation lifecycle transition (close or reopen): when it happened, the resulting state, who acted, and the close reason/note for close transitions.","properties":{"date":{"type":"string","format":"date-time","description":"When the transition happened"},"state":{"$ref":"#/components/schemas/ConversationState","description":"Resulting state: CLOSED on a close, OPEN on a reopen"},"actor":{"type":"string","description":"Id of the user who performed the transition. Omitted for employee actions on anonymous conversations."},"userType":{"$ref":"#/components/schemas/UserType","description":"Whether the actor acted as an employee or a company user (manager/admin)"},"reason":{"$ref":"#/components/schemas/ConversationCloseReason","description":"Close reason for CLOSED transitions; null for reopens. Clients translate the enum to a localized label."},"note":{"type":"string","description":"Free-text close note, when provided. Omitted for employee actions on anonymous conversations."}}},"ConversationState":{"type":"string","enum":["OPEN","CLOSED"]}}},"paths":{"/api/v1/company/conversations/message/{conversationId}":{"post":{"tags":["conversations-resource"],"summary":"Post a message to a conversation","description":"Appends a message to an existing conversation. Posting to a closed conversation is rejected unless reopen=true, in which case the conversation is reopened and the message is posted in the same operation.","operationId":"postMessage_1","parameters":[{"name":"conversationId","in":"path","description":"Id of the conversation to post to","required":true,"schema":{"type":"string"}},{"name":"reopen","in":"query","description":"When true, reopen the conversation if it is closed before posting. Only a manager/admin owner may reopen.","required":false,"schema":{"type":"boolean","default":false}}],"requestBody":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/ConversationMessageDTO"}}},"required":true},"responses":{"200":{"description":"Message posted; returns the updated conversation","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ConversationDTO"}}}},"412":{"description":"Conversation is closed and reopen was not requested, message is empty, or the conversation is not owned by the caller","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ConversationDTO"}}}}}}}}}
```

## POST /api/v1/company/conversations/init

>

```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":{"ConversationInitRequestDTO":{"type":"object","properties":{"personKey":{"type":"string"},"commentId":{"type":"string"},"originType":{"type":"string","enum":["COMMENT","ENGAGEMENT_STATUS"]},"statusDate":{"type":"string","format":"date-time"},"message":{"type":"string"}}},"ConversationDTO":{"allOf":[{"$ref":"#/components/schemas/ConversationHeaderDTO"},{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["COMMENT","ENGAGEMENT_STATUS"]},"name":{"type":"string"},"commentId":{"type":"string"},"updated":{"type":"boolean"},"updatedOn":{"type":"string","format":"date-time"},"title":{"type":"string","deprecated":true},"hierarchyName":{"type":"string","deprecated":true},"imagePath":{"type":"string"},"owned":{"type":"boolean"},"closed":{"type":"boolean","description":"Whether the conversation is closed. Posting a message while closed reopens the conversation, so the composer should stay enabled."},"closedOn":{"type":"string","format":"date-time","description":"Date the conversation was closed, when closed is true"},"closeReason":{"$ref":"#/components/schemas/ConversationCloseReason","description":"Reason the conversation was closed, when closed is true. Clients translate the enum to a localized label."},"closeReasonNote":{"type":"string","description":"Free-text note accompanying the close reason, when provided"},"stateHistory":{"type":"array","description":"Chronological history of lifecycle transitions (closes and reopens). Present when the conversation has been closed at least once.","items":{"$ref":"#/components/schemas/ConversationStateChangeDTO"}},"allowedCloseReasons":{"type":"array","description":"Close reasons the current user may use to close THIS conversation, given their role in it (participant vs owner). The client should offer exactly these; the backend validates against the same set.","items":{"$ref":"#/components/schemas/ConversationCloseReason"}},"signature":{"$ref":"#/components/schemas/SignatureDTO"},"messages":{"type":"array","description":"Messages in this conversation","items":{"$ref":"#/components/schemas/ConversationMessageDTO"}}}}],"description":"Full conversation: header fields plus list of messages."},"ConversationHeaderDTO":{"type":"object","description":"Conversation header: id, type, name, comment id, updated, dates, owner, closed state, signature, and messages.","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["COMMENT","ENGAGEMENT_STATUS"]},"name":{"type":"string"},"commentId":{"type":"string"},"updated":{"type":"boolean"},"updatedOn":{"type":"string","format":"date-time"},"title":{"type":"string","deprecated":true},"hierarchyName":{"type":"string","deprecated":true},"imagePath":{"type":"string"},"owned":{"type":"boolean"},"closed":{"type":"boolean","description":"Whether the conversation is closed. Posting a message while closed reopens the conversation, so the composer should stay enabled."},"closedOn":{"type":"string","format":"date-time","description":"Date the conversation was closed, when closed is true"},"closeReason":{"$ref":"#/components/schemas/ConversationCloseReason","description":"Reason the conversation was closed, when closed is true. Clients translate the enum to a localized label."},"closeReasonNote":{"type":"string","description":"Free-text note accompanying the close reason, when provided"},"stateHistory":{"type":"array","description":"Chronological history of lifecycle transitions (closes and reopens). Present when the conversation has been closed at least once.","items":{"$ref":"#/components/schemas/ConversationStateChangeDTO"}},"allowedCloseReasons":{"type":"array","description":"Close reasons the current user may use to close THIS conversation, given their role in it (participant vs owner). The client should offer exactly these; the backend validates against the same set.","items":{"$ref":"#/components/schemas/ConversationCloseReason"}},"signature":{"$ref":"#/components/schemas/SignatureDTO"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ConversationMessageDTO"}}}},"ConversationCloseReason":{"type":"string","enum":["RESOLVED","HANDLED","NO_ACTION_NEEDED","DUPLICATE","NOT_INTERESTED","PREFER_NOT_TO_CONTINUE","OTHER"]},"ConversationStateChangeDTO":{"type":"object","description":"A single conversation lifecycle transition (close or reopen): when it happened, the resulting state, who acted, and the close reason/note for close transitions.","properties":{"date":{"type":"string","format":"date-time","description":"When the transition happened"},"state":{"$ref":"#/components/schemas/ConversationState","description":"Resulting state: CLOSED on a close, OPEN on a reopen"},"actor":{"type":"string","description":"Id of the user who performed the transition. Omitted for employee actions on anonymous conversations."},"userType":{"$ref":"#/components/schemas/UserType","description":"Whether the actor acted as an employee or a company user (manager/admin)"},"reason":{"$ref":"#/components/schemas/ConversationCloseReason","description":"Close reason for CLOSED transitions; null for reopens. Clients translate the enum to a localized label."},"note":{"type":"string","description":"Free-text close note, when provided. Omitted for employee actions on anonymous conversations."}}},"ConversationState":{"type":"string","enum":["OPEN","CLOSED"]},"UserType":{"type":"string","description":"Type of user in the system, either an employee or a company user (admin, manager, etc).","enum":["EMPLOYEE","COMPANY_USER"]},"SignatureDTO":{"type":"object","description":"Signature (author) of a comment: id, name, description, and profile image.","properties":{"id":{"type":"string","description":"User ID of the signer"},"name":{"type":"string","description":"Display name of the signer"},"description":{"type":"string","description":"Optional description (e.g. role)"},"profileImagePath":{"type":"string","description":"URL or path to the profile image"}}},"ConversationMessageDTO":{"type":"object","description":"Single message in a conversation: date, text, user type, seen, owned, anonymous, signature.","properties":{"date":{"type":"string","format":"date-time","description":"Message date and time"},"message":{"type":"string","description":"Message text"},"userType":{"$ref":"#/components/schemas/UserType","description":"Type of user who sent the message"},"seen":{"type":"boolean","description":"Whether the message has been seen"},"owned":{"type":"boolean","description":"Whether the message is from the current user"},"signature":{"$ref":"#/components/schemas/SignatureDTO","description":"Signature when not anonymous"},"anonymous":{"type":"boolean"}}},"ErrorMessage":{"type":"object","properties":{"errorCode":{"type":"string"},"errorMessage":{"type":"string"},"customMessage":{"type":"string"}}}}},"paths":{"/api/v1/company/conversations/init":{"post":{"tags":["conversations-resource"],"operationId":"initConversationOverStatus","requestBody":{"content":{"*/*":{"schema":{"$ref":"#/components/schemas/ConversationInitRequestDTO"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ConversationDTO"}}}},"400":{"description":"Bad Request","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}}}}}}
```

## Export conversations to Excel

> Requests an Excel export of the conversations matching the given filters. The report is generated asynchronously and delivered to the requesting user as an emailed download link, so this endpoint returns immediately. The filters accepted here mirror those of the conversation list endpoint, so the export reflects whatever the dashboard is currently filtering. The export never reveals more than the dashboard: anonymous conversations do not expose the participant identity, and message bodies are omitted for conversations the caller cannot view.

```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"]}}},"paths":{"/api/v1/company/conversations/export":{"post":{"tags":["conversations-resource"],"summary":"Export conversations to Excel","description":"Requests an Excel export of the conversations matching the given filters. The report is generated asynchronously and delivered to the requesting user as an emailed download link, so this endpoint returns immediately. The filters accepted here mirror those of the conversation list endpoint, so the export reflects whatever the dashboard is currently filtering. The export never reveals more than the dashboard: anonymous conversations do not expose the participant identity, and message bodies are omitted for conversations the caller cannot view.","operationId":"exportConversations","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":"Export accepted; the download link will be emailed to the caller"},"403":{"description":"The caller does not have a role allowed to export conversations"}}}}}}
```

## GET /api/v1/company/conversations

>

```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"]},"PaginableGenericListResultConversationDTO":{"type":"object","properties":{"from":{"type":"integer","format":"int32"},"to":{"type":"integer","format":"int32"},"total":{"type":"integer","format":"int32"},"noContent":{"type":"boolean"},"results":{"type":"array","items":{"$ref":"#/components/schemas/ConversationDTO"}}}},"ConversationDTO":{"allOf":[{"$ref":"#/components/schemas/ConversationHeaderDTO"},{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["COMMENT","ENGAGEMENT_STATUS"]},"name":{"type":"string"},"commentId":{"type":"string"},"updated":{"type":"boolean"},"updatedOn":{"type":"string","format":"date-time"},"title":{"type":"string","deprecated":true},"hierarchyName":{"type":"string","deprecated":true},"imagePath":{"type":"string"},"owned":{"type":"boolean"},"closed":{"type":"boolean","description":"Whether the conversation is closed. Posting a message while closed reopens the conversation, so the composer should stay enabled."},"closedOn":{"type":"string","format":"date-time","description":"Date the conversation was closed, when closed is true"},"closeReason":{"$ref":"#/components/schemas/ConversationCloseReason","description":"Reason the conversation was closed, when closed is true. Clients translate the enum to a localized label."},"closeReasonNote":{"type":"string","description":"Free-text note accompanying the close reason, when provided"},"stateHistory":{"type":"array","description":"Chronological history of lifecycle transitions (closes and reopens). Present when the conversation has been closed at least once.","items":{"$ref":"#/components/schemas/ConversationStateChangeDTO"}},"allowedCloseReasons":{"type":"array","description":"Close reasons the current user may use to close THIS conversation, given their role in it (participant vs owner). The client should offer exactly these; the backend validates against the same set.","items":{"$ref":"#/components/schemas/ConversationCloseReason"}},"signature":{"$ref":"#/components/schemas/SignatureDTO"},"messages":{"type":"array","description":"Messages in this conversation","items":{"$ref":"#/components/schemas/ConversationMessageDTO"}}}}],"description":"Full conversation: header fields plus list of messages."},"ConversationHeaderDTO":{"type":"object","description":"Conversation header: id, type, name, comment id, updated, dates, owner, closed state, signature, and messages.","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["COMMENT","ENGAGEMENT_STATUS"]},"name":{"type":"string"},"commentId":{"type":"string"},"updated":{"type":"boolean"},"updatedOn":{"type":"string","format":"date-time"},"title":{"type":"string","deprecated":true},"hierarchyName":{"type":"string","deprecated":true},"imagePath":{"type":"string"},"owned":{"type":"boolean"},"closed":{"type":"boolean","description":"Whether the conversation is closed. Posting a message while closed reopens the conversation, so the composer should stay enabled."},"closedOn":{"type":"string","format":"date-time","description":"Date the conversation was closed, when closed is true"},"closeReason":{"$ref":"#/components/schemas/ConversationCloseReason","description":"Reason the conversation was closed, when closed is true. Clients translate the enum to a localized label."},"closeReasonNote":{"type":"string","description":"Free-text note accompanying the close reason, when provided"},"stateHistory":{"type":"array","description":"Chronological history of lifecycle transitions (closes and reopens). Present when the conversation has been closed at least once.","items":{"$ref":"#/components/schemas/ConversationStateChangeDTO"}},"allowedCloseReasons":{"type":"array","description":"Close reasons the current user may use to close THIS conversation, given their role in it (participant vs owner). The client should offer exactly these; the backend validates against the same set.","items":{"$ref":"#/components/schemas/ConversationCloseReason"}},"signature":{"$ref":"#/components/schemas/SignatureDTO"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ConversationMessageDTO"}}}},"ConversationCloseReason":{"type":"string","enum":["RESOLVED","HANDLED","NO_ACTION_NEEDED","DUPLICATE","NOT_INTERESTED","PREFER_NOT_TO_CONTINUE","OTHER"]},"ConversationStateChangeDTO":{"type":"object","description":"A single conversation lifecycle transition (close or reopen): when it happened, the resulting state, who acted, and the close reason/note for close transitions.","properties":{"date":{"type":"string","format":"date-time","description":"When the transition happened"},"state":{"$ref":"#/components/schemas/ConversationState","description":"Resulting state: CLOSED on a close, OPEN on a reopen"},"actor":{"type":"string","description":"Id of the user who performed the transition. Omitted for employee actions on anonymous conversations."},"userType":{"$ref":"#/components/schemas/UserType","description":"Whether the actor acted as an employee or a company user (manager/admin)"},"reason":{"$ref":"#/components/schemas/ConversationCloseReason","description":"Close reason for CLOSED transitions; null for reopens. Clients translate the enum to a localized label."},"note":{"type":"string","description":"Free-text close note, when provided. Omitted for employee actions on anonymous conversations."}}},"SignatureDTO":{"type":"object","description":"Signature (author) of a comment: id, name, description, and profile image.","properties":{"id":{"type":"string","description":"User ID of the signer"},"name":{"type":"string","description":"Display name of the signer"},"description":{"type":"string","description":"Optional description (e.g. role)"},"profileImagePath":{"type":"string","description":"URL or path to the profile image"}}},"ConversationMessageDTO":{"type":"object","description":"Single message in a conversation: date, text, user type, seen, owned, anonymous, signature.","properties":{"date":{"type":"string","format":"date-time","description":"Message date and time"},"message":{"type":"string","description":"Message text"},"userType":{"$ref":"#/components/schemas/UserType","description":"Type of user who sent the message"},"seen":{"type":"boolean","description":"Whether the message has been seen"},"owned":{"type":"boolean","description":"Whether the message is from the current user"},"signature":{"$ref":"#/components/schemas/SignatureDTO","description":"Signature when not anonymous"},"anonymous":{"type":"boolean"}}}}},"paths":{"/api/v1/company/conversations":{"get":{"tags":["conversations-resource"],"operationId":"findConversations","parameters":[{"name":"lastMessageFrom","in":"query","required":false,"schema":{"$ref":"#/components/schemas/UserType"}},{"name":"fromConversation","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":0}},{"name":"toConversation","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":10}},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"sortOrder","in":"query","required":false,"schema":{"type":"string","default":"RECENT","enum":["RECENT","OLDER"]}},{"name":"ownerId","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"uniqueItems":true}},{"name":"personEncryptedId","in":"query","required":false,"schema":{"type":"string"}},{"name":"types","in":"query","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":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PaginableGenericListResultConversationDTO"}}}}}}}}}
```

## GET /api/v1/company/conversations/preview

>

```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":{"PaginableGenericListResultConversationHeaderDTO":{"type":"object","properties":{"from":{"type":"integer","format":"int32"},"to":{"type":"integer","format":"int32"},"total":{"type":"integer","format":"int32"},"noContent":{"type":"boolean"},"results":{"type":"array","items":{"$ref":"#/components/schemas/ConversationHeaderDTO"}}}},"ConversationHeaderDTO":{"type":"object","description":"Conversation header: id, type, name, comment id, updated, dates, owner, closed state, signature, and messages.","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["COMMENT","ENGAGEMENT_STATUS"]},"name":{"type":"string"},"commentId":{"type":"string"},"updated":{"type":"boolean"},"updatedOn":{"type":"string","format":"date-time"},"title":{"type":"string","deprecated":true},"hierarchyName":{"type":"string","deprecated":true},"imagePath":{"type":"string"},"owned":{"type":"boolean"},"closed":{"type":"boolean","description":"Whether the conversation is closed. Posting a message while closed reopens the conversation, so the composer should stay enabled."},"closedOn":{"type":"string","format":"date-time","description":"Date the conversation was closed, when closed is true"},"closeReason":{"$ref":"#/components/schemas/ConversationCloseReason","description":"Reason the conversation was closed, when closed is true. Clients translate the enum to a localized label."},"closeReasonNote":{"type":"string","description":"Free-text note accompanying the close reason, when provided"},"stateHistory":{"type":"array","description":"Chronological history of lifecycle transitions (closes and reopens). Present when the conversation has been closed at least once.","items":{"$ref":"#/components/schemas/ConversationStateChangeDTO"}},"allowedCloseReasons":{"type":"array","description":"Close reasons the current user may use to close THIS conversation, given their role in it (participant vs owner). The client should offer exactly these; the backend validates against the same set.","items":{"$ref":"#/components/schemas/ConversationCloseReason"}},"signature":{"$ref":"#/components/schemas/SignatureDTO"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ConversationMessageDTO"}}}},"ConversationCloseReason":{"type":"string","enum":["RESOLVED","HANDLED","NO_ACTION_NEEDED","DUPLICATE","NOT_INTERESTED","PREFER_NOT_TO_CONTINUE","OTHER"]},"ConversationStateChangeDTO":{"type":"object","description":"A single conversation lifecycle transition (close or reopen): when it happened, the resulting state, who acted, and the close reason/note for close transitions.","properties":{"date":{"type":"string","format":"date-time","description":"When the transition happened"},"state":{"$ref":"#/components/schemas/ConversationState","description":"Resulting state: CLOSED on a close, OPEN on a reopen"},"actor":{"type":"string","description":"Id of the user who performed the transition. Omitted for employee actions on anonymous conversations."},"userType":{"$ref":"#/components/schemas/UserType","description":"Whether the actor acted as an employee or a company user (manager/admin)"},"reason":{"$ref":"#/components/schemas/ConversationCloseReason","description":"Close reason for CLOSED transitions; null for reopens. Clients translate the enum to a localized label."},"note":{"type":"string","description":"Free-text close note, when provided. Omitted for employee actions on anonymous conversations."}}},"ConversationState":{"type":"string","enum":["OPEN","CLOSED"]},"UserType":{"type":"string","description":"Type of user in the system, either an employee or a company user (admin, manager, etc).","enum":["EMPLOYEE","COMPANY_USER"]},"SignatureDTO":{"type":"object","description":"Signature (author) of a comment: id, name, description, and profile image.","properties":{"id":{"type":"string","description":"User ID of the signer"},"name":{"type":"string","description":"Display name of the signer"},"description":{"type":"string","description":"Optional description (e.g. role)"},"profileImagePath":{"type":"string","description":"URL or path to the profile image"}}},"ConversationMessageDTO":{"type":"object","description":"Single message in a conversation: date, text, user type, seen, owned, anonymous, signature.","properties":{"date":{"type":"string","format":"date-time","description":"Message date and time"},"message":{"type":"string","description":"Message text"},"userType":{"$ref":"#/components/schemas/UserType","description":"Type of user who sent the message"},"seen":{"type":"boolean","description":"Whether the message has been seen"},"owned":{"type":"boolean","description":"Whether the message is from the current user"},"signature":{"$ref":"#/components/schemas/SignatureDTO","description":"Signature when not anonymous"},"anonymous":{"type":"boolean"}}}}},"paths":{"/api/v1/company/conversations/preview":{"get":{"tags":["conversations-resource"],"operationId":"findParticipantPreviewConversations","parameters":[{"name":"fromConversation","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":0}},{"name":"toConversation","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":10}},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"sortOrder","in":"query","required":false,"schema":{"type":"string","default":"RECENT","enum":["RECENT","OLDER"]}},{"name":"personEncryptedId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PaginableGenericListResultConversationHeaderDTO"}}}}}}}}}
```

## GET /api/v1/company/conversations/pending

>

```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":{"ConversationPendingDTO":{"type":"object","properties":{"pending":{"type":"integer","format":"int32"}}}}},"paths":{"/api/v1/company/conversations/pending":{"get":{"tags":["conversations-resource"],"operationId":"getPendingConversations","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ConversationPendingDTO"}}}}}}}}}
```
