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

# Conversations

## GET /api/v1/employee/conversations/{employeeId}/{conversationId}

> Get's a conversation

```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":[{"employeeAPISessionId":[]}],"components":{"securitySchemes":{},"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/employee/conversations/{employeeId}/{conversationId}":{"get":{"tags":["Conversations"],"description":"Get's a conversation","operationId":"getConversations","parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationDTO"}}}}}}}}}
```

## PUT /api/v1/employee/conversations/{employeeId}/{conversationId}

> Set's the conversation as seen

```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":[{"employeeAPISessionId":[]}],"components":{"securitySchemes":{},"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/employee/conversations/{employeeId}/{conversationId}":{"put":{"tags":["Conversations"],"description":"Set's the conversation as seen","operationId":"setConversationSeen","parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationDTO"}}}}}}}}}
```

## PUT /api/v1/employee/conversations/{employeeId}/{conversationId}/close

> Closes the conversation with a reason (required; OTHER requires a note). A closed conversation blocks new messages until it is reopened; an employee reopens it simply by posting a new message.

```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":[{"employeeAPISessionId":[]}],"components":{"securitySchemes":{},"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/employee/conversations/{employeeId}/{conversationId}/close":{"put":{"tags":["Conversations"],"description":"Closes the conversation with a reason (required; OTHER requires a note). A closed conversation blocks new messages until it is reopened; an employee reopens it simply by posting a new message.","operationId":"closeConversation","parameters":[{"name":"conversationId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationCloseRequestDTO"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationDTO"}}}}}}}}}
```

## POST /api/v1/employee/conversations/{employeeId}/message/{contextId}

> Posts a message to a conversation. If the conversation is closed, sending a message reopens it: the act of posting is the employee's reopen intent, so no flag is required.

```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":[{"employeeAPISessionId":[]}],"components":{"securitySchemes":{},"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/employee/conversations/{employeeId}/message/{contextId}":{"post":{"tags":["Conversations"],"description":"Posts a message to a conversation. If the conversation is closed, sending a message reopens it: the act of posting is the employee's reopen intent, so no flag is required.","operationId":"postMessage","parameters":[{"name":"contextId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationMessageDTO"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationDTO"}}}}}}}}}
```

## GET /api/v1/employee/conversations/{employeeId}

> Get all the conversations. Optionally filter by lifecycle state with the 'state' query param (OPEN / CLOSED) and by read state with the 'readState' query param (READ / UNREAD); omit either to not filter on that axis (default returns all).

```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":[{"employeeAPISessionId":[]}],"components":{"securitySchemes":{},"schemas":{"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."}}},"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/employee/conversations/{employeeId}":{"get":{"tags":["Conversations"],"description":"Get all the conversations. Optionally filter by lifecycle state with the 'state' query param (OPEN / CLOSED) and by read state with the 'readState' query param (READ / UNREAD); omit either to not filter on that axis (default returns all).","operationId":"getConversation_2","parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":0}},{"name":"to","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":9}},{"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: READ, UNREAD, or omitted for both.","required":false,"schema":{"$ref":"#/components/schemas/ConversationReadState"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginableGenericListResultConversationDTO"}}}}}}}}}
```

## GET /api/v1/employee/conversations/{employeeId}/status

> Get's conversation status for that employee

```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":[{"employeeAPISessionId":[]}],"components":{"securitySchemes":{},"schemas":{"ConversationsStatusDTO":{"type":"object","description":"Conversations status: unread count and total count.","properties":{"unread":{"type":"integer","format":"int32","description":"Number of unread conversations"},"total":{"type":"integer","format":"int32","description":"Total number of conversations"}}}}},"paths":{"/api/v1/employee/conversations/{employeeId}/status":{"get":{"tags":["Conversations"],"description":"Get's conversation status for that employee","operationId":"getConversationsStatus","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationsStatusDTO"}}}}}}}}}
```

## GET /api/v1/employee/conversations/{employeeId}/starters/{contextId}

> 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":[{"employeeAPISessionId":[]}],"components":{"securitySchemes":{},"schemas":{"ConversationStarterSuggestionDTO":{"type":"object","description":"Suggested conversation starter for a context (e.g. a comment): starter text and reason.","properties":{"starter":{"type":"string","description":"Suggested text to start the conversation"},"reason":{"type":"string","description":"Reason or context for suggesting this starter"}}}}},"paths":{"/api/v1/employee/conversations/{employeeId}/starters/{contextId}":{"get":{"tags":["Conversations"],"description":"Get's conversation starters for a given context","operationId":"getConversationStarters_1","parameters":[{"name":"contextId","in":"path","required":true,"schema":{"type":"string"}},{"name":"numSuggestions","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":3}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ConversationStarterSuggestionDTO"}}}}}}}}}}
```

## GET /api/v1/employee/conversations/{employeeId}/pending

> Lists the employee's most recent pending conversations to show on login: open conversations unread by the employee (the company side replied and the employee has not read it yet) whose last activity is older than 3 days. A maximum of 3 is returned, most recent first. Gated by the conversationsOnLoginEnabled feature flag and only available to employees and advisors.

```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":[{"employeeAPISessionId":[]}],"components":{"securitySchemes":{},"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/employee/conversations/{employeeId}/pending":{"get":{"tags":["Conversations"],"description":"Lists the employee's most recent pending conversations to show on login: open conversations unread by the employee (the company side replied and the employee has not read it yet) whose last activity is older than 3 days. A maximum of 3 is returned, most recent first. Gated by the conversationsOnLoginEnabled feature flag and only available to employees and advisors.","operationId":"getOnLoginOpenConversations","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ConversationDTO"}}}}}}}}}}
```
