Hello, I have a question about your product.
", "bodyMarkdown": "Hello, I have a question about your product.", "channel": "desktop", "createdAt": "2025-01-15T10:30:00.000Z", "object": "conversation_part", "partType": "user_msg", "updatedAt": "2025-01-15T10:30:00.000Z", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/user.png" }, "redacted": false, "tagApplications": [ { "appliedAt": "2025-01-15T10:30:00.000Z", "tagId": "67ec1234abcd5678ef901234", "appliedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "removedAt": "2025-01-15T11:00:00.000Z", "removedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "tag": { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } } ] } ], "csatDebug": { "requestId": "csat_req_123", "status": "pending", "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z", "emailDelivery": { "status": "failed", "failedAt": "2025-01-15T10:31:00.000Z", "failureReason": "smtp_bounce", "messageId": "msg_123", "sentAt": "2025-01-15T10:31:00.000Z" }, "lateSubmitWindowEndsAt": "2025-01-16T10:30:00.000Z" }, "csatHistory": [ { "channel": "desktop", "isLatestEffective": true, "lastUpdatedAt": "2025-01-15T10:35:00.000Z", "requestedAt": "2025-01-15T10:30:00.000Z", "requestId": "csat_req_123", "requestSource": "workflow", "status": "pending", "canceledAt": "2025-01-15T10:32:00.000Z", "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z", "emailDelivery": { "status": "failed", "failedAt": "2025-01-15T10:31:00.000Z", "failureReason": "smtp_bounce", "messageId": "msg_123", "sentAt": "2025-01-15T10:31:00.000Z" }, "expiredAt": "2025-01-16T10:30:00.000Z", "lateSubmitWindowEndsAt": "2025-01-16T10:30:00.000Z", "ratedAgent": { "type": "teammate", "id": "507f1f77bcf86cd799439011" }, "ratedAt": "2025-01-15T10:35:00.000Z", "remark": "Thanks for the quick help.", "score": 4, "workflow": { "workflowActionId": "action_123", "workflowId": "507f1f77bcf86cd799439011", "workflowRunId": "run_123", "workflowStepId": "step_123" } } ], "csatSummary": { "lastUpdatedAt": "2025-01-15T10:35:00.000Z", "status": "pending", "canceledAt": "2025-01-15T10:35:00.000Z", "channel": "desktop", "expiredAt": "2025-01-15T10:35:00.000Z", "ratedAgent": { "type": "teammate", "id": "507f1f77bcf86cd799439011" }, "ratedAt": "2025-01-15T10:35:00.000Z", "remark": "Very helpful support.", "requestedAt": "2025-01-15T10:30:00.000Z", "requestId": "csat_req_123", "requestSource": "workflow", "score": 5, "workflow": { "workflowActionId": "action_123", "workflowId": "507f1f77bcf86cd799439011", "workflowRunId": "run_123", "workflowStepId": "step_123" } }, "disableCustomerReply": false, "readReceipts": [ { "id": "507f1f77bcf86cd799439011", "lastReadPartId": "8", "userType": "admin" } ], "source": { "bodyHtml": "Hi, I have a question about your enterprise plan...
", "bodyMarkdown": "Hi, I have a question about your enterprise plan...", "channel": "desktop", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer" }, "deliveredAs": "customer_initiated", "subject": "Question about pricing", "url": "https://example.com/pricing" }, "title": "Question about pricing" } ], "nextCursor": "eyJpZCI6IjEyMzQ1In0=", "object": "list" } ``` ## Create a conversation **post** `/v2/conversations` Creates a new conversation. Supports both contact-initiated (customer/lead) and admin-initiated (outreach) conversations. ## Contact-Initiated Conversation For conversations started by a customer or lead: | Field | Type | Required | Description | | -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `from.type` | string | Yes | Must be "contact" | | `from.id` | string | Yes | The Featurebase contact ID (24-character ObjectId) | | `bodyMarkdown` | string | Yes | The initial message content in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored. | | `channel` | string | No | The channel: "desktop" (default) or "email" | | `createdAt` | string | No | ISO timestamp for migrations | ### Example Contact-Initiated Request ```json { "from": { "type": "contact", "id": "676f0f6765bdaa7d7d760f88" }, "bodyMarkdown": "Hello, I have a question about your product.", "channel": "desktop" } ``` ## Admin-Initiated Outreach For outreach conversations started by an admin: | Field | Type | Required | Description | | ---------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `from.type` | string | Yes | Must be "admin" | | `from.id` | string | Yes | The Featurebase admin ID (24-character ObjectId) | | `bodyMarkdown` | string | Yes | The initial message content in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored. | | `channel` | string | No | The channel: "desktop" (default) or "email" | | `recipients` | object | Yes | Recipients for the outreach | | `recipients.to` | object | Yes | Primary recipients | | `recipients.to.emails` | string[] | No* | Email addresses | | `recipients.to.ids` | string[] | No* | Featurebase contact IDs | | `recipients.cc` | object | No | CC recipients (same structure as "to") | | `recipients.bcc` | object | No | BCC recipients (same structure as "to") | | `subject` | string | No** | Email subject line | | `createdAt` | string | No | ISO timestamp for migrations | \*At least one email or ID is required in `recipients.to` \**Required when channel is "email" ### Example Admin Outreach (In-App) ```json { "from": { "type": "admin", "id": "507f1f77bcf86cd799439011" }, "bodyMarkdown": "Hi! Just following up on your inquiry.", "channel": "desktop", "recipients": { "to": { "ids": ["676f0f6765bdaa7d7d760f88"] } } } ``` ### Example Admin Outreach (Email) ```json { "from": { "type": "admin", "id": "507f1f77bcf86cd799439011" }, "bodyMarkdown": "Hi! Just following up on your inquiry.", "channel": "email", "subject": "Following up on your inquiry", "recipients": { "to": { "emails": ["john@example.com"] }, "cc": { "emails": ["manager@example.com"] } } } ``` ### Response Returns the created conversation object with a **201 Created** status. ### Example Response ```json { "object": "conversation", "id": "12345", "state": "open", "priority": false, "adminAssigneeId": null, "participants": [ { "type": "customer", "id": "676f0f6765bdaa7d7d760f88" } ], "source": { "channel": "desktop", "deliveredAs": "customer_initiated", "bodyHtml": "Hello, I have a question about your product.
", "bodyMarkdown": "Hello, I have a question about your product.", "author": { "type": "customer", "id": "676f0f6765bdaa7d7d760f88" } }, "createdAt": "2025-01-15T10:30:00.000Z", "updatedAt": "2025-01-15T10:30:00.000Z" } ``` ### Version Availability This endpoint is only available in API version 2026-01-01.nova and newer. ### Header Parameters - `"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"` - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Body Parameters - `bodyMarkdown: string` The content of the initial message in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored. - `from: object { id, type } or object { id, type }` The author initiating the conversation. Use type "contact" for customer/lead or "admin" for outreach. - `Contact object { id, type }` Conversation initiated by a contact - `id: string` The Featurebase contact ID - `type: "contact"` The type of author. Use "contact" for customer/lead initiated conversations. - `"contact"` - `Admin object { id, type }` Conversation initiated by an admin (outreach) - `id: string` The Featurebase admin ID - `type: "admin"` The type of author. Use "admin" for admin initiated outreach conversations. - `"admin"` - `channel: optional "desktop" or "email"` The channel for the conversation. Defaults to "desktop" (SDK/widget). - `"desktop"` - `"email"` - `createdAt: optional string` The time the conversation was created as an ISO timestamp. If not provided, the current time will be used. This field is recommended for migrating past conversations from another source. - `recipients: optional object { to, bcc, cc }` Recipients for admin-initiated outreach. Required when from.type is "admin". Specify at least one recipient in the "to" field. - `to: EmailRecipients` Primary recipients (To field) - `emails: optional array of string` Array of email addresses - `ids: optional array of string` Array of Featurebase contact IDs - `bcc: optional EmailRecipients` Primary recipients (To field) - `cc: optional EmailRecipients` Primary recipients (To field) - `subject: optional string` Subject line for the email. Required when channel is "email" and from.type is "admin". ### Returns - `Conversation object { id, adminAssigneeId, botConversationStateLastUpdatedAt, 26 more }` - `id: string` Unique conversation identifier - `adminAssigneeId: string` ID of the assigned admin - `botConversationStateLastUpdatedAt: string` ISO timestamp when bot state last changed - `brandId: string` ID of the brand associated with this conversation - `createdAt: string` ISO timestamp when conversation was created - `hasAdminOverriddenLanguage: boolean` Whether an admin has manually overridden the language for this conversation. When true, automatic language detection is disabled. - `isBlocked: boolean` Whether the user is blocked - `lastActivityAt: string` ISO timestamp of last activity - `object: "conversation"` Object type identifier - `"conversation"` - `participants: array of ConversationParticipant` Participants in this conversation - `id: string` Participant ID - `type: "customer" or "lead" or "admin" or 3 more` Type of participant - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `priority: boolean` Whether this conversation is marked as priority - `prioritySetAt: string` ISO timestamp when priority was set - `snoozedUntil: string` ISO timestamp until which conversation is snoozed - `state: "open" or "closed" or "snoozed"` Current state of the conversation - `"open"` - `"closed"` - `"snoozed"` - `tags: array of ConversationTag` Current tags applied anywhere in this conversation - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `teamAssigneeId: string` ID of the assigned team - `updatedAt: string` ISO timestamp when conversation was last updated - `userPreferredLanguage: string` User's preferred language - `waitingSince: string` ISO timestamp when conversation started waiting - `awaitingCustomerReply: optional boolean` Whether we are awaiting a customer reply - `botConversationState: optional "active" or "handed_off_to_human" or "resolved"` State of AI agent handling for this conversation - `"active"` - `"handed_off_to_human"` - `"resolved"` - `conversationParts: optional array of ConversationPart` Array of conversation parts (messages). Only included when fetching a single conversation by ID. - `UserMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Message from a customer or lead - `id: string` Unique part identifier - `bodyHtml: string` Message body content as HTML with signed image URLs - `bodyMarkdown: string` Message body content as markdown - `channel: "unknown" or "desktop" or "android" or 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "user_msg"` User message type - `"user_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `id: string` Author ID - `type: "customer" or "lead" or "admin" or 3 more` Type of author - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `email: optional string` Author email address - `name: optional string` Author display name - `profilePicture: optional string` Author profile picture URL - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `type: "admin" or "customer" or "lead" or 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id: optional string` Actor identifier when available - `name: optional string` Actor display name when available - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `AdminMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Message from an admin or support agent - `id: string` Unique part identifier - `bodyHtml: string` Message body content as HTML with signed image URLs - `bodyMarkdown: string` Message body content as markdown - `channel: "unknown" or "desktop" or "android" or 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_msg"` Admin message type - `"admin_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AdminNote object { id, bodyHtml, bodyMarkdown, 7 more }` Internal note visible only to admins - `id: string` Unique part identifier - `bodyHtml: string` Note body content as HTML with signed image URLs - `bodyMarkdown: string` Note body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_note"` Admin internal note type - `"admin_note"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `EmailMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Message sent via email - `id: string` Unique part identifier - `bodyHtml: string` Email body content as HTML with signed image URLs - `bodyMarkdown: string` Email body content as markdown - `channel: "email"` Email channel - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "email_msg"` Email message type - `"email_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `BotMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Automated message from AI or bot - `id: string` Unique part identifier - `bodyHtml: string` Bot message body content as HTML with signed image URLs - `bodyMarkdown: string` Bot message body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "bot_msg"` Bot message type - `"bot_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `channel: optional "unknown" or "desktop" or "android" or 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyOpts object { id, createdAt, object, 6 more }` Presents options for user to choose from - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_opts"` Quick reply options type - `"quick_reply_opts"` - `replyOptions: array of object { id, text }` Available reply options - `id: string` Option ID - `text: string` Option text - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyResp object { id, bodyHtml, bodyMarkdown, 8 more }` User's selection from quick reply options - `id: string` Unique part identifier - `bodyHtml: string` The selected option text as HTML - `bodyMarkdown: string` The selected option text as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_resp"` Quick reply response type - `"quick_reply_resp"` - `selectedOptionId: string` ID of the selected option - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `RatingRequested object { id, createdAt, csat, 3 more }` Represents a persisted CSAT request in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: object { channel, requestedAt, requestId, 7 more }` Canonical CSAT request payload for this thread event - `channel: "desktop" or "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" or "rated" or "canceled" or "expired"` Status of the CSAT request represented by this part - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt: optional string` ISO timestamp after which changing the rating is no longer allowed - `expiredAt: optional string` ISO timestamp when the request expired, when applicable - `lateSubmitWindowEndsAt: optional string` ISO timestamp after which late submission is no longer allowed - `ratedAgent: optional CsatRatedAgent` - `type: "teammate" or "fibi" or "chatbot"` Type of agent the CSAT request is attributed to - `"teammate"` - `"fibi"` - `"chatbot"` - `id: optional string` Identifier of the rated agent when applicable - `workflow: optional CsatWorkflowLink` - `workflowActionId: optional string` Workflow action ID associated with the CSAT request - `workflowId: optional string` Workflow ID associated with the CSAT request - `workflowRunId: optional string` Workflow run ID associated with the CSAT request - `workflowStepId: optional string` Workflow step ID associated with the CSAT request - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_requested"` CSAT rating requested part type - `"rating_requested"` - `updatedAt: string` ISO timestamp when the part was last updated - `RatingSubmitted object { id, createdAt, csat, 3 more }` Represents a persisted CSAT submission in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: object { channel, ratedAt, requestId, 7 more }` Canonical CSAT submission payload for this thread event - `channel: "desktop" or "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `ratedAt: string` ISO timestamp when the customer submitted the rating - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `score: number` CSAT score from 1 to 5 - `status: "rated"` Submitted ratings are always in the rated state - `"rated"` - `ratedAgent: optional CsatRatedAgent` - `remark: optional string` Optional remark left with the rating - `requestedAt: optional string` ISO timestamp when the request was created - `workflow: optional CsatWorkflowLink` - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_submitted"` CSAT rating submitted part type - `"rating_submitted"` - `updatedAt: string` ISO timestamp when the part was last updated - `AttrPrompt object { id, createdAt, form, 6 more }` Requests information from user via form - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `form: object { id, attributes }` Form configuration - `id: string` Form ID - `attributes: array of object { identifier, name, type }` Form fields - `identifier: string` Field identifier - `name: string` Field display name - `type: string` Field type - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_prompt"` Attribute collection prompt type - `"attr_prompt"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AttrComplete object { id, createdAt, object, 2 more }` Indicates form was completed - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_complete"` Attribute collection complete type - `"attr_complete"` - `updatedAt: string` ISO timestamp when the part was last updated - `Assign object { id, createdAt, object, 5 more }` Conversation assigned to admin or team - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "assign"` Assignment type - `"assign"` - `updatedAt: string` ISO timestamp when the part was last updated - `adminAssigneeId: optional string` ID of the admin assigned to the conversation - `adminAssignerId: optional string` ID of the admin who made the assignment - `teamAssigneeId: optional string` ID of the team assigned to the conversation - `Status object { id, createdAt, object, 4 more }` Conversation state changed (open/closed/snoozed) - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "status"` Status change type - `"status"` - `status: "open" or "closed" or "snoozed"` New conversation status - `"open"` - `"closed"` - `"snoozed"` - `updatedAt: string` ISO timestamp when the part was last updated - `snoozedUntil: optional string` ISO timestamp until conversation is snoozed (if snoozed) - `Tags object { id, action, createdAt, 8 more }` A tag was added to or removed from a specific reply - `id: string` Unique part identifier - `action: "added" or "removed"` Whether the tag was added or removed - `"added"` - `"removed"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `occurredAt: string` ISO timestamp when the tag mutation occurred - `partType: "tags"` Tag update type - `"tags"` - `tagId: string` Identifier of the affected tag - `updatedAt: string` ISO timestamp when the part was last updated - `actor: optional ConversationTagMutationActor` Actor that applied the tag - `tagName: optional string` Tag name at the time of the event or the best available current display name - `targetPartId: optional string` Conversation part that the tag mutation targeted - `WorkflowWait object { id, createdAt, object, 3 more }` Represents a workflow wait start, finish, or interruption in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "workflow_wait"` Workflow wait event part type - `"workflow_wait"` - `updatedAt: string` ISO timestamp when the part was last updated - `workflowWait: object { eventType, occurredAt, interruptedByUserType, 3 more }` Workflow wait event payload for this thread event - `eventType: "started" or "finished" or "interrupted"` Lifecycle stage of the workflow wait event - `"started"` - `"finished"` - `"interrupted"` - `occurredAt: string` ISO timestamp when the wait event occurred - `interruptedByUserType: optional "admin" or "customer" or "lead"` User type that interrupted the wait when applicable - `"admin"` - `"customer"` - `"lead"` - `waitLabel: optional string` Human-readable wait duration or preset label - `workflowId: optional string` Workflow ID associated with the wait event - `workflowName: optional string` Workflow display name at the time of the wait event - `Priority object { id, createdAt, isPriority, 3 more }` Conversation priority was updated - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `isPriority: boolean` Whether the conversation is now marked as priority - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "priority"` Priority change type - `"priority"` - `updatedAt: string` ISO timestamp when the part was last updated - `PartAdd object { id, createdAt, object, 3 more }` New participant joined the conversation - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `participant: object { id, type }` The added participant - `id: string` Participant ID - `type: "customer" or "lead" or "admin"` Participant type - `"customer"` - `"lead"` - `"admin"` - `partType: "part_add"` Participant added type - `"part_add"` - `updatedAt: string` ISO timestamp when the part was last updated - `csatDebug: optional object { requestId, status, changeLockWindowEndsAt, 2 more }` Minimal CSAT diagnostics for the current effective request. - `requestId: string` Canonical CSAT request ID used for the latest debug snapshot - `status: "pending" or "rated" or "canceled" or "expired"` Lifecycle status of the request represented in the debug snapshot - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt: optional string` ISO timestamp when rating edits stop being accepted - `emailDelivery: optional CsatEmailDelivery` - `status: "pending" or "sent" or "failed"` Email delivery status for the CSAT request when applicable - `"pending"` - `"sent"` - `"failed"` - `failedAt: optional string` ISO timestamp when the CSAT email failed - `failureReason: optional string` Operational failure reason for the CSAT email delivery - `messageId: optional string` Email message ID associated with delivery - `sentAt: optional string` ISO timestamp when the CSAT email was sent - `lateSubmitWindowEndsAt: optional string` ISO timestamp when first-time submissions stop being accepted - `csatHistory: optional array of object { channel, isLatestEffective, lastUpdatedAt, 14 more }` Historical CSAT requests for this conversation, ordered newest first. - `channel: "desktop" or "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `isLatestEffective: boolean` Whether this row represents the currently effective CSAT request for the conversation - `lastUpdatedAt: string` ISO timestamp when the request last changed - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" or "rated" or "canceled" or "expired"` Lifecycle status for this historical CSAT request - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt: optional string` ISO timestamp when the request was canceled - `changeLockWindowEndsAt: optional string` ISO timestamp when edits to an existing rating stop being accepted - `emailDelivery: optional CsatEmailDelivery` - `expiredAt: optional string` ISO timestamp when the request expired - `lateSubmitWindowEndsAt: optional string` ISO timestamp when first-time submissions stop being accepted - `ratedAgent: optional CsatRatedAgent` - `ratedAt: optional string` ISO timestamp when the request was rated - `remark: optional string` Submitted remark when present - `score: optional number` Submitted score when this request was rated - `workflow: optional CsatWorkflowLink` - `csatSummary: optional object { lastUpdatedAt, status, canceledAt, 10 more }` Derived CSAT summary for this conversation when a rating request or rating exists. - `lastUpdatedAt: string` ISO timestamp when the summary last changed - `status: "pending" or "rated" or "canceled" or "expired"` Current summary status for CSAT on this conversation - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt: optional string` ISO timestamp when the request was canceled - `channel: optional "desktop" or "email"` Channel used for the latest CSAT request when known - `"desktop"` - `"email"` - `expiredAt: optional string` ISO timestamp when the request expired - `ratedAgent: optional CsatRatedAgent` - `ratedAt: optional string` ISO timestamp when the customer submitted a rating - `remark: optional string` Optional remark left with the rating - `requestedAt: optional string` ISO timestamp when the latest CSAT request was created - `requestId: optional string` Canonical CSAT request ID - `requestSource: optional "workflow"` Source of the latest CSAT request when known - `"workflow"` - `score: optional number` CSAT score from 1 to 5 when rated - `workflow: optional CsatWorkflowLink` - `disableCustomerReply: optional boolean` Whether customer replies are disabled - `readReceipts: optional array of object { id, lastReadPartId, userType }` Read receipts indicating how far each participant has read in the conversation. Each receipt maps a user to their last-read conversation part. The tracked position reflects the system read state and may reference parts the user cannot directly view (e.g., a contact's read position may point to an internal admin note). Use these receipts to render read indicators and typing awareness, not to infer content access. - `id: string` The internal ID of the user - `lastReadPartId: string` The ID of the last conversation part this user has read. Note: This reflects the system-tracked read position and may reference a part the user cannot directly access (e.g., internal notes for contacts). The read state is advanced to the latest part in the conversation regardless of part visibility. - `userType: "admin" or "customer" or "lead"` Type of user who has read the conversation - `"admin"` - `"customer"` - `"lead"` - `source: optional object { bodyHtml, bodyMarkdown, channel, 4 more }` - `bodyHtml: string` Body of the initial message as HTML with signed image URLs - `bodyMarkdown: string` Body of the initial message as markdown - `channel: "unknown" or "desktop" or "android" or 2 more` Channel through which the conversation was initiated - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `author: optional ConversationParticipant` - `id: string` Participant ID - `type: "customer" or "lead" or "admin" or 3 more` Type of participant - `deliveredAs: optional "customer_initiated" or "admin_initiated"` How the conversation was initiated - `"customer_initiated"` - `"admin_initiated"` - `subject: optional string` Subject line for email conversations - `url: optional string` URL where the conversation was initiated - `title: optional string` Conversation title ### Example ```http curl https://do.featurebase.app/v2/conversations \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $FEATUREBASE_API_KEY" \ -d '{ "bodyMarkdown": "Hello, I have a question about your product.\\n\\n", "from": { "id": "676f0f6765bdaa7d7d760f88", "type": "contact" }, "channel": "desktop", "createdAt": "2025-01-15T10:30:00.000Z", "subject": "Following up on your inquiry" }' ``` #### Response ```json { "id": "12345", "adminAssigneeId": "507f1f77bcf86cd799439011", "botConversationStateLastUpdatedAt": "2025-01-15T10:30:00.000Z", "brandId": "507f1f77bcf86cd799439011", "createdAt": "2025-01-15T10:30:00.000Z", "hasAdminOverriddenLanguage": false, "isBlocked": false, "lastActivityAt": "2025-01-15T12:30:00.000Z", "object": "conversation", "participants": [ { "id": "676f0f6765bdaa7d7d760f88", "type": "customer" } ], "priority": false, "prioritySetAt": "2025-01-15T10:30:00.000Z", "snoozedUntil": "2025-01-16T09:00:00.000Z", "state": "open", "tags": [ { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } ], "teamAssigneeId": "507f1f77bcf86cd799439012", "updatedAt": "2025-01-15T12:30:00.000Z", "userPreferredLanguage": "en", "waitingSince": "2025-01-15T10:30:00.000Z", "awaitingCustomerReply": true, "botConversationState": "active", "conversationParts": [ { "id": "1", "bodyHtml": "Hello, I have a question about your product.
", "bodyMarkdown": "Hello, I have a question about your product.", "channel": "desktop", "createdAt": "2025-01-15T10:30:00.000Z", "object": "conversation_part", "partType": "user_msg", "updatedAt": "2025-01-15T10:30:00.000Z", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/user.png" }, "redacted": false, "tagApplications": [ { "appliedAt": "2025-01-15T10:30:00.000Z", "tagId": "67ec1234abcd5678ef901234", "appliedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "removedAt": "2025-01-15T11:00:00.000Z", "removedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "tag": { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } } ] } ], "csatDebug": { "requestId": "csat_req_123", "status": "pending", "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z", "emailDelivery": { "status": "failed", "failedAt": "2025-01-15T10:31:00.000Z", "failureReason": "smtp_bounce", "messageId": "msg_123", "sentAt": "2025-01-15T10:31:00.000Z" }, "lateSubmitWindowEndsAt": "2025-01-16T10:30:00.000Z" }, "csatHistory": [ { "channel": "desktop", "isLatestEffective": true, "lastUpdatedAt": "2025-01-15T10:35:00.000Z", "requestedAt": "2025-01-15T10:30:00.000Z", "requestId": "csat_req_123", "requestSource": "workflow", "status": "pending", "canceledAt": "2025-01-15T10:32:00.000Z", "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z", "emailDelivery": { "status": "failed", "failedAt": "2025-01-15T10:31:00.000Z", "failureReason": "smtp_bounce", "messageId": "msg_123", "sentAt": "2025-01-15T10:31:00.000Z" }, "expiredAt": "2025-01-16T10:30:00.000Z", "lateSubmitWindowEndsAt": "2025-01-16T10:30:00.000Z", "ratedAgent": { "type": "teammate", "id": "507f1f77bcf86cd799439011" }, "ratedAt": "2025-01-15T10:35:00.000Z", "remark": "Thanks for the quick help.", "score": 4, "workflow": { "workflowActionId": "action_123", "workflowId": "507f1f77bcf86cd799439011", "workflowRunId": "run_123", "workflowStepId": "step_123" } } ], "csatSummary": { "lastUpdatedAt": "2025-01-15T10:35:00.000Z", "status": "pending", "canceledAt": "2025-01-15T10:35:00.000Z", "channel": "desktop", "expiredAt": "2025-01-15T10:35:00.000Z", "ratedAgent": { "type": "teammate", "id": "507f1f77bcf86cd799439011" }, "ratedAt": "2025-01-15T10:35:00.000Z", "remark": "Very helpful support.", "requestedAt": "2025-01-15T10:30:00.000Z", "requestId": "csat_req_123", "requestSource": "workflow", "score": 5, "workflow": { "workflowActionId": "action_123", "workflowId": "507f1f77bcf86cd799439011", "workflowRunId": "run_123", "workflowStepId": "step_123" } }, "disableCustomerReply": false, "readReceipts": [ { "id": "507f1f77bcf86cd799439011", "lastReadPartId": "8", "userType": "admin" } ], "source": { "bodyHtml": "Hi, I have a question about your enterprise plan...
", "bodyMarkdown": "Hi, I have a question about your enterprise plan...", "channel": "desktop", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer" }, "deliveredAs": "customer_initiated", "subject": "Question about pricing", "url": "https://example.com/pricing" }, "title": "Question about pricing" } ``` ## Get conversation by ID **get** `/v2/conversations/{id}` Retrieves a single conversation by its ID, including conversation parts (messages). ### Path Parameters - `id` - The conversation ID (short ID) ### Hard Limit of 500 Parts The maximum number of conversation parts that can be returned via the API is **500**. If a conversation has more than 500 parts, only the **500 most recent** conversation parts will be returned. ### Response Format Returns a single conversation object with: - `object` - Always "conversation" - `id` - Unique conversation identifier (short ID) - `title` - Conversation title - `state` - Current state ("open", "closed", or "snoozed") - `priority` - Whether the conversation is marked as priority - `adminAssigneeId` - ID of assigned admin (if any) - `teamAssigneeId` - ID of assigned team (if any) - `participants` - Array of participants - `source` - Information about the first message - `conversationParts` - Array of conversation parts (messages, max 500) - `createdAt` - Creation timestamp - `updatedAt` - Last update timestamp ### Conversation Parts Each conversation part includes: - `object` - Always "conversation_part" - `id` - Unique part identifier - `partType` - Type of part (e.g., "user_msg", "admin_msg", "bot_msg") - `body` - Message body (HTML content) - `author` - Author information with name, email, and profile picture - `channel` - Channel through which the message was sent - `createdAt` - Creation timestamp - `updatedAt` - Last update timestamp ### Example ```json { "object": "conversation", "id": "12345", "title": "Question about pricing", "state": "open", "priority": false, "adminAssigneeId": "507f1f77bcf86cd799439011", "participants": [ { "type": "customer", "id": "676f0f6765bdaa7d7d760f88" } ], "conversationParts": [ { "object": "conversation_part", "id": "1", "partType": "user_msg", "bodyHtml": "Hello, I have a question about your pricing plans.
", "bodyMarkdown": "Hello, I have a question about your pricing plans.", "author": { "type": "customer", "id": "676f0f6765bdaa7d7d760f88", "name": "John Doe", "email": "john@example.com" }, "channel": "desktop", "createdAt": "2025-01-15T10:30:00.000Z", "updatedAt": "2025-01-15T10:30:00.000Z" }, { "object": "conversation_part", "id": "2", "partType": "admin_msg", "bodyHtml": "Hi John! I'd be happy to help you with pricing information.
", "bodyMarkdown": "Hi John! I'd be happy to help you with pricing information.", "author": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "Support Agent" }, "channel": "desktop", "createdAt": "2025-01-15T10:35:00.000Z", "updatedAt": "2025-01-15T10:35:00.000Z" } ], "createdAt": "2025-01-15T10:30:00.000Z", "updatedAt": "2025-01-15T10:35:00.000Z" } ``` ### Version Availability This endpoint is only available in API version 2026-01-01.nova and newer. ### Path Parameters - `id: string` Conversation ID (short ID) ### Header Parameters - `"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"` - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `Conversation object { id, adminAssigneeId, botConversationStateLastUpdatedAt, 26 more }` - `id: string` Unique conversation identifier - `adminAssigneeId: string` ID of the assigned admin - `botConversationStateLastUpdatedAt: string` ISO timestamp when bot state last changed - `brandId: string` ID of the brand associated with this conversation - `createdAt: string` ISO timestamp when conversation was created - `hasAdminOverriddenLanguage: boolean` Whether an admin has manually overridden the language for this conversation. When true, automatic language detection is disabled. - `isBlocked: boolean` Whether the user is blocked - `lastActivityAt: string` ISO timestamp of last activity - `object: "conversation"` Object type identifier - `"conversation"` - `participants: array of ConversationParticipant` Participants in this conversation - `id: string` Participant ID - `type: "customer" or "lead" or "admin" or 3 more` Type of participant - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `priority: boolean` Whether this conversation is marked as priority - `prioritySetAt: string` ISO timestamp when priority was set - `snoozedUntil: string` ISO timestamp until which conversation is snoozed - `state: "open" or "closed" or "snoozed"` Current state of the conversation - `"open"` - `"closed"` - `"snoozed"` - `tags: array of ConversationTag` Current tags applied anywhere in this conversation - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `teamAssigneeId: string` ID of the assigned team - `updatedAt: string` ISO timestamp when conversation was last updated - `userPreferredLanguage: string` User's preferred language - `waitingSince: string` ISO timestamp when conversation started waiting - `awaitingCustomerReply: optional boolean` Whether we are awaiting a customer reply - `botConversationState: optional "active" or "handed_off_to_human" or "resolved"` State of AI agent handling for this conversation - `"active"` - `"handed_off_to_human"` - `"resolved"` - `conversationParts: optional array of ConversationPart` Array of conversation parts (messages). Only included when fetching a single conversation by ID. - `UserMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Message from a customer or lead - `id: string` Unique part identifier - `bodyHtml: string` Message body content as HTML with signed image URLs - `bodyMarkdown: string` Message body content as markdown - `channel: "unknown" or "desktop" or "android" or 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "user_msg"` User message type - `"user_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `id: string` Author ID - `type: "customer" or "lead" or "admin" or 3 more` Type of author - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `email: optional string` Author email address - `name: optional string` Author display name - `profilePicture: optional string` Author profile picture URL - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `type: "admin" or "customer" or "lead" or 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id: optional string` Actor identifier when available - `name: optional string` Actor display name when available - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `AdminMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Message from an admin or support agent - `id: string` Unique part identifier - `bodyHtml: string` Message body content as HTML with signed image URLs - `bodyMarkdown: string` Message body content as markdown - `channel: "unknown" or "desktop" or "android" or 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_msg"` Admin message type - `"admin_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AdminNote object { id, bodyHtml, bodyMarkdown, 7 more }` Internal note visible only to admins - `id: string` Unique part identifier - `bodyHtml: string` Note body content as HTML with signed image URLs - `bodyMarkdown: string` Note body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_note"` Admin internal note type - `"admin_note"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `EmailMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Message sent via email - `id: string` Unique part identifier - `bodyHtml: string` Email body content as HTML with signed image URLs - `bodyMarkdown: string` Email body content as markdown - `channel: "email"` Email channel - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "email_msg"` Email message type - `"email_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `BotMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Automated message from AI or bot - `id: string` Unique part identifier - `bodyHtml: string` Bot message body content as HTML with signed image URLs - `bodyMarkdown: string` Bot message body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "bot_msg"` Bot message type - `"bot_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `channel: optional "unknown" or "desktop" or "android" or 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyOpts object { id, createdAt, object, 6 more }` Presents options for user to choose from - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_opts"` Quick reply options type - `"quick_reply_opts"` - `replyOptions: array of object { id, text }` Available reply options - `id: string` Option ID - `text: string` Option text - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyResp object { id, bodyHtml, bodyMarkdown, 8 more }` User's selection from quick reply options - `id: string` Unique part identifier - `bodyHtml: string` The selected option text as HTML - `bodyMarkdown: string` The selected option text as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_resp"` Quick reply response type - `"quick_reply_resp"` - `selectedOptionId: string` ID of the selected option - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `RatingRequested object { id, createdAt, csat, 3 more }` Represents a persisted CSAT request in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: object { channel, requestedAt, requestId, 7 more }` Canonical CSAT request payload for this thread event - `channel: "desktop" or "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" or "rated" or "canceled" or "expired"` Status of the CSAT request represented by this part - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt: optional string` ISO timestamp after which changing the rating is no longer allowed - `expiredAt: optional string` ISO timestamp when the request expired, when applicable - `lateSubmitWindowEndsAt: optional string` ISO timestamp after which late submission is no longer allowed - `ratedAgent: optional CsatRatedAgent` - `type: "teammate" or "fibi" or "chatbot"` Type of agent the CSAT request is attributed to - `"teammate"` - `"fibi"` - `"chatbot"` - `id: optional string` Identifier of the rated agent when applicable - `workflow: optional CsatWorkflowLink` - `workflowActionId: optional string` Workflow action ID associated with the CSAT request - `workflowId: optional string` Workflow ID associated with the CSAT request - `workflowRunId: optional string` Workflow run ID associated with the CSAT request - `workflowStepId: optional string` Workflow step ID associated with the CSAT request - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_requested"` CSAT rating requested part type - `"rating_requested"` - `updatedAt: string` ISO timestamp when the part was last updated - `RatingSubmitted object { id, createdAt, csat, 3 more }` Represents a persisted CSAT submission in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: object { channel, ratedAt, requestId, 7 more }` Canonical CSAT submission payload for this thread event - `channel: "desktop" or "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `ratedAt: string` ISO timestamp when the customer submitted the rating - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `score: number` CSAT score from 1 to 5 - `status: "rated"` Submitted ratings are always in the rated state - `"rated"` - `ratedAgent: optional CsatRatedAgent` - `remark: optional string` Optional remark left with the rating - `requestedAt: optional string` ISO timestamp when the request was created - `workflow: optional CsatWorkflowLink` - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_submitted"` CSAT rating submitted part type - `"rating_submitted"` - `updatedAt: string` ISO timestamp when the part was last updated - `AttrPrompt object { id, createdAt, form, 6 more }` Requests information from user via form - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `form: object { id, attributes }` Form configuration - `id: string` Form ID - `attributes: array of object { identifier, name, type }` Form fields - `identifier: string` Field identifier - `name: string` Field display name - `type: string` Field type - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_prompt"` Attribute collection prompt type - `"attr_prompt"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AttrComplete object { id, createdAt, object, 2 more }` Indicates form was completed - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_complete"` Attribute collection complete type - `"attr_complete"` - `updatedAt: string` ISO timestamp when the part was last updated - `Assign object { id, createdAt, object, 5 more }` Conversation assigned to admin or team - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "assign"` Assignment type - `"assign"` - `updatedAt: string` ISO timestamp when the part was last updated - `adminAssigneeId: optional string` ID of the admin assigned to the conversation - `adminAssignerId: optional string` ID of the admin who made the assignment - `teamAssigneeId: optional string` ID of the team assigned to the conversation - `Status object { id, createdAt, object, 4 more }` Conversation state changed (open/closed/snoozed) - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "status"` Status change type - `"status"` - `status: "open" or "closed" or "snoozed"` New conversation status - `"open"` - `"closed"` - `"snoozed"` - `updatedAt: string` ISO timestamp when the part was last updated - `snoozedUntil: optional string` ISO timestamp until conversation is snoozed (if snoozed) - `Tags object { id, action, createdAt, 8 more }` A tag was added to or removed from a specific reply - `id: string` Unique part identifier - `action: "added" or "removed"` Whether the tag was added or removed - `"added"` - `"removed"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `occurredAt: string` ISO timestamp when the tag mutation occurred - `partType: "tags"` Tag update type - `"tags"` - `tagId: string` Identifier of the affected tag - `updatedAt: string` ISO timestamp when the part was last updated - `actor: optional ConversationTagMutationActor` Actor that applied the tag - `tagName: optional string` Tag name at the time of the event or the best available current display name - `targetPartId: optional string` Conversation part that the tag mutation targeted - `WorkflowWait object { id, createdAt, object, 3 more }` Represents a workflow wait start, finish, or interruption in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "workflow_wait"` Workflow wait event part type - `"workflow_wait"` - `updatedAt: string` ISO timestamp when the part was last updated - `workflowWait: object { eventType, occurredAt, interruptedByUserType, 3 more }` Workflow wait event payload for this thread event - `eventType: "started" or "finished" or "interrupted"` Lifecycle stage of the workflow wait event - `"started"` - `"finished"` - `"interrupted"` - `occurredAt: string` ISO timestamp when the wait event occurred - `interruptedByUserType: optional "admin" or "customer" or "lead"` User type that interrupted the wait when applicable - `"admin"` - `"customer"` - `"lead"` - `waitLabel: optional string` Human-readable wait duration or preset label - `workflowId: optional string` Workflow ID associated with the wait event - `workflowName: optional string` Workflow display name at the time of the wait event - `Priority object { id, createdAt, isPriority, 3 more }` Conversation priority was updated - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `isPriority: boolean` Whether the conversation is now marked as priority - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "priority"` Priority change type - `"priority"` - `updatedAt: string` ISO timestamp when the part was last updated - `PartAdd object { id, createdAt, object, 3 more }` New participant joined the conversation - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `participant: object { id, type }` The added participant - `id: string` Participant ID - `type: "customer" or "lead" or "admin"` Participant type - `"customer"` - `"lead"` - `"admin"` - `partType: "part_add"` Participant added type - `"part_add"` - `updatedAt: string` ISO timestamp when the part was last updated - `csatDebug: optional object { requestId, status, changeLockWindowEndsAt, 2 more }` Minimal CSAT diagnostics for the current effective request. - `requestId: string` Canonical CSAT request ID used for the latest debug snapshot - `status: "pending" or "rated" or "canceled" or "expired"` Lifecycle status of the request represented in the debug snapshot - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt: optional string` ISO timestamp when rating edits stop being accepted - `emailDelivery: optional CsatEmailDelivery` - `status: "pending" or "sent" or "failed"` Email delivery status for the CSAT request when applicable - `"pending"` - `"sent"` - `"failed"` - `failedAt: optional string` ISO timestamp when the CSAT email failed - `failureReason: optional string` Operational failure reason for the CSAT email delivery - `messageId: optional string` Email message ID associated with delivery - `sentAt: optional string` ISO timestamp when the CSAT email was sent - `lateSubmitWindowEndsAt: optional string` ISO timestamp when first-time submissions stop being accepted - `csatHistory: optional array of object { channel, isLatestEffective, lastUpdatedAt, 14 more }` Historical CSAT requests for this conversation, ordered newest first. - `channel: "desktop" or "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `isLatestEffective: boolean` Whether this row represents the currently effective CSAT request for the conversation - `lastUpdatedAt: string` ISO timestamp when the request last changed - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" or "rated" or "canceled" or "expired"` Lifecycle status for this historical CSAT request - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt: optional string` ISO timestamp when the request was canceled - `changeLockWindowEndsAt: optional string` ISO timestamp when edits to an existing rating stop being accepted - `emailDelivery: optional CsatEmailDelivery` - `expiredAt: optional string` ISO timestamp when the request expired - `lateSubmitWindowEndsAt: optional string` ISO timestamp when first-time submissions stop being accepted - `ratedAgent: optional CsatRatedAgent` - `ratedAt: optional string` ISO timestamp when the request was rated - `remark: optional string` Submitted remark when present - `score: optional number` Submitted score when this request was rated - `workflow: optional CsatWorkflowLink` - `csatSummary: optional object { lastUpdatedAt, status, canceledAt, 10 more }` Derived CSAT summary for this conversation when a rating request or rating exists. - `lastUpdatedAt: string` ISO timestamp when the summary last changed - `status: "pending" or "rated" or "canceled" or "expired"` Current summary status for CSAT on this conversation - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt: optional string` ISO timestamp when the request was canceled - `channel: optional "desktop" or "email"` Channel used for the latest CSAT request when known - `"desktop"` - `"email"` - `expiredAt: optional string` ISO timestamp when the request expired - `ratedAgent: optional CsatRatedAgent` - `ratedAt: optional string` ISO timestamp when the customer submitted a rating - `remark: optional string` Optional remark left with the rating - `requestedAt: optional string` ISO timestamp when the latest CSAT request was created - `requestId: optional string` Canonical CSAT request ID - `requestSource: optional "workflow"` Source of the latest CSAT request when known - `"workflow"` - `score: optional number` CSAT score from 1 to 5 when rated - `workflow: optional CsatWorkflowLink` - `disableCustomerReply: optional boolean` Whether customer replies are disabled - `readReceipts: optional array of object { id, lastReadPartId, userType }` Read receipts indicating how far each participant has read in the conversation. Each receipt maps a user to their last-read conversation part. The tracked position reflects the system read state and may reference parts the user cannot directly view (e.g., a contact's read position may point to an internal admin note). Use these receipts to render read indicators and typing awareness, not to infer content access. - `id: string` The internal ID of the user - `lastReadPartId: string` The ID of the last conversation part this user has read. Note: This reflects the system-tracked read position and may reference a part the user cannot directly access (e.g., internal notes for contacts). The read state is advanced to the latest part in the conversation regardless of part visibility. - `userType: "admin" or "customer" or "lead"` Type of user who has read the conversation - `"admin"` - `"customer"` - `"lead"` - `source: optional object { bodyHtml, bodyMarkdown, channel, 4 more }` - `bodyHtml: string` Body of the initial message as HTML with signed image URLs - `bodyMarkdown: string` Body of the initial message as markdown - `channel: "unknown" or "desktop" or "android" or 2 more` Channel through which the conversation was initiated - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `author: optional ConversationParticipant` - `id: string` Participant ID - `type: "customer" or "lead" or "admin" or 3 more` Type of participant - `deliveredAs: optional "customer_initiated" or "admin_initiated"` How the conversation was initiated - `"customer_initiated"` - `"admin_initiated"` - `subject: optional string` Subject line for email conversations - `url: optional string` URL where the conversation was initiated - `title: optional string` Conversation title ### Example ```http curl https://do.featurebase.app/v2/conversations/$ID \ -H "Authorization: Bearer $FEATUREBASE_API_KEY" ``` #### Response ```json { "id": "12345", "adminAssigneeId": "507f1f77bcf86cd799439011", "botConversationStateLastUpdatedAt": "2025-01-15T10:30:00.000Z", "brandId": "507f1f77bcf86cd799439011", "createdAt": "2025-01-15T10:30:00.000Z", "hasAdminOverriddenLanguage": false, "isBlocked": false, "lastActivityAt": "2025-01-15T12:30:00.000Z", "object": "conversation", "participants": [ { "id": "676f0f6765bdaa7d7d760f88", "type": "customer" } ], "priority": false, "prioritySetAt": "2025-01-15T10:30:00.000Z", "snoozedUntil": "2025-01-16T09:00:00.000Z", "state": "open", "tags": [ { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } ], "teamAssigneeId": "507f1f77bcf86cd799439012", "updatedAt": "2025-01-15T12:30:00.000Z", "userPreferredLanguage": "en", "waitingSince": "2025-01-15T10:30:00.000Z", "awaitingCustomerReply": true, "botConversationState": "active", "conversationParts": [ { "id": "1", "bodyHtml": "Hello, I have a question about your product.
", "bodyMarkdown": "Hello, I have a question about your product.", "channel": "desktop", "createdAt": "2025-01-15T10:30:00.000Z", "object": "conversation_part", "partType": "user_msg", "updatedAt": "2025-01-15T10:30:00.000Z", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/user.png" }, "redacted": false, "tagApplications": [ { "appliedAt": "2025-01-15T10:30:00.000Z", "tagId": "67ec1234abcd5678ef901234", "appliedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "removedAt": "2025-01-15T11:00:00.000Z", "removedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "tag": { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } } ] } ], "csatDebug": { "requestId": "csat_req_123", "status": "pending", "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z", "emailDelivery": { "status": "failed", "failedAt": "2025-01-15T10:31:00.000Z", "failureReason": "smtp_bounce", "messageId": "msg_123", "sentAt": "2025-01-15T10:31:00.000Z" }, "lateSubmitWindowEndsAt": "2025-01-16T10:30:00.000Z" }, "csatHistory": [ { "channel": "desktop", "isLatestEffective": true, "lastUpdatedAt": "2025-01-15T10:35:00.000Z", "requestedAt": "2025-01-15T10:30:00.000Z", "requestId": "csat_req_123", "requestSource": "workflow", "status": "pending", "canceledAt": "2025-01-15T10:32:00.000Z", "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z", "emailDelivery": { "status": "failed", "failedAt": "2025-01-15T10:31:00.000Z", "failureReason": "smtp_bounce", "messageId": "msg_123", "sentAt": "2025-01-15T10:31:00.000Z" }, "expiredAt": "2025-01-16T10:30:00.000Z", "lateSubmitWindowEndsAt": "2025-01-16T10:30:00.000Z", "ratedAgent": { "type": "teammate", "id": "507f1f77bcf86cd799439011" }, "ratedAt": "2025-01-15T10:35:00.000Z", "remark": "Thanks for the quick help.", "score": 4, "workflow": { "workflowActionId": "action_123", "workflowId": "507f1f77bcf86cd799439011", "workflowRunId": "run_123", "workflowStepId": "step_123" } } ], "csatSummary": { "lastUpdatedAt": "2025-01-15T10:35:00.000Z", "status": "pending", "canceledAt": "2025-01-15T10:35:00.000Z", "channel": "desktop", "expiredAt": "2025-01-15T10:35:00.000Z", "ratedAgent": { "type": "teammate", "id": "507f1f77bcf86cd799439011" }, "ratedAt": "2025-01-15T10:35:00.000Z", "remark": "Very helpful support.", "requestedAt": "2025-01-15T10:30:00.000Z", "requestId": "csat_req_123", "requestSource": "workflow", "score": 5, "workflow": { "workflowActionId": "action_123", "workflowId": "507f1f77bcf86cd799439011", "workflowRunId": "run_123", "workflowStepId": "step_123" } }, "disableCustomerReply": false, "readReceipts": [ { "id": "507f1f77bcf86cd799439011", "lastReadPartId": "8", "userType": "admin" } ], "source": { "bodyHtml": "Hi, I have a question about your enterprise plan...
", "bodyMarkdown": "Hi, I have a question about your enterprise plan...", "channel": "desktop", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer" }, "deliveredAs": "customer_initiated", "subject": "Question about pricing", "url": "https://example.com/pricing" }, "title": "Question about pricing" } ``` ## Delete a conversation **delete** `/v2/conversations/{id}` Permanently deletes a conversation by its short ID. ### Path Parameters - `id` - The conversation short ID (numeric) ### Response Returns a deletion confirmation object: ```json { "id": "12345", "object": "conversation", "deleted": true } ``` ### Caution This operation is **irreversible**. The conversation and all its messages will be permanently deleted. ### Version Availability This endpoint is only available in API version 2026-01-01.nova and newer. ### Path Parameters - `id: string` Conversation ID (short ID) ### Header Parameters - `"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"` - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `id: string` Unique identifier of the deleted conversation - `deleted: true` Indicates the resource was deleted - `true` - `object: "conversation"` Object type identifier - `"conversation"` ### Example ```http curl https://do.featurebase.app/v2/conversations/$ID \ -X DELETE \ -H "Authorization: Bearer $FEATUREBASE_API_KEY" ``` #### Response ```json { "id": "12345", "deleted": true, "object": "conversation" } ``` ## Update a conversation **patch** `/v2/conversations/{id}` Updates a conversation's properties. Supports partial updates - only provided fields will be updated. ### Path Parameters - `id` - The conversation ID (short ID) ### Request Body All fields are optional. Only provided fields will be updated. | Field | Type | Description | | ------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | | `actingAdminId` | string | Admin ID performing the action (for attribution). If not provided, uses bot service user. Must be a member of the organization. | | `state` | string | Conversation state: "open", "closed", or "snoozed" | | `snoozedUntil` | string | ISO datetime when to unsnooze (required when state is "snoozed") | | `adminAssigneeId` | string/null | Admin ID to assign, or null to unassign | | `teamAssigneeId` | string/null | Team ID to assign, or null to unassign | | `title` | string | Conversation title | | `customAttributes` | object | Custom attributes to set on the conversation | | `markAsRead` | object | Mark conversation as read for specific users | ### markAsRead Object | Field | Type | Description | | ------------- | -------- | -------------------------------------------------------------- | | `allAdmins` | boolean | If true, marks all admins with existing readReceipts as read | | `adminIds` | string[] | Array of specific admin IDs to mark as read | | `allContacts` | boolean | If true, marks all contacts with existing readReceipts as read | | `contactIds` | string[] | Array of specific contact IDs to mark as read | Note: Only users with existing read receipts will be updated. Use `allAdmins`/`allContacts` OR `adminIds`/`contactIds` - the "all" flags take precedence. ### Response Returns the updated conversation object. ### Example: Close a Conversation (with attribution) ```json { "actingAdminId": "507f1f77bcf86cd799439011", "state": "closed" } ``` ### Example: Close a Conversation (bot user) ```json { "state": "closed" } ``` ### Example: Snooze a Conversation ```json { "state": "snoozed", "snoozedUntil": "2025-01-20T10:00:00.000Z" } ``` ### Example: Assign to an Admin ```json { "adminAssigneeId": "507f1f77bcf86cd799439011" } ``` ### Example: Update Title and Custom Attributes ```json { "title": "Billing Issue - Priority", "customAttributes": { "priority_level": "high", "category": "billing" } } ``` ### Example: Mark as Read (All Admins) ```json { "markAsRead": { "allAdmins": true } } ``` ### Example: Mark as Read (All Contacts) ```json { "markAsRead": { "allContacts": true } } ``` ### Example: Mark as Read (Specific IDs) ```json { "markAsRead": { "adminIds": ["507f1f77bcf86cd799439011"], "contactIds": ["676f0f6765bdaa7d7d760f88"] } } ``` ### Version Availability This endpoint is only available in API version 2026-01-01.nova and newer. ### Path Parameters - `id: string` Conversation ID (short ID) ### Header Parameters - `"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"` - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Body Parameters - `actingAdminId: optional string` The admin ID performing this action. Changes will be attributed to this admin. If not provided, changes are attributed to the system bot user. The admin must be a member of the organization. - `adminAssigneeId: optional string` The admin ID to assign the conversation to, or null to unassign. - `customAttributes: optional map[unknown]` Custom attributes to set on the conversation. Uses the same validation as v1 API. - `markAsRead: optional object { adminIds, allAdmins, allContacts, contactIds }` Mark the conversation as read for specific admins and/or contacts. - `adminIds: optional array of string` Array of admin IDs to mark as read. Only admins with existing readReceipts will be updated. - `allAdmins: optional boolean` If true, marks all admins with existing readReceipts as read. - `allContacts: optional boolean` If true, marks all contacts (customers and leads) with existing readReceipts as read. - `contactIds: optional array of string` Array of contact IDs to mark as read. Only contacts with existing readReceipts will be updated. - `snoozedUntil: optional string` ISO datetime when the conversation should be unsnoozed. Required when state is "snoozed". Must be a future date. - `state: optional "open" or "closed" or "snoozed"` The state of the conversation. Use "snoozed" with snoozedUntil to snooze. - `"open"` - `"closed"` - `"snoozed"` - `teamAssigneeId: optional string` The team ID to assign the conversation to, or null to unassign. - `title: optional string` The title of the conversation. ### Returns - `Conversation object { id, adminAssigneeId, botConversationStateLastUpdatedAt, 26 more }` - `id: string` Unique conversation identifier - `adminAssigneeId: string` ID of the assigned admin - `botConversationStateLastUpdatedAt: string` ISO timestamp when bot state last changed - `brandId: string` ID of the brand associated with this conversation - `createdAt: string` ISO timestamp when conversation was created - `hasAdminOverriddenLanguage: boolean` Whether an admin has manually overridden the language for this conversation. When true, automatic language detection is disabled. - `isBlocked: boolean` Whether the user is blocked - `lastActivityAt: string` ISO timestamp of last activity - `object: "conversation"` Object type identifier - `"conversation"` - `participants: array of ConversationParticipant` Participants in this conversation - `id: string` Participant ID - `type: "customer" or "lead" or "admin" or 3 more` Type of participant - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `priority: boolean` Whether this conversation is marked as priority - `prioritySetAt: string` ISO timestamp when priority was set - `snoozedUntil: string` ISO timestamp until which conversation is snoozed - `state: "open" or "closed" or "snoozed"` Current state of the conversation - `"open"` - `"closed"` - `"snoozed"` - `tags: array of ConversationTag` Current tags applied anywhere in this conversation - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `teamAssigneeId: string` ID of the assigned team - `updatedAt: string` ISO timestamp when conversation was last updated - `userPreferredLanguage: string` User's preferred language - `waitingSince: string` ISO timestamp when conversation started waiting - `awaitingCustomerReply: optional boolean` Whether we are awaiting a customer reply - `botConversationState: optional "active" or "handed_off_to_human" or "resolved"` State of AI agent handling for this conversation - `"active"` - `"handed_off_to_human"` - `"resolved"` - `conversationParts: optional array of ConversationPart` Array of conversation parts (messages). Only included when fetching a single conversation by ID. - `UserMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Message from a customer or lead - `id: string` Unique part identifier - `bodyHtml: string` Message body content as HTML with signed image URLs - `bodyMarkdown: string` Message body content as markdown - `channel: "unknown" or "desktop" or "android" or 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "user_msg"` User message type - `"user_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `id: string` Author ID - `type: "customer" or "lead" or "admin" or 3 more` Type of author - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `email: optional string` Author email address - `name: optional string` Author display name - `profilePicture: optional string` Author profile picture URL - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `type: "admin" or "customer" or "lead" or 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id: optional string` Actor identifier when available - `name: optional string` Actor display name when available - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `AdminMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Message from an admin or support agent - `id: string` Unique part identifier - `bodyHtml: string` Message body content as HTML with signed image URLs - `bodyMarkdown: string` Message body content as markdown - `channel: "unknown" or "desktop" or "android" or 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_msg"` Admin message type - `"admin_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AdminNote object { id, bodyHtml, bodyMarkdown, 7 more }` Internal note visible only to admins - `id: string` Unique part identifier - `bodyHtml: string` Note body content as HTML with signed image URLs - `bodyMarkdown: string` Note body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_note"` Admin internal note type - `"admin_note"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `EmailMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Message sent via email - `id: string` Unique part identifier - `bodyHtml: string` Email body content as HTML with signed image URLs - `bodyMarkdown: string` Email body content as markdown - `channel: "email"` Email channel - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "email_msg"` Email message type - `"email_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `BotMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Automated message from AI or bot - `id: string` Unique part identifier - `bodyHtml: string` Bot message body content as HTML with signed image URLs - `bodyMarkdown: string` Bot message body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "bot_msg"` Bot message type - `"bot_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `channel: optional "unknown" or "desktop" or "android" or 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyOpts object { id, createdAt, object, 6 more }` Presents options for user to choose from - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_opts"` Quick reply options type - `"quick_reply_opts"` - `replyOptions: array of object { id, text }` Available reply options - `id: string` Option ID - `text: string` Option text - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyResp object { id, bodyHtml, bodyMarkdown, 8 more }` User's selection from quick reply options - `id: string` Unique part identifier - `bodyHtml: string` The selected option text as HTML - `bodyMarkdown: string` The selected option text as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_resp"` Quick reply response type - `"quick_reply_resp"` - `selectedOptionId: string` ID of the selected option - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `RatingRequested object { id, createdAt, csat, 3 more }` Represents a persisted CSAT request in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: object { channel, requestedAt, requestId, 7 more }` Canonical CSAT request payload for this thread event - `channel: "desktop" or "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" or "rated" or "canceled" or "expired"` Status of the CSAT request represented by this part - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt: optional string` ISO timestamp after which changing the rating is no longer allowed - `expiredAt: optional string` ISO timestamp when the request expired, when applicable - `lateSubmitWindowEndsAt: optional string` ISO timestamp after which late submission is no longer allowed - `ratedAgent: optional CsatRatedAgent` - `type: "teammate" or "fibi" or "chatbot"` Type of agent the CSAT request is attributed to - `"teammate"` - `"fibi"` - `"chatbot"` - `id: optional string` Identifier of the rated agent when applicable - `workflow: optional CsatWorkflowLink` - `workflowActionId: optional string` Workflow action ID associated with the CSAT request - `workflowId: optional string` Workflow ID associated with the CSAT request - `workflowRunId: optional string` Workflow run ID associated with the CSAT request - `workflowStepId: optional string` Workflow step ID associated with the CSAT request - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_requested"` CSAT rating requested part type - `"rating_requested"` - `updatedAt: string` ISO timestamp when the part was last updated - `RatingSubmitted object { id, createdAt, csat, 3 more }` Represents a persisted CSAT submission in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: object { channel, ratedAt, requestId, 7 more }` Canonical CSAT submission payload for this thread event - `channel: "desktop" or "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `ratedAt: string` ISO timestamp when the customer submitted the rating - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `score: number` CSAT score from 1 to 5 - `status: "rated"` Submitted ratings are always in the rated state - `"rated"` - `ratedAgent: optional CsatRatedAgent` - `remark: optional string` Optional remark left with the rating - `requestedAt: optional string` ISO timestamp when the request was created - `workflow: optional CsatWorkflowLink` - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_submitted"` CSAT rating submitted part type - `"rating_submitted"` - `updatedAt: string` ISO timestamp when the part was last updated - `AttrPrompt object { id, createdAt, form, 6 more }` Requests information from user via form - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `form: object { id, attributes }` Form configuration - `id: string` Form ID - `attributes: array of object { identifier, name, type }` Form fields - `identifier: string` Field identifier - `name: string` Field display name - `type: string` Field type - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_prompt"` Attribute collection prompt type - `"attr_prompt"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AttrComplete object { id, createdAt, object, 2 more }` Indicates form was completed - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_complete"` Attribute collection complete type - `"attr_complete"` - `updatedAt: string` ISO timestamp when the part was last updated - `Assign object { id, createdAt, object, 5 more }` Conversation assigned to admin or team - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "assign"` Assignment type - `"assign"` - `updatedAt: string` ISO timestamp when the part was last updated - `adminAssigneeId: optional string` ID of the admin assigned to the conversation - `adminAssignerId: optional string` ID of the admin who made the assignment - `teamAssigneeId: optional string` ID of the team assigned to the conversation - `Status object { id, createdAt, object, 4 more }` Conversation state changed (open/closed/snoozed) - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "status"` Status change type - `"status"` - `status: "open" or "closed" or "snoozed"` New conversation status - `"open"` - `"closed"` - `"snoozed"` - `updatedAt: string` ISO timestamp when the part was last updated - `snoozedUntil: optional string` ISO timestamp until conversation is snoozed (if snoozed) - `Tags object { id, action, createdAt, 8 more }` A tag was added to or removed from a specific reply - `id: string` Unique part identifier - `action: "added" or "removed"` Whether the tag was added or removed - `"added"` - `"removed"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `occurredAt: string` ISO timestamp when the tag mutation occurred - `partType: "tags"` Tag update type - `"tags"` - `tagId: string` Identifier of the affected tag - `updatedAt: string` ISO timestamp when the part was last updated - `actor: optional ConversationTagMutationActor` Actor that applied the tag - `tagName: optional string` Tag name at the time of the event or the best available current display name - `targetPartId: optional string` Conversation part that the tag mutation targeted - `WorkflowWait object { id, createdAt, object, 3 more }` Represents a workflow wait start, finish, or interruption in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "workflow_wait"` Workflow wait event part type - `"workflow_wait"` - `updatedAt: string` ISO timestamp when the part was last updated - `workflowWait: object { eventType, occurredAt, interruptedByUserType, 3 more }` Workflow wait event payload for this thread event - `eventType: "started" or "finished" or "interrupted"` Lifecycle stage of the workflow wait event - `"started"` - `"finished"` - `"interrupted"` - `occurredAt: string` ISO timestamp when the wait event occurred - `interruptedByUserType: optional "admin" or "customer" or "lead"` User type that interrupted the wait when applicable - `"admin"` - `"customer"` - `"lead"` - `waitLabel: optional string` Human-readable wait duration or preset label - `workflowId: optional string` Workflow ID associated with the wait event - `workflowName: optional string` Workflow display name at the time of the wait event - `Priority object { id, createdAt, isPriority, 3 more }` Conversation priority was updated - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `isPriority: boolean` Whether the conversation is now marked as priority - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "priority"` Priority change type - `"priority"` - `updatedAt: string` ISO timestamp when the part was last updated - `PartAdd object { id, createdAt, object, 3 more }` New participant joined the conversation - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `participant: object { id, type }` The added participant - `id: string` Participant ID - `type: "customer" or "lead" or "admin"` Participant type - `"customer"` - `"lead"` - `"admin"` - `partType: "part_add"` Participant added type - `"part_add"` - `updatedAt: string` ISO timestamp when the part was last updated - `csatDebug: optional object { requestId, status, changeLockWindowEndsAt, 2 more }` Minimal CSAT diagnostics for the current effective request. - `requestId: string` Canonical CSAT request ID used for the latest debug snapshot - `status: "pending" or "rated" or "canceled" or "expired"` Lifecycle status of the request represented in the debug snapshot - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt: optional string` ISO timestamp when rating edits stop being accepted - `emailDelivery: optional CsatEmailDelivery` - `status: "pending" or "sent" or "failed"` Email delivery status for the CSAT request when applicable - `"pending"` - `"sent"` - `"failed"` - `failedAt: optional string` ISO timestamp when the CSAT email failed - `failureReason: optional string` Operational failure reason for the CSAT email delivery - `messageId: optional string` Email message ID associated with delivery - `sentAt: optional string` ISO timestamp when the CSAT email was sent - `lateSubmitWindowEndsAt: optional string` ISO timestamp when first-time submissions stop being accepted - `csatHistory: optional array of object { channel, isLatestEffective, lastUpdatedAt, 14 more }` Historical CSAT requests for this conversation, ordered newest first. - `channel: "desktop" or "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `isLatestEffective: boolean` Whether this row represents the currently effective CSAT request for the conversation - `lastUpdatedAt: string` ISO timestamp when the request last changed - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" or "rated" or "canceled" or "expired"` Lifecycle status for this historical CSAT request - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt: optional string` ISO timestamp when the request was canceled - `changeLockWindowEndsAt: optional string` ISO timestamp when edits to an existing rating stop being accepted - `emailDelivery: optional CsatEmailDelivery` - `expiredAt: optional string` ISO timestamp when the request expired - `lateSubmitWindowEndsAt: optional string` ISO timestamp when first-time submissions stop being accepted - `ratedAgent: optional CsatRatedAgent` - `ratedAt: optional string` ISO timestamp when the request was rated - `remark: optional string` Submitted remark when present - `score: optional number` Submitted score when this request was rated - `workflow: optional CsatWorkflowLink` - `csatSummary: optional object { lastUpdatedAt, status, canceledAt, 10 more }` Derived CSAT summary for this conversation when a rating request or rating exists. - `lastUpdatedAt: string` ISO timestamp when the summary last changed - `status: "pending" or "rated" or "canceled" or "expired"` Current summary status for CSAT on this conversation - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt: optional string` ISO timestamp when the request was canceled - `channel: optional "desktop" or "email"` Channel used for the latest CSAT request when known - `"desktop"` - `"email"` - `expiredAt: optional string` ISO timestamp when the request expired - `ratedAgent: optional CsatRatedAgent` - `ratedAt: optional string` ISO timestamp when the customer submitted a rating - `remark: optional string` Optional remark left with the rating - `requestedAt: optional string` ISO timestamp when the latest CSAT request was created - `requestId: optional string` Canonical CSAT request ID - `requestSource: optional "workflow"` Source of the latest CSAT request when known - `"workflow"` - `score: optional number` CSAT score from 1 to 5 when rated - `workflow: optional CsatWorkflowLink` - `disableCustomerReply: optional boolean` Whether customer replies are disabled - `readReceipts: optional array of object { id, lastReadPartId, userType }` Read receipts indicating how far each participant has read in the conversation. Each receipt maps a user to their last-read conversation part. The tracked position reflects the system read state and may reference parts the user cannot directly view (e.g., a contact's read position may point to an internal admin note). Use these receipts to render read indicators and typing awareness, not to infer content access. - `id: string` The internal ID of the user - `lastReadPartId: string` The ID of the last conversation part this user has read. Note: This reflects the system-tracked read position and may reference a part the user cannot directly access (e.g., internal notes for contacts). The read state is advanced to the latest part in the conversation regardless of part visibility. - `userType: "admin" or "customer" or "lead"` Type of user who has read the conversation - `"admin"` - `"customer"` - `"lead"` - `source: optional object { bodyHtml, bodyMarkdown, channel, 4 more }` - `bodyHtml: string` Body of the initial message as HTML with signed image URLs - `bodyMarkdown: string` Body of the initial message as markdown - `channel: "unknown" or "desktop" or "android" or 2 more` Channel through which the conversation was initiated - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `author: optional ConversationParticipant` - `id: string` Participant ID - `type: "customer" or "lead" or "admin" or 3 more` Type of participant - `deliveredAs: optional "customer_initiated" or "admin_initiated"` How the conversation was initiated - `"customer_initiated"` - `"admin_initiated"` - `subject: optional string` Subject line for email conversations - `url: optional string` URL where the conversation was initiated - `title: optional string` Conversation title ### Example ```http curl https://do.featurebase.app/v2/conversations/$ID \ -X PATCH \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $FEATUREBASE_API_KEY" \ -d '{ "actingAdminId": "507f1f77bcf86cd799439011", "adminAssigneeId": "507f1f77bcf86cd799439011", "customAttributes": { "priority_level": "bar", "category": "bar" }, "snoozedUntil": "2025-01-20T10:00:00.000Z", "state": "open", "teamAssigneeId": "507f1f77bcf86cd799439012", "title": "Question about pricing" }' ``` #### Response ```json { "id": "12345", "adminAssigneeId": "507f1f77bcf86cd799439011", "botConversationStateLastUpdatedAt": "2025-01-15T10:30:00.000Z", "brandId": "507f1f77bcf86cd799439011", "createdAt": "2025-01-15T10:30:00.000Z", "hasAdminOverriddenLanguage": false, "isBlocked": false, "lastActivityAt": "2025-01-15T12:30:00.000Z", "object": "conversation", "participants": [ { "id": "676f0f6765bdaa7d7d760f88", "type": "customer" } ], "priority": false, "prioritySetAt": "2025-01-15T10:30:00.000Z", "snoozedUntil": "2025-01-16T09:00:00.000Z", "state": "open", "tags": [ { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } ], "teamAssigneeId": "507f1f77bcf86cd799439012", "updatedAt": "2025-01-15T12:30:00.000Z", "userPreferredLanguage": "en", "waitingSince": "2025-01-15T10:30:00.000Z", "awaitingCustomerReply": true, "botConversationState": "active", "conversationParts": [ { "id": "1", "bodyHtml": "Hello, I have a question about your product.
", "bodyMarkdown": "Hello, I have a question about your product.", "channel": "desktop", "createdAt": "2025-01-15T10:30:00.000Z", "object": "conversation_part", "partType": "user_msg", "updatedAt": "2025-01-15T10:30:00.000Z", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/user.png" }, "redacted": false, "tagApplications": [ { "appliedAt": "2025-01-15T10:30:00.000Z", "tagId": "67ec1234abcd5678ef901234", "appliedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "removedAt": "2025-01-15T11:00:00.000Z", "removedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "tag": { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } } ] } ], "csatDebug": { "requestId": "csat_req_123", "status": "pending", "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z", "emailDelivery": { "status": "failed", "failedAt": "2025-01-15T10:31:00.000Z", "failureReason": "smtp_bounce", "messageId": "msg_123", "sentAt": "2025-01-15T10:31:00.000Z" }, "lateSubmitWindowEndsAt": "2025-01-16T10:30:00.000Z" }, "csatHistory": [ { "channel": "desktop", "isLatestEffective": true, "lastUpdatedAt": "2025-01-15T10:35:00.000Z", "requestedAt": "2025-01-15T10:30:00.000Z", "requestId": "csat_req_123", "requestSource": "workflow", "status": "pending", "canceledAt": "2025-01-15T10:32:00.000Z", "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z", "emailDelivery": { "status": "failed", "failedAt": "2025-01-15T10:31:00.000Z", "failureReason": "smtp_bounce", "messageId": "msg_123", "sentAt": "2025-01-15T10:31:00.000Z" }, "expiredAt": "2025-01-16T10:30:00.000Z", "lateSubmitWindowEndsAt": "2025-01-16T10:30:00.000Z", "ratedAgent": { "type": "teammate", "id": "507f1f77bcf86cd799439011" }, "ratedAt": "2025-01-15T10:35:00.000Z", "remark": "Thanks for the quick help.", "score": 4, "workflow": { "workflowActionId": "action_123", "workflowId": "507f1f77bcf86cd799439011", "workflowRunId": "run_123", "workflowStepId": "step_123" } } ], "csatSummary": { "lastUpdatedAt": "2025-01-15T10:35:00.000Z", "status": "pending", "canceledAt": "2025-01-15T10:35:00.000Z", "channel": "desktop", "expiredAt": "2025-01-15T10:35:00.000Z", "ratedAgent": { "type": "teammate", "id": "507f1f77bcf86cd799439011" }, "ratedAt": "2025-01-15T10:35:00.000Z", "remark": "Very helpful support.", "requestedAt": "2025-01-15T10:30:00.000Z", "requestId": "csat_req_123", "requestSource": "workflow", "score": 5, "workflow": { "workflowActionId": "action_123", "workflowId": "507f1f77bcf86cd799439011", "workflowRunId": "run_123", "workflowStepId": "step_123" } }, "disableCustomerReply": false, "readReceipts": [ { "id": "507f1f77bcf86cd799439011", "lastReadPartId": "8", "userType": "admin" } ], "source": { "bodyHtml": "Hi, I have a question about your enterprise plan...
", "bodyMarkdown": "Hi, I have a question about your enterprise plan...", "channel": "desktop", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer" }, "deliveredAs": "customer_initiated", "subject": "Question about pricing", "url": "https://example.com/pricing" }, "title": "Question about pricing" } ``` ## Reply to a conversation **post** `/v2/conversations/{id}/reply` Adds a reply to an existing conversation. Supports both contact (customer/lead) and admin replies. ### Path Parameters - `id` - The conversation ID (short ID) ### Request Body The request body varies based on who is sending the reply: #### Contact Reply (customer/lead) | Field | Type | Required | Description | | ------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `type` | string | Yes | Must be "contact" | | `userId` | string | No* | External user ID from your system | | `id` | string | No* | Featurebase contact ID (24-character ObjectId) | | `bodyMarkdown` | string | Yes | The message content in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored. | | `messageType` | string | Yes | Must be "reply" | | `skipNotifications` | boolean | No | Skip sending notifications (default: false). Useful for bulk imports. | \*At least one of `userId` or `id` is required. #### Admin Reply | Field | Type | Required | Description | | ------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `type` | string | Yes | Must be "admin" | | `id` | string | Yes | Featurebase admin ID (24-character ObjectId) | | `bodyMarkdown` | string | Yes | The message content in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored. | | `messageType` | string | Yes | "reply" for customer-visible reply, "note" for internal note | | `skipNotifications` | boolean | No | Skip sending notifications (default: false). Useful for bulk imports. | ### Response Returns the created conversation part object with a **201 Created** status. The response includes both `bodyHtml` (with signed image URLs) and `bodyMarkdown` fields. ### Example Contact Reply ```json { "type": "contact", "userId": "user_123", "bodyMarkdown": "Thank you for your help!", "messageType": "reply" } ``` ### Example Admin Reply ```json { "type": "admin", "id": "507f1f77bcf86cd799439011", "bodyMarkdown": "I'm happy to help! Here's what you need to do...", "messageType": "reply" } ``` ### Example Admin Note (Internal) ```json { "type": "admin", "id": "507f1f77bcf86cd799439011", "bodyMarkdown": "Customer seems frustrated, escalating to tier 2.", "messageType": "note" } ``` ### Example Response ```json { "object": "conversation_part", "id": "3", "partType": "user_msg", "bodyHtml": "Thank you for your help!
", "bodyMarkdown": "Thank you for your help!", "author": { "type": "customer", "id": "676f0f6765bdaa7d7d760f88", "name": "John Doe", "email": "john@example.com" }, "channel": "desktop", "createdAt": "2025-01-15T10:40:00.000Z", "updatedAt": "2025-01-15T10:40:00.000Z" } ``` ### Version Availability This endpoint is only available in API version 2026-01-01.nova and newer. ### Path Parameters - `id: string` Conversation ID (short ID) ### Header Parameters - `"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"` - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Body Parameters - `body: object { bodyMarkdown, messageType, type, 3 more } or object { id, bodyMarkdown, messageType, 2 more }` Reply from a customer or lead - `Contact object { bodyMarkdown, messageType, type, 3 more }` Reply from a customer or lead - `bodyMarkdown: string` The content of the reply message in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored. - `messageType: "reply"` The type of message. Always "reply" for contact replies. - `"reply"` - `type: "contact"` The type of author. Use "contact" for customer/lead replies. - `"contact"` - `id: optional string` The Featurebase contact ID - `skipNotifications: optional boolean` Skip sending notifications (default: false). Useful for bulk imports. - `userId: optional string` The external user ID from your system - `Admin object { id, bodyMarkdown, messageType, 2 more }` Reply or internal note from an admin - `id: string` The Featurebase admin ID - `bodyMarkdown: string` The content of the reply message in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored. - `messageType: "reply" or "note"` The type of message. "reply" is visible to the customer, "note" is an internal note only visible to admins. - `"reply"` - `"note"` - `type: "admin"` The type of author. Use "admin" for admin replies. - `"admin"` - `skipNotifications: optional boolean` Skip sending notifications (default: false). Useful for bulk imports. ### Returns - `ConversationPart = object { id, bodyHtml, bodyMarkdown, 8 more } or object { id, bodyHtml, bodyMarkdown, 8 more } or object { id, bodyHtml, bodyMarkdown, 7 more } or 14 more` Message from a customer or lead - `UserMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Message from a customer or lead - `id: string` Unique part identifier - `bodyHtml: string` Message body content as HTML with signed image URLs - `bodyMarkdown: string` Message body content as markdown - `channel: "unknown" or "desktop" or "android" or 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "user_msg"` User message type - `"user_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `id: string` Author ID - `type: "customer" or "lead" or "admin" or 3 more` Type of author - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `email: optional string` Author email address - `name: optional string` Author display name - `profilePicture: optional string` Author profile picture URL - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `type: "admin" or "customer" or "lead" or 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id: optional string` Actor identifier when available - `name: optional string` Actor display name when available - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `AdminMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Message from an admin or support agent - `id: string` Unique part identifier - `bodyHtml: string` Message body content as HTML with signed image URLs - `bodyMarkdown: string` Message body content as markdown - `channel: "unknown" or "desktop" or "android" or 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_msg"` Admin message type - `"admin_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AdminNote object { id, bodyHtml, bodyMarkdown, 7 more }` Internal note visible only to admins - `id: string` Unique part identifier - `bodyHtml: string` Note body content as HTML with signed image URLs - `bodyMarkdown: string` Note body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_note"` Admin internal note type - `"admin_note"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `EmailMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Message sent via email - `id: string` Unique part identifier - `bodyHtml: string` Email body content as HTML with signed image URLs - `bodyMarkdown: string` Email body content as markdown - `channel: "email"` Email channel - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "email_msg"` Email message type - `"email_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `BotMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Automated message from AI or bot - `id: string` Unique part identifier - `bodyHtml: string` Bot message body content as HTML with signed image URLs - `bodyMarkdown: string` Bot message body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "bot_msg"` Bot message type - `"bot_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `channel: optional "unknown" or "desktop" or "android" or 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyOpts object { id, createdAt, object, 6 more }` Presents options for user to choose from - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_opts"` Quick reply options type - `"quick_reply_opts"` - `replyOptions: array of object { id, text }` Available reply options - `id: string` Option ID - `text: string` Option text - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyResp object { id, bodyHtml, bodyMarkdown, 8 more }` User's selection from quick reply options - `id: string` Unique part identifier - `bodyHtml: string` The selected option text as HTML - `bodyMarkdown: string` The selected option text as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_resp"` Quick reply response type - `"quick_reply_resp"` - `selectedOptionId: string` ID of the selected option - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `RatingRequested object { id, createdAt, csat, 3 more }` Represents a persisted CSAT request in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: object { channel, requestedAt, requestId, 7 more }` Canonical CSAT request payload for this thread event - `channel: "desktop" or "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" or "rated" or "canceled" or "expired"` Status of the CSAT request represented by this part - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt: optional string` ISO timestamp after which changing the rating is no longer allowed - `expiredAt: optional string` ISO timestamp when the request expired, when applicable - `lateSubmitWindowEndsAt: optional string` ISO timestamp after which late submission is no longer allowed - `ratedAgent: optional CsatRatedAgent` - `type: "teammate" or "fibi" or "chatbot"` Type of agent the CSAT request is attributed to - `"teammate"` - `"fibi"` - `"chatbot"` - `id: optional string` Identifier of the rated agent when applicable - `workflow: optional CsatWorkflowLink` - `workflowActionId: optional string` Workflow action ID associated with the CSAT request - `workflowId: optional string` Workflow ID associated with the CSAT request - `workflowRunId: optional string` Workflow run ID associated with the CSAT request - `workflowStepId: optional string` Workflow step ID associated with the CSAT request - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_requested"` CSAT rating requested part type - `"rating_requested"` - `updatedAt: string` ISO timestamp when the part was last updated - `RatingSubmitted object { id, createdAt, csat, 3 more }` Represents a persisted CSAT submission in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: object { channel, ratedAt, requestId, 7 more }` Canonical CSAT submission payload for this thread event - `channel: "desktop" or "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `ratedAt: string` ISO timestamp when the customer submitted the rating - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `score: number` CSAT score from 1 to 5 - `status: "rated"` Submitted ratings are always in the rated state - `"rated"` - `ratedAgent: optional CsatRatedAgent` - `remark: optional string` Optional remark left with the rating - `requestedAt: optional string` ISO timestamp when the request was created - `workflow: optional CsatWorkflowLink` - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_submitted"` CSAT rating submitted part type - `"rating_submitted"` - `updatedAt: string` ISO timestamp when the part was last updated - `AttrPrompt object { id, createdAt, form, 6 more }` Requests information from user via form - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `form: object { id, attributes }` Form configuration - `id: string` Form ID - `attributes: array of object { identifier, name, type }` Form fields - `identifier: string` Field identifier - `name: string` Field display name - `type: string` Field type - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_prompt"` Attribute collection prompt type - `"attr_prompt"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AttrComplete object { id, createdAt, object, 2 more }` Indicates form was completed - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_complete"` Attribute collection complete type - `"attr_complete"` - `updatedAt: string` ISO timestamp when the part was last updated - `Assign object { id, createdAt, object, 5 more }` Conversation assigned to admin or team - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "assign"` Assignment type - `"assign"` - `updatedAt: string` ISO timestamp when the part was last updated - `adminAssigneeId: optional string` ID of the admin assigned to the conversation - `adminAssignerId: optional string` ID of the admin who made the assignment - `teamAssigneeId: optional string` ID of the team assigned to the conversation - `Status object { id, createdAt, object, 4 more }` Conversation state changed (open/closed/snoozed) - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "status"` Status change type - `"status"` - `status: "open" or "closed" or "snoozed"` New conversation status - `"open"` - `"closed"` - `"snoozed"` - `updatedAt: string` ISO timestamp when the part was last updated - `snoozedUntil: optional string` ISO timestamp until conversation is snoozed (if snoozed) - `Tags object { id, action, createdAt, 8 more }` A tag was added to or removed from a specific reply - `id: string` Unique part identifier - `action: "added" or "removed"` Whether the tag was added or removed - `"added"` - `"removed"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `occurredAt: string` ISO timestamp when the tag mutation occurred - `partType: "tags"` Tag update type - `"tags"` - `tagId: string` Identifier of the affected tag - `updatedAt: string` ISO timestamp when the part was last updated - `actor: optional ConversationTagMutationActor` Actor that applied the tag - `tagName: optional string` Tag name at the time of the event or the best available current display name - `targetPartId: optional string` Conversation part that the tag mutation targeted - `WorkflowWait object { id, createdAt, object, 3 more }` Represents a workflow wait start, finish, or interruption in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "workflow_wait"` Workflow wait event part type - `"workflow_wait"` - `updatedAt: string` ISO timestamp when the part was last updated - `workflowWait: object { eventType, occurredAt, interruptedByUserType, 3 more }` Workflow wait event payload for this thread event - `eventType: "started" or "finished" or "interrupted"` Lifecycle stage of the workflow wait event - `"started"` - `"finished"` - `"interrupted"` - `occurredAt: string` ISO timestamp when the wait event occurred - `interruptedByUserType: optional "admin" or "customer" or "lead"` User type that interrupted the wait when applicable - `"admin"` - `"customer"` - `"lead"` - `waitLabel: optional string` Human-readable wait duration or preset label - `workflowId: optional string` Workflow ID associated with the wait event - `workflowName: optional string` Workflow display name at the time of the wait event - `Priority object { id, createdAt, isPriority, 3 more }` Conversation priority was updated - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `isPriority: boolean` Whether the conversation is now marked as priority - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "priority"` Priority change type - `"priority"` - `updatedAt: string` ISO timestamp when the part was last updated - `PartAdd object { id, createdAt, object, 3 more }` New participant joined the conversation - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `participant: object { id, type }` The added participant - `id: string` Participant ID - `type: "customer" or "lead" or "admin"` Participant type - `"customer"` - `"lead"` - `"admin"` - `partType: "part_add"` Participant added type - `"part_add"` - `updatedAt: string` ISO timestamp when the part was last updated ### Example ```http curl https://do.featurebase.app/v2/conversations/$ID/reply \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $FEATUREBASE_API_KEY" \ -d '{ "bodyMarkdown": "Thank you for your help!", "messageType": "reply", "type": "contact", "id": "676f0f6765bdaa7d7d760f88", "userId": "user_123" }' ``` #### Response ```json { "id": "1", "bodyHtml": "Hello, I have a question about your product.
", "bodyMarkdown": "Hello, I have a question about your product.", "channel": "desktop", "createdAt": "2025-01-15T10:30:00.000Z", "object": "conversation_part", "partType": "user_msg", "updatedAt": "2025-01-15T10:30:00.000Z", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/user.png" }, "redacted": false, "tagApplications": [ { "appliedAt": "2025-01-15T10:30:00.000Z", "tagId": "67ec1234abcd5678ef901234", "appliedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "removedAt": "2025-01-15T11:00:00.000Z", "removedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "tag": { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } } ] } ``` ## Redact a conversation part **post** `/v2/conversations/redact` Redacts a conversation part (message) from a conversation. Redaction permanently removes the message content while preserving the conversation structure. Only human message types can be redacted: - `user_msg` - Messages from customers/leads - `admin_msg` - Messages from admins - `email_msg` - Email messages - `bot_msg` - Bot messages System-generated conversation parts (assignments, status changes, etc.) cannot be redacted. ### Request Body | Field | Type | Required | Description | | -------------------- | ------ | -------- | ------------------------------------------------------------------------------ | | `type` | string | Yes | The type of item to redact. Currently only `"conversation_part"` is supported. | | `conversationId` | string | Yes | The conversation short ID containing the part to redact | | `conversationPartId` | string | Yes | The conversation part short ID to redact | | `actingAdminId` | string | No | Admin ID performing the action (for attribution) | ### Response Returns the updated conversation object. ### Example Request ```json { "type": "conversation_part", "conversationId": "12345", "conversationPartId": "67890", "actingAdminId": "507f1f77bcf86cd799439011" } ``` ### Example Response ```json { "object": "conversation", "id": "12345", "conversationParts": [ { "object": "conversation_part", "id": "67890", "partType": "user_msg", "bodyHtml": "", "bodyMarkdown": "", "redacted": true, ... } ], ... } ``` ### Error Cases - **400 Bad Request** - Only human messages can be redacted - **404 Not Found** - Conversation or conversation part not found ### Version Availability This endpoint is only available in API version 2026-01-01.nova and newer. ### Header Parameters - `"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"` - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Body Parameters - `conversationId: string` The conversation short ID that contains the part to redact - `conversationPartId: string` The conversation part short ID to redact - `type: "conversation_part"` The type of item to redact. Currently only "conversation_part" is supported. - `"conversation_part"` - `actingAdminId: optional string` The admin ID performing this action. If not provided, changes are attributed to the system bot user. ### Returns - `Conversation object { id, adminAssigneeId, botConversationStateLastUpdatedAt, 26 more }` - `id: string` Unique conversation identifier - `adminAssigneeId: string` ID of the assigned admin - `botConversationStateLastUpdatedAt: string` ISO timestamp when bot state last changed - `brandId: string` ID of the brand associated with this conversation - `createdAt: string` ISO timestamp when conversation was created - `hasAdminOverriddenLanguage: boolean` Whether an admin has manually overridden the language for this conversation. When true, automatic language detection is disabled. - `isBlocked: boolean` Whether the user is blocked - `lastActivityAt: string` ISO timestamp of last activity - `object: "conversation"` Object type identifier - `"conversation"` - `participants: array of ConversationParticipant` Participants in this conversation - `id: string` Participant ID - `type: "customer" or "lead" or "admin" or 3 more` Type of participant - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `priority: boolean` Whether this conversation is marked as priority - `prioritySetAt: string` ISO timestamp when priority was set - `snoozedUntil: string` ISO timestamp until which conversation is snoozed - `state: "open" or "closed" or "snoozed"` Current state of the conversation - `"open"` - `"closed"` - `"snoozed"` - `tags: array of ConversationTag` Current tags applied anywhere in this conversation - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `teamAssigneeId: string` ID of the assigned team - `updatedAt: string` ISO timestamp when conversation was last updated - `userPreferredLanguage: string` User's preferred language - `waitingSince: string` ISO timestamp when conversation started waiting - `awaitingCustomerReply: optional boolean` Whether we are awaiting a customer reply - `botConversationState: optional "active" or "handed_off_to_human" or "resolved"` State of AI agent handling for this conversation - `"active"` - `"handed_off_to_human"` - `"resolved"` - `conversationParts: optional array of ConversationPart` Array of conversation parts (messages). Only included when fetching a single conversation by ID. - `UserMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Message from a customer or lead - `id: string` Unique part identifier - `bodyHtml: string` Message body content as HTML with signed image URLs - `bodyMarkdown: string` Message body content as markdown - `channel: "unknown" or "desktop" or "android" or 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "user_msg"` User message type - `"user_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `id: string` Author ID - `type: "customer" or "lead" or "admin" or 3 more` Type of author - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `email: optional string` Author email address - `name: optional string` Author display name - `profilePicture: optional string` Author profile picture URL - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `type: "admin" or "customer" or "lead" or 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id: optional string` Actor identifier when available - `name: optional string` Actor display name when available - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `AdminMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Message from an admin or support agent - `id: string` Unique part identifier - `bodyHtml: string` Message body content as HTML with signed image URLs - `bodyMarkdown: string` Message body content as markdown - `channel: "unknown" or "desktop" or "android" or 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_msg"` Admin message type - `"admin_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AdminNote object { id, bodyHtml, bodyMarkdown, 7 more }` Internal note visible only to admins - `id: string` Unique part identifier - `bodyHtml: string` Note body content as HTML with signed image URLs - `bodyMarkdown: string` Note body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_note"` Admin internal note type - `"admin_note"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `EmailMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Message sent via email - `id: string` Unique part identifier - `bodyHtml: string` Email body content as HTML with signed image URLs - `bodyMarkdown: string` Email body content as markdown - `channel: "email"` Email channel - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "email_msg"` Email message type - `"email_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `BotMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Automated message from AI or bot - `id: string` Unique part identifier - `bodyHtml: string` Bot message body content as HTML with signed image URLs - `bodyMarkdown: string` Bot message body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "bot_msg"` Bot message type - `"bot_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `channel: optional "unknown" or "desktop" or "android" or 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyOpts object { id, createdAt, object, 6 more }` Presents options for user to choose from - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_opts"` Quick reply options type - `"quick_reply_opts"` - `replyOptions: array of object { id, text }` Available reply options - `id: string` Option ID - `text: string` Option text - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyResp object { id, bodyHtml, bodyMarkdown, 8 more }` User's selection from quick reply options - `id: string` Unique part identifier - `bodyHtml: string` The selected option text as HTML - `bodyMarkdown: string` The selected option text as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_resp"` Quick reply response type - `"quick_reply_resp"` - `selectedOptionId: string` ID of the selected option - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `RatingRequested object { id, createdAt, csat, 3 more }` Represents a persisted CSAT request in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: object { channel, requestedAt, requestId, 7 more }` Canonical CSAT request payload for this thread event - `channel: "desktop" or "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" or "rated" or "canceled" or "expired"` Status of the CSAT request represented by this part - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt: optional string` ISO timestamp after which changing the rating is no longer allowed - `expiredAt: optional string` ISO timestamp when the request expired, when applicable - `lateSubmitWindowEndsAt: optional string` ISO timestamp after which late submission is no longer allowed - `ratedAgent: optional CsatRatedAgent` - `type: "teammate" or "fibi" or "chatbot"` Type of agent the CSAT request is attributed to - `"teammate"` - `"fibi"` - `"chatbot"` - `id: optional string` Identifier of the rated agent when applicable - `workflow: optional CsatWorkflowLink` - `workflowActionId: optional string` Workflow action ID associated with the CSAT request - `workflowId: optional string` Workflow ID associated with the CSAT request - `workflowRunId: optional string` Workflow run ID associated with the CSAT request - `workflowStepId: optional string` Workflow step ID associated with the CSAT request - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_requested"` CSAT rating requested part type - `"rating_requested"` - `updatedAt: string` ISO timestamp when the part was last updated - `RatingSubmitted object { id, createdAt, csat, 3 more }` Represents a persisted CSAT submission in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: object { channel, ratedAt, requestId, 7 more }` Canonical CSAT submission payload for this thread event - `channel: "desktop" or "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `ratedAt: string` ISO timestamp when the customer submitted the rating - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `score: number` CSAT score from 1 to 5 - `status: "rated"` Submitted ratings are always in the rated state - `"rated"` - `ratedAgent: optional CsatRatedAgent` - `remark: optional string` Optional remark left with the rating - `requestedAt: optional string` ISO timestamp when the request was created - `workflow: optional CsatWorkflowLink` - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_submitted"` CSAT rating submitted part type - `"rating_submitted"` - `updatedAt: string` ISO timestamp when the part was last updated - `AttrPrompt object { id, createdAt, form, 6 more }` Requests information from user via form - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `form: object { id, attributes }` Form configuration - `id: string` Form ID - `attributes: array of object { identifier, name, type }` Form fields - `identifier: string` Field identifier - `name: string` Field display name - `type: string` Field type - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_prompt"` Attribute collection prompt type - `"attr_prompt"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AttrComplete object { id, createdAt, object, 2 more }` Indicates form was completed - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_complete"` Attribute collection complete type - `"attr_complete"` - `updatedAt: string` ISO timestamp when the part was last updated - `Assign object { id, createdAt, object, 5 more }` Conversation assigned to admin or team - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "assign"` Assignment type - `"assign"` - `updatedAt: string` ISO timestamp when the part was last updated - `adminAssigneeId: optional string` ID of the admin assigned to the conversation - `adminAssignerId: optional string` ID of the admin who made the assignment - `teamAssigneeId: optional string` ID of the team assigned to the conversation - `Status object { id, createdAt, object, 4 more }` Conversation state changed (open/closed/snoozed) - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "status"` Status change type - `"status"` - `status: "open" or "closed" or "snoozed"` New conversation status - `"open"` - `"closed"` - `"snoozed"` - `updatedAt: string` ISO timestamp when the part was last updated - `snoozedUntil: optional string` ISO timestamp until conversation is snoozed (if snoozed) - `Tags object { id, action, createdAt, 8 more }` A tag was added to or removed from a specific reply - `id: string` Unique part identifier - `action: "added" or "removed"` Whether the tag was added or removed - `"added"` - `"removed"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `occurredAt: string` ISO timestamp when the tag mutation occurred - `partType: "tags"` Tag update type - `"tags"` - `tagId: string` Identifier of the affected tag - `updatedAt: string` ISO timestamp when the part was last updated - `actor: optional ConversationTagMutationActor` Actor that applied the tag - `tagName: optional string` Tag name at the time of the event or the best available current display name - `targetPartId: optional string` Conversation part that the tag mutation targeted - `WorkflowWait object { id, createdAt, object, 3 more }` Represents a workflow wait start, finish, or interruption in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "workflow_wait"` Workflow wait event part type - `"workflow_wait"` - `updatedAt: string` ISO timestamp when the part was last updated - `workflowWait: object { eventType, occurredAt, interruptedByUserType, 3 more }` Workflow wait event payload for this thread event - `eventType: "started" or "finished" or "interrupted"` Lifecycle stage of the workflow wait event - `"started"` - `"finished"` - `"interrupted"` - `occurredAt: string` ISO timestamp when the wait event occurred - `interruptedByUserType: optional "admin" or "customer" or "lead"` User type that interrupted the wait when applicable - `"admin"` - `"customer"` - `"lead"` - `waitLabel: optional string` Human-readable wait duration or preset label - `workflowId: optional string` Workflow ID associated with the wait event - `workflowName: optional string` Workflow display name at the time of the wait event - `Priority object { id, createdAt, isPriority, 3 more }` Conversation priority was updated - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `isPriority: boolean` Whether the conversation is now marked as priority - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "priority"` Priority change type - `"priority"` - `updatedAt: string` ISO timestamp when the part was last updated - `PartAdd object { id, createdAt, object, 3 more }` New participant joined the conversation - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `participant: object { id, type }` The added participant - `id: string` Participant ID - `type: "customer" or "lead" or "admin"` Participant type - `"customer"` - `"lead"` - `"admin"` - `partType: "part_add"` Participant added type - `"part_add"` - `updatedAt: string` ISO timestamp when the part was last updated - `csatDebug: optional object { requestId, status, changeLockWindowEndsAt, 2 more }` Minimal CSAT diagnostics for the current effective request. - `requestId: string` Canonical CSAT request ID used for the latest debug snapshot - `status: "pending" or "rated" or "canceled" or "expired"` Lifecycle status of the request represented in the debug snapshot - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt: optional string` ISO timestamp when rating edits stop being accepted - `emailDelivery: optional CsatEmailDelivery` - `status: "pending" or "sent" or "failed"` Email delivery status for the CSAT request when applicable - `"pending"` - `"sent"` - `"failed"` - `failedAt: optional string` ISO timestamp when the CSAT email failed - `failureReason: optional string` Operational failure reason for the CSAT email delivery - `messageId: optional string` Email message ID associated with delivery - `sentAt: optional string` ISO timestamp when the CSAT email was sent - `lateSubmitWindowEndsAt: optional string` ISO timestamp when first-time submissions stop being accepted - `csatHistory: optional array of object { channel, isLatestEffective, lastUpdatedAt, 14 more }` Historical CSAT requests for this conversation, ordered newest first. - `channel: "desktop" or "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `isLatestEffective: boolean` Whether this row represents the currently effective CSAT request for the conversation - `lastUpdatedAt: string` ISO timestamp when the request last changed - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" or "rated" or "canceled" or "expired"` Lifecycle status for this historical CSAT request - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt: optional string` ISO timestamp when the request was canceled - `changeLockWindowEndsAt: optional string` ISO timestamp when edits to an existing rating stop being accepted - `emailDelivery: optional CsatEmailDelivery` - `expiredAt: optional string` ISO timestamp when the request expired - `lateSubmitWindowEndsAt: optional string` ISO timestamp when first-time submissions stop being accepted - `ratedAgent: optional CsatRatedAgent` - `ratedAt: optional string` ISO timestamp when the request was rated - `remark: optional string` Submitted remark when present - `score: optional number` Submitted score when this request was rated - `workflow: optional CsatWorkflowLink` - `csatSummary: optional object { lastUpdatedAt, status, canceledAt, 10 more }` Derived CSAT summary for this conversation when a rating request or rating exists. - `lastUpdatedAt: string` ISO timestamp when the summary last changed - `status: "pending" or "rated" or "canceled" or "expired"` Current summary status for CSAT on this conversation - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt: optional string` ISO timestamp when the request was canceled - `channel: optional "desktop" or "email"` Channel used for the latest CSAT request when known - `"desktop"` - `"email"` - `expiredAt: optional string` ISO timestamp when the request expired - `ratedAgent: optional CsatRatedAgent` - `ratedAt: optional string` ISO timestamp when the customer submitted a rating - `remark: optional string` Optional remark left with the rating - `requestedAt: optional string` ISO timestamp when the latest CSAT request was created - `requestId: optional string` Canonical CSAT request ID - `requestSource: optional "workflow"` Source of the latest CSAT request when known - `"workflow"` - `score: optional number` CSAT score from 1 to 5 when rated - `workflow: optional CsatWorkflowLink` - `disableCustomerReply: optional boolean` Whether customer replies are disabled - `readReceipts: optional array of object { id, lastReadPartId, userType }` Read receipts indicating how far each participant has read in the conversation. Each receipt maps a user to their last-read conversation part. The tracked position reflects the system read state and may reference parts the user cannot directly view (e.g., a contact's read position may point to an internal admin note). Use these receipts to render read indicators and typing awareness, not to infer content access. - `id: string` The internal ID of the user - `lastReadPartId: string` The ID of the last conversation part this user has read. Note: This reflects the system-tracked read position and may reference a part the user cannot directly access (e.g., internal notes for contacts). The read state is advanced to the latest part in the conversation regardless of part visibility. - `userType: "admin" or "customer" or "lead"` Type of user who has read the conversation - `"admin"` - `"customer"` - `"lead"` - `source: optional object { bodyHtml, bodyMarkdown, channel, 4 more }` - `bodyHtml: string` Body of the initial message as HTML with signed image URLs - `bodyMarkdown: string` Body of the initial message as markdown - `channel: "unknown" or "desktop" or "android" or 2 more` Channel through which the conversation was initiated - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `author: optional ConversationParticipant` - `id: string` Participant ID - `type: "customer" or "lead" or "admin" or 3 more` Type of participant - `deliveredAs: optional "customer_initiated" or "admin_initiated"` How the conversation was initiated - `"customer_initiated"` - `"admin_initiated"` - `subject: optional string` Subject line for email conversations - `url: optional string` URL where the conversation was initiated - `title: optional string` Conversation title ### Example ```http curl https://do.featurebase.app/v2/conversations/redact \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $FEATUREBASE_API_KEY" \ -d '{ "conversationId": "12345", "conversationPartId": "67890", "type": "conversation_part", "actingAdminId": "507f1f77bcf86cd799439011" }' ``` #### Response ```json { "id": "12345", "adminAssigneeId": "507f1f77bcf86cd799439011", "botConversationStateLastUpdatedAt": "2025-01-15T10:30:00.000Z", "brandId": "507f1f77bcf86cd799439011", "createdAt": "2025-01-15T10:30:00.000Z", "hasAdminOverriddenLanguage": false, "isBlocked": false, "lastActivityAt": "2025-01-15T12:30:00.000Z", "object": "conversation", "participants": [ { "id": "676f0f6765bdaa7d7d760f88", "type": "customer" } ], "priority": false, "prioritySetAt": "2025-01-15T10:30:00.000Z", "snoozedUntil": "2025-01-16T09:00:00.000Z", "state": "open", "tags": [ { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } ], "teamAssigneeId": "507f1f77bcf86cd799439012", "updatedAt": "2025-01-15T12:30:00.000Z", "userPreferredLanguage": "en", "waitingSince": "2025-01-15T10:30:00.000Z", "awaitingCustomerReply": true, "botConversationState": "active", "conversationParts": [ { "id": "1", "bodyHtml": "Hello, I have a question about your product.
", "bodyMarkdown": "Hello, I have a question about your product.", "channel": "desktop", "createdAt": "2025-01-15T10:30:00.000Z", "object": "conversation_part", "partType": "user_msg", "updatedAt": "2025-01-15T10:30:00.000Z", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/user.png" }, "redacted": false, "tagApplications": [ { "appliedAt": "2025-01-15T10:30:00.000Z", "tagId": "67ec1234abcd5678ef901234", "appliedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "removedAt": "2025-01-15T11:00:00.000Z", "removedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "tag": { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } } ] } ], "csatDebug": { "requestId": "csat_req_123", "status": "pending", "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z", "emailDelivery": { "status": "failed", "failedAt": "2025-01-15T10:31:00.000Z", "failureReason": "smtp_bounce", "messageId": "msg_123", "sentAt": "2025-01-15T10:31:00.000Z" }, "lateSubmitWindowEndsAt": "2025-01-16T10:30:00.000Z" }, "csatHistory": [ { "channel": "desktop", "isLatestEffective": true, "lastUpdatedAt": "2025-01-15T10:35:00.000Z", "requestedAt": "2025-01-15T10:30:00.000Z", "requestId": "csat_req_123", "requestSource": "workflow", "status": "pending", "canceledAt": "2025-01-15T10:32:00.000Z", "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z", "emailDelivery": { "status": "failed", "failedAt": "2025-01-15T10:31:00.000Z", "failureReason": "smtp_bounce", "messageId": "msg_123", "sentAt": "2025-01-15T10:31:00.000Z" }, "expiredAt": "2025-01-16T10:30:00.000Z", "lateSubmitWindowEndsAt": "2025-01-16T10:30:00.000Z", "ratedAgent": { "type": "teammate", "id": "507f1f77bcf86cd799439011" }, "ratedAt": "2025-01-15T10:35:00.000Z", "remark": "Thanks for the quick help.", "score": 4, "workflow": { "workflowActionId": "action_123", "workflowId": "507f1f77bcf86cd799439011", "workflowRunId": "run_123", "workflowStepId": "step_123" } } ], "csatSummary": { "lastUpdatedAt": "2025-01-15T10:35:00.000Z", "status": "pending", "canceledAt": "2025-01-15T10:35:00.000Z", "channel": "desktop", "expiredAt": "2025-01-15T10:35:00.000Z", "ratedAgent": { "type": "teammate", "id": "507f1f77bcf86cd799439011" }, "ratedAt": "2025-01-15T10:35:00.000Z", "remark": "Very helpful support.", "requestedAt": "2025-01-15T10:30:00.000Z", "requestId": "csat_req_123", "requestSource": "workflow", "score": 5, "workflow": { "workflowActionId": "action_123", "workflowId": "507f1f77bcf86cd799439011", "workflowRunId": "run_123", "workflowStepId": "step_123" } }, "disableCustomerReply": false, "readReceipts": [ { "id": "507f1f77bcf86cd799439011", "lastReadPartId": "8", "userType": "admin" } ], "source": { "bodyHtml": "Hi, I have a question about your enterprise plan...
", "bodyMarkdown": "Hi, I have a question about your enterprise plan...", "channel": "desktop", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer" }, "deliveredAs": "customer_initiated", "subject": "Question about pricing", "url": "https://example.com/pricing" }, "title": "Question about pricing" } ``` ## Domain Types ### Conversation - `Conversation object { id, adminAssigneeId, botConversationStateLastUpdatedAt, 26 more }` - `id: string` Unique conversation identifier - `adminAssigneeId: string` ID of the assigned admin - `botConversationStateLastUpdatedAt: string` ISO timestamp when bot state last changed - `brandId: string` ID of the brand associated with this conversation - `createdAt: string` ISO timestamp when conversation was created - `hasAdminOverriddenLanguage: boolean` Whether an admin has manually overridden the language for this conversation. When true, automatic language detection is disabled. - `isBlocked: boolean` Whether the user is blocked - `lastActivityAt: string` ISO timestamp of last activity - `object: "conversation"` Object type identifier - `"conversation"` - `participants: array of ConversationParticipant` Participants in this conversation - `id: string` Participant ID - `type: "customer" or "lead" or "admin" or 3 more` Type of participant - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `priority: boolean` Whether this conversation is marked as priority - `prioritySetAt: string` ISO timestamp when priority was set - `snoozedUntil: string` ISO timestamp until which conversation is snoozed - `state: "open" or "closed" or "snoozed"` Current state of the conversation - `"open"` - `"closed"` - `"snoozed"` - `tags: array of ConversationTag` Current tags applied anywhere in this conversation - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `teamAssigneeId: string` ID of the assigned team - `updatedAt: string` ISO timestamp when conversation was last updated - `userPreferredLanguage: string` User's preferred language - `waitingSince: string` ISO timestamp when conversation started waiting - `awaitingCustomerReply: optional boolean` Whether we are awaiting a customer reply - `botConversationState: optional "active" or "handed_off_to_human" or "resolved"` State of AI agent handling for this conversation - `"active"` - `"handed_off_to_human"` - `"resolved"` - `conversationParts: optional array of ConversationPart` Array of conversation parts (messages). Only included when fetching a single conversation by ID. - `UserMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Message from a customer or lead - `id: string` Unique part identifier - `bodyHtml: string` Message body content as HTML with signed image URLs - `bodyMarkdown: string` Message body content as markdown - `channel: "unknown" or "desktop" or "android" or 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "user_msg"` User message type - `"user_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `id: string` Author ID - `type: "customer" or "lead" or "admin" or 3 more` Type of author - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `email: optional string` Author email address - `name: optional string` Author display name - `profilePicture: optional string` Author profile picture URL - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `type: "admin" or "customer" or "lead" or 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id: optional string` Actor identifier when available - `name: optional string` Actor display name when available - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `AdminMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Message from an admin or support agent - `id: string` Unique part identifier - `bodyHtml: string` Message body content as HTML with signed image URLs - `bodyMarkdown: string` Message body content as markdown - `channel: "unknown" or "desktop" or "android" or 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_msg"` Admin message type - `"admin_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AdminNote object { id, bodyHtml, bodyMarkdown, 7 more }` Internal note visible only to admins - `id: string` Unique part identifier - `bodyHtml: string` Note body content as HTML with signed image URLs - `bodyMarkdown: string` Note body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_note"` Admin internal note type - `"admin_note"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `EmailMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Message sent via email - `id: string` Unique part identifier - `bodyHtml: string` Email body content as HTML with signed image URLs - `bodyMarkdown: string` Email body content as markdown - `channel: "email"` Email channel - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "email_msg"` Email message type - `"email_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `BotMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Automated message from AI or bot - `id: string` Unique part identifier - `bodyHtml: string` Bot message body content as HTML with signed image URLs - `bodyMarkdown: string` Bot message body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "bot_msg"` Bot message type - `"bot_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `channel: optional "unknown" or "desktop" or "android" or 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyOpts object { id, createdAt, object, 6 more }` Presents options for user to choose from - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_opts"` Quick reply options type - `"quick_reply_opts"` - `replyOptions: array of object { id, text }` Available reply options - `id: string` Option ID - `text: string` Option text - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyResp object { id, bodyHtml, bodyMarkdown, 8 more }` User's selection from quick reply options - `id: string` Unique part identifier - `bodyHtml: string` The selected option text as HTML - `bodyMarkdown: string` The selected option text as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_resp"` Quick reply response type - `"quick_reply_resp"` - `selectedOptionId: string` ID of the selected option - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `RatingRequested object { id, createdAt, csat, 3 more }` Represents a persisted CSAT request in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: object { channel, requestedAt, requestId, 7 more }` Canonical CSAT request payload for this thread event - `channel: "desktop" or "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" or "rated" or "canceled" or "expired"` Status of the CSAT request represented by this part - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt: optional string` ISO timestamp after which changing the rating is no longer allowed - `expiredAt: optional string` ISO timestamp when the request expired, when applicable - `lateSubmitWindowEndsAt: optional string` ISO timestamp after which late submission is no longer allowed - `ratedAgent: optional CsatRatedAgent` - `type: "teammate" or "fibi" or "chatbot"` Type of agent the CSAT request is attributed to - `"teammate"` - `"fibi"` - `"chatbot"` - `id: optional string` Identifier of the rated agent when applicable - `workflow: optional CsatWorkflowLink` - `workflowActionId: optional string` Workflow action ID associated with the CSAT request - `workflowId: optional string` Workflow ID associated with the CSAT request - `workflowRunId: optional string` Workflow run ID associated with the CSAT request - `workflowStepId: optional string` Workflow step ID associated with the CSAT request - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_requested"` CSAT rating requested part type - `"rating_requested"` - `updatedAt: string` ISO timestamp when the part was last updated - `RatingSubmitted object { id, createdAt, csat, 3 more }` Represents a persisted CSAT submission in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: object { channel, ratedAt, requestId, 7 more }` Canonical CSAT submission payload for this thread event - `channel: "desktop" or "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `ratedAt: string` ISO timestamp when the customer submitted the rating - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `score: number` CSAT score from 1 to 5 - `status: "rated"` Submitted ratings are always in the rated state - `"rated"` - `ratedAgent: optional CsatRatedAgent` - `remark: optional string` Optional remark left with the rating - `requestedAt: optional string` ISO timestamp when the request was created - `workflow: optional CsatWorkflowLink` - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_submitted"` CSAT rating submitted part type - `"rating_submitted"` - `updatedAt: string` ISO timestamp when the part was last updated - `AttrPrompt object { id, createdAt, form, 6 more }` Requests information from user via form - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `form: object { id, attributes }` Form configuration - `id: string` Form ID - `attributes: array of object { identifier, name, type }` Form fields - `identifier: string` Field identifier - `name: string` Field display name - `type: string` Field type - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_prompt"` Attribute collection prompt type - `"attr_prompt"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AttrComplete object { id, createdAt, object, 2 more }` Indicates form was completed - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_complete"` Attribute collection complete type - `"attr_complete"` - `updatedAt: string` ISO timestamp when the part was last updated - `Assign object { id, createdAt, object, 5 more }` Conversation assigned to admin or team - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "assign"` Assignment type - `"assign"` - `updatedAt: string` ISO timestamp when the part was last updated - `adminAssigneeId: optional string` ID of the admin assigned to the conversation - `adminAssignerId: optional string` ID of the admin who made the assignment - `teamAssigneeId: optional string` ID of the team assigned to the conversation - `Status object { id, createdAt, object, 4 more }` Conversation state changed (open/closed/snoozed) - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "status"` Status change type - `"status"` - `status: "open" or "closed" or "snoozed"` New conversation status - `"open"` - `"closed"` - `"snoozed"` - `updatedAt: string` ISO timestamp when the part was last updated - `snoozedUntil: optional string` ISO timestamp until conversation is snoozed (if snoozed) - `Tags object { id, action, createdAt, 8 more }` A tag was added to or removed from a specific reply - `id: string` Unique part identifier - `action: "added" or "removed"` Whether the tag was added or removed - `"added"` - `"removed"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `occurredAt: string` ISO timestamp when the tag mutation occurred - `partType: "tags"` Tag update type - `"tags"` - `tagId: string` Identifier of the affected tag - `updatedAt: string` ISO timestamp when the part was last updated - `actor: optional ConversationTagMutationActor` Actor that applied the tag - `tagName: optional string` Tag name at the time of the event or the best available current display name - `targetPartId: optional string` Conversation part that the tag mutation targeted - `WorkflowWait object { id, createdAt, object, 3 more }` Represents a workflow wait start, finish, or interruption in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "workflow_wait"` Workflow wait event part type - `"workflow_wait"` - `updatedAt: string` ISO timestamp when the part was last updated - `workflowWait: object { eventType, occurredAt, interruptedByUserType, 3 more }` Workflow wait event payload for this thread event - `eventType: "started" or "finished" or "interrupted"` Lifecycle stage of the workflow wait event - `"started"` - `"finished"` - `"interrupted"` - `occurredAt: string` ISO timestamp when the wait event occurred - `interruptedByUserType: optional "admin" or "customer" or "lead"` User type that interrupted the wait when applicable - `"admin"` - `"customer"` - `"lead"` - `waitLabel: optional string` Human-readable wait duration or preset label - `workflowId: optional string` Workflow ID associated with the wait event - `workflowName: optional string` Workflow display name at the time of the wait event - `Priority object { id, createdAt, isPriority, 3 more }` Conversation priority was updated - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `isPriority: boolean` Whether the conversation is now marked as priority - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "priority"` Priority change type - `"priority"` - `updatedAt: string` ISO timestamp when the part was last updated - `PartAdd object { id, createdAt, object, 3 more }` New participant joined the conversation - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `participant: object { id, type }` The added participant - `id: string` Participant ID - `type: "customer" or "lead" or "admin"` Participant type - `"customer"` - `"lead"` - `"admin"` - `partType: "part_add"` Participant added type - `"part_add"` - `updatedAt: string` ISO timestamp when the part was last updated - `csatDebug: optional object { requestId, status, changeLockWindowEndsAt, 2 more }` Minimal CSAT diagnostics for the current effective request. - `requestId: string` Canonical CSAT request ID used for the latest debug snapshot - `status: "pending" or "rated" or "canceled" or "expired"` Lifecycle status of the request represented in the debug snapshot - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt: optional string` ISO timestamp when rating edits stop being accepted - `emailDelivery: optional CsatEmailDelivery` - `status: "pending" or "sent" or "failed"` Email delivery status for the CSAT request when applicable - `"pending"` - `"sent"` - `"failed"` - `failedAt: optional string` ISO timestamp when the CSAT email failed - `failureReason: optional string` Operational failure reason for the CSAT email delivery - `messageId: optional string` Email message ID associated with delivery - `sentAt: optional string` ISO timestamp when the CSAT email was sent - `lateSubmitWindowEndsAt: optional string` ISO timestamp when first-time submissions stop being accepted - `csatHistory: optional array of object { channel, isLatestEffective, lastUpdatedAt, 14 more }` Historical CSAT requests for this conversation, ordered newest first. - `channel: "desktop" or "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `isLatestEffective: boolean` Whether this row represents the currently effective CSAT request for the conversation - `lastUpdatedAt: string` ISO timestamp when the request last changed - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" or "rated" or "canceled" or "expired"` Lifecycle status for this historical CSAT request - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt: optional string` ISO timestamp when the request was canceled - `changeLockWindowEndsAt: optional string` ISO timestamp when edits to an existing rating stop being accepted - `emailDelivery: optional CsatEmailDelivery` - `expiredAt: optional string` ISO timestamp when the request expired - `lateSubmitWindowEndsAt: optional string` ISO timestamp when first-time submissions stop being accepted - `ratedAgent: optional CsatRatedAgent` - `ratedAt: optional string` ISO timestamp when the request was rated - `remark: optional string` Submitted remark when present - `score: optional number` Submitted score when this request was rated - `workflow: optional CsatWorkflowLink` - `csatSummary: optional object { lastUpdatedAt, status, canceledAt, 10 more }` Derived CSAT summary for this conversation when a rating request or rating exists. - `lastUpdatedAt: string` ISO timestamp when the summary last changed - `status: "pending" or "rated" or "canceled" or "expired"` Current summary status for CSAT on this conversation - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt: optional string` ISO timestamp when the request was canceled - `channel: optional "desktop" or "email"` Channel used for the latest CSAT request when known - `"desktop"` - `"email"` - `expiredAt: optional string` ISO timestamp when the request expired - `ratedAgent: optional CsatRatedAgent` - `ratedAt: optional string` ISO timestamp when the customer submitted a rating - `remark: optional string` Optional remark left with the rating - `requestedAt: optional string` ISO timestamp when the latest CSAT request was created - `requestId: optional string` Canonical CSAT request ID - `requestSource: optional "workflow"` Source of the latest CSAT request when known - `"workflow"` - `score: optional number` CSAT score from 1 to 5 when rated - `workflow: optional CsatWorkflowLink` - `disableCustomerReply: optional boolean` Whether customer replies are disabled - `readReceipts: optional array of object { id, lastReadPartId, userType }` Read receipts indicating how far each participant has read in the conversation. Each receipt maps a user to their last-read conversation part. The tracked position reflects the system read state and may reference parts the user cannot directly view (e.g., a contact's read position may point to an internal admin note). Use these receipts to render read indicators and typing awareness, not to infer content access. - `id: string` The internal ID of the user - `lastReadPartId: string` The ID of the last conversation part this user has read. Note: This reflects the system-tracked read position and may reference a part the user cannot directly access (e.g., internal notes for contacts). The read state is advanced to the latest part in the conversation regardless of part visibility. - `userType: "admin" or "customer" or "lead"` Type of user who has read the conversation - `"admin"` - `"customer"` - `"lead"` - `source: optional object { bodyHtml, bodyMarkdown, channel, 4 more }` - `bodyHtml: string` Body of the initial message as HTML with signed image URLs - `bodyMarkdown: string` Body of the initial message as markdown - `channel: "unknown" or "desktop" or "android" or 2 more` Channel through which the conversation was initiated - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `author: optional ConversationParticipant` - `id: string` Participant ID - `type: "customer" or "lead" or "admin" or 3 more` Type of participant - `deliveredAs: optional "customer_initiated" or "admin_initiated"` How the conversation was initiated - `"customer_initiated"` - `"admin_initiated"` - `subject: optional string` Subject line for email conversations - `url: optional string` URL where the conversation was initiated - `title: optional string` Conversation title ### Conversation Part - `ConversationPart = object { id, bodyHtml, bodyMarkdown, 8 more } or object { id, bodyHtml, bodyMarkdown, 8 more } or object { id, bodyHtml, bodyMarkdown, 7 more } or 14 more` Message from a customer or lead - `UserMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Message from a customer or lead - `id: string` Unique part identifier - `bodyHtml: string` Message body content as HTML with signed image URLs - `bodyMarkdown: string` Message body content as markdown - `channel: "unknown" or "desktop" or "android" or 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "user_msg"` User message type - `"user_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `id: string` Author ID - `type: "customer" or "lead" or "admin" or 3 more` Type of author - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `email: optional string` Author email address - `name: optional string` Author display name - `profilePicture: optional string` Author profile picture URL - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `type: "admin" or "customer" or "lead" or 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id: optional string` Actor identifier when available - `name: optional string` Actor display name when available - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `AdminMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Message from an admin or support agent - `id: string` Unique part identifier - `bodyHtml: string` Message body content as HTML with signed image URLs - `bodyMarkdown: string` Message body content as markdown - `channel: "unknown" or "desktop" or "android" or 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_msg"` Admin message type - `"admin_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AdminNote object { id, bodyHtml, bodyMarkdown, 7 more }` Internal note visible only to admins - `id: string` Unique part identifier - `bodyHtml: string` Note body content as HTML with signed image URLs - `bodyMarkdown: string` Note body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_note"` Admin internal note type - `"admin_note"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `EmailMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Message sent via email - `id: string` Unique part identifier - `bodyHtml: string` Email body content as HTML with signed image URLs - `bodyMarkdown: string` Email body content as markdown - `channel: "email"` Email channel - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "email_msg"` Email message type - `"email_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `BotMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Automated message from AI or bot - `id: string` Unique part identifier - `bodyHtml: string` Bot message body content as HTML with signed image URLs - `bodyMarkdown: string` Bot message body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "bot_msg"` Bot message type - `"bot_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `channel: optional "unknown" or "desktop" or "android" or 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyOpts object { id, createdAt, object, 6 more }` Presents options for user to choose from - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_opts"` Quick reply options type - `"quick_reply_opts"` - `replyOptions: array of object { id, text }` Available reply options - `id: string` Option ID - `text: string` Option text - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyResp object { id, bodyHtml, bodyMarkdown, 8 more }` User's selection from quick reply options - `id: string` Unique part identifier - `bodyHtml: string` The selected option text as HTML - `bodyMarkdown: string` The selected option text as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_resp"` Quick reply response type - `"quick_reply_resp"` - `selectedOptionId: string` ID of the selected option - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `RatingRequested object { id, createdAt, csat, 3 more }` Represents a persisted CSAT request in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: object { channel, requestedAt, requestId, 7 more }` Canonical CSAT request payload for this thread event - `channel: "desktop" or "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" or "rated" or "canceled" or "expired"` Status of the CSAT request represented by this part - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt: optional string` ISO timestamp after which changing the rating is no longer allowed - `expiredAt: optional string` ISO timestamp when the request expired, when applicable - `lateSubmitWindowEndsAt: optional string` ISO timestamp after which late submission is no longer allowed - `ratedAgent: optional CsatRatedAgent` - `type: "teammate" or "fibi" or "chatbot"` Type of agent the CSAT request is attributed to - `"teammate"` - `"fibi"` - `"chatbot"` - `id: optional string` Identifier of the rated agent when applicable - `workflow: optional CsatWorkflowLink` - `workflowActionId: optional string` Workflow action ID associated with the CSAT request - `workflowId: optional string` Workflow ID associated with the CSAT request - `workflowRunId: optional string` Workflow run ID associated with the CSAT request - `workflowStepId: optional string` Workflow step ID associated with the CSAT request - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_requested"` CSAT rating requested part type - `"rating_requested"` - `updatedAt: string` ISO timestamp when the part was last updated - `RatingSubmitted object { id, createdAt, csat, 3 more }` Represents a persisted CSAT submission in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: object { channel, ratedAt, requestId, 7 more }` Canonical CSAT submission payload for this thread event - `channel: "desktop" or "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `ratedAt: string` ISO timestamp when the customer submitted the rating - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `score: number` CSAT score from 1 to 5 - `status: "rated"` Submitted ratings are always in the rated state - `"rated"` - `ratedAgent: optional CsatRatedAgent` - `remark: optional string` Optional remark left with the rating - `requestedAt: optional string` ISO timestamp when the request was created - `workflow: optional CsatWorkflowLink` - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_submitted"` CSAT rating submitted part type - `"rating_submitted"` - `updatedAt: string` ISO timestamp when the part was last updated - `AttrPrompt object { id, createdAt, form, 6 more }` Requests information from user via form - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `form: object { id, attributes }` Form configuration - `id: string` Form ID - `attributes: array of object { identifier, name, type }` Form fields - `identifier: string` Field identifier - `name: string` Field display name - `type: string` Field type - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_prompt"` Attribute collection prompt type - `"attr_prompt"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AttrComplete object { id, createdAt, object, 2 more }` Indicates form was completed - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_complete"` Attribute collection complete type - `"attr_complete"` - `updatedAt: string` ISO timestamp when the part was last updated - `Assign object { id, createdAt, object, 5 more }` Conversation assigned to admin or team - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "assign"` Assignment type - `"assign"` - `updatedAt: string` ISO timestamp when the part was last updated - `adminAssigneeId: optional string` ID of the admin assigned to the conversation - `adminAssignerId: optional string` ID of the admin who made the assignment - `teamAssigneeId: optional string` ID of the team assigned to the conversation - `Status object { id, createdAt, object, 4 more }` Conversation state changed (open/closed/snoozed) - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "status"` Status change type - `"status"` - `status: "open" or "closed" or "snoozed"` New conversation status - `"open"` - `"closed"` - `"snoozed"` - `updatedAt: string` ISO timestamp when the part was last updated - `snoozedUntil: optional string` ISO timestamp until conversation is snoozed (if snoozed) - `Tags object { id, action, createdAt, 8 more }` A tag was added to or removed from a specific reply - `id: string` Unique part identifier - `action: "added" or "removed"` Whether the tag was added or removed - `"added"` - `"removed"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `occurredAt: string` ISO timestamp when the tag mutation occurred - `partType: "tags"` Tag update type - `"tags"` - `tagId: string` Identifier of the affected tag - `updatedAt: string` ISO timestamp when the part was last updated - `actor: optional ConversationTagMutationActor` Actor that applied the tag - `tagName: optional string` Tag name at the time of the event or the best available current display name - `targetPartId: optional string` Conversation part that the tag mutation targeted - `WorkflowWait object { id, createdAt, object, 3 more }` Represents a workflow wait start, finish, or interruption in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "workflow_wait"` Workflow wait event part type - `"workflow_wait"` - `updatedAt: string` ISO timestamp when the part was last updated - `workflowWait: object { eventType, occurredAt, interruptedByUserType, 3 more }` Workflow wait event payload for this thread event - `eventType: "started" or "finished" or "interrupted"` Lifecycle stage of the workflow wait event - `"started"` - `"finished"` - `"interrupted"` - `occurredAt: string` ISO timestamp when the wait event occurred - `interruptedByUserType: optional "admin" or "customer" or "lead"` User type that interrupted the wait when applicable - `"admin"` - `"customer"` - `"lead"` - `waitLabel: optional string` Human-readable wait duration or preset label - `workflowId: optional string` Workflow ID associated with the wait event - `workflowName: optional string` Workflow display name at the time of the wait event - `Priority object { id, createdAt, isPriority, 3 more }` Conversation priority was updated - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `isPriority: boolean` Whether the conversation is now marked as priority - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "priority"` Priority change type - `"priority"` - `updatedAt: string` ISO timestamp when the part was last updated - `PartAdd object { id, createdAt, object, 3 more }` New participant joined the conversation - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `participant: object { id, type }` The added participant - `id: string` Participant ID - `type: "customer" or "lead" or "admin"` Participant type - `"customer"` - `"lead"` - `"admin"` - `partType: "part_add"` Participant added type - `"part_add"` - `updatedAt: string` ISO timestamp when the part was last updated ### Conversation Part Author - `ConversationPartAuthor object { id, type, email, 2 more }` - `id: string` Author ID - `type: "customer" or "lead" or "admin" or 3 more` Type of author - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `email: optional string` Author email address - `name: optional string` Author display name - `profilePicture: optional string` Author profile picture URL ### Conversation Participant - `ConversationParticipant object { id, type }` - `id: string` Participant ID - `type: "customer" or "lead" or "admin" or 3 more` Type of participant - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` ### Conversation Tag Application - `ConversationTagApplication object { appliedAt, tagId, appliedBy, 3 more }` - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `type: "admin" or "customer" or "lead" or 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id: optional string` Actor identifier when available - `name: optional string` Actor display name when available - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` ### Csat Email Delivery - `CsatEmailDelivery object { status, failedAt, failureReason, 2 more }` - `status: "pending" or "sent" or "failed"` Email delivery status for the CSAT request when applicable - `"pending"` - `"sent"` - `"failed"` - `failedAt: optional string` ISO timestamp when the CSAT email failed - `failureReason: optional string` Operational failure reason for the CSAT email delivery - `messageId: optional string` Email message ID associated with delivery - `sentAt: optional string` ISO timestamp when the CSAT email was sent ### Csat Rated Agent - `CsatRatedAgent object { type, id }` - `type: "teammate" or "fibi" or "chatbot"` Type of agent the CSAT request is attributed to - `"teammate"` - `"fibi"` - `"chatbot"` - `id: optional string` Identifier of the rated agent when applicable ### Csat Workflow Link - `CsatWorkflowLink object { workflowActionId, workflowId, workflowRunId, workflowStepId }` - `workflowActionId: optional string` Workflow action ID associated with the CSAT request - `workflowId: optional string` Workflow ID associated with the CSAT request - `workflowRunId: optional string` Workflow run ID associated with the CSAT request - `workflowStepId: optional string` Workflow step ID associated with the CSAT request ### Email Recipients - `EmailRecipients object { emails, ids }` Primary recipients (To field) - `emails: optional array of string` Array of email addresses - `ids: optional array of string` Array of Featurebase contact IDs ### Conversation Delete Response - `ConversationDeleteResponse object { id, deleted, object }` - `id: string` Unique identifier of the deleted conversation - `deleted: true` Indicates the resource was deleted - `true` - `object: "conversation"` Object type identifier - `"conversation"` # Tags ## Attach a tag to a conversation **post** `/v2/conversations/{id}/tags` Attaches a workspace tag to a conversation. This endpoint requires both the tag ID to attach and the `actingAdminId` of the admin on whose behalf the mutation is recorded. ### Path Parameters - `id` - The conversation ID (short ID) ### Request Body | Field | Type | Required | Description | | --------------- | ------ | -------- | ------------------------------------------------------------------------ | | `tagId` | string | Yes | The Featurebase tag ID to attach | | `actingAdminId` | string | Yes | The admin performing the mutation. Must be a member of the organization. | ### Behavior Featurebase resolves the latest taggable reply/message in the conversation and records the tag attachment against that part so audit metadata remains deterministic. ### Response Returns the affected tag plus attachment metadata such as `targetPartId`, `appliedAt`, and `appliedBy`. ### Example Request ```json { "tagId": "67ec1234abcd5678ef901234", "actingAdminId": "507f1f77bcf86cd799439011" } ``` ### Version Availability This endpoint is only available in API version 2026-01-01.nova and newer. ### Path Parameters - `id: string` Conversation ID (short ID) ### Header Parameters - `"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"` - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Body Parameters - `actingAdminId: string` Required admin ID performing this tag attachment. Must be a member of the organization so the mutation can be attributed to a real admin actor. - `tagId: string` The Featurebase tag ID to attach to the conversation. ### Returns - `AttachedConversationTag object { id, name, type, 5 more }` - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `appliedAt: optional string` ISO timestamp when the tag was applied - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `type: "admin" or "customer" or "lead" or 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id: optional string` Actor identifier when available - `name: optional string` Actor display name when available - `removedAt: optional string` ISO timestamp when the tag was removed, if applicable - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `targetPartId: optional string` Reply/message ID used as the deterministic attachment target for this conversation tag mutation. ### Example ```http curl https://do.featurebase.app/v2/conversations/$ID/tags \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $FEATUREBASE_API_KEY" \ -d '{ "actingAdminId": "507f1f77bcf86cd799439011", "tagId": "67ec1234abcd5678ef901234" }' ``` #### Response ```json { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag", "appliedAt": "2025-01-15T10:30:00.000Z", "appliedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "removedAt": "2025-01-15T11:00:00.000Z", "removedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "targetPartId": "67890" } ``` ## Detach a tag from a conversation **delete** `/v2/conversations/{id}/tags/{tagId}` Removes a workspace tag from a conversation. This endpoint requires the `actingAdminId` of the admin on whose behalf the mutation is recorded. ### Path Parameters - `id` - The conversation ID (short ID) - `tagId` - The Featurebase tag ID to remove ### Request Body | Field | Type | Required | Description | | --------------- | ------ | -------- | ------------------------------------------------------------------------ | | `actingAdminId` | string | Yes | The admin performing the mutation. Must be a member of the organization. | ### Behavior Featurebase resolves the latest taggable reply/message in the conversation and records the tag removal against that part so audit metadata remains deterministic. ### Response Returns the affected tag payload with the most relevant attachment metadata available for that relationship. ### Example Request ```json { "actingAdminId": "507f1f77bcf86cd799439011" } ``` ### Version Availability This endpoint is only available in API version 2026-01-01.nova and newer. ### Path Parameters - `id: string` Conversation ID (short ID) - `tagId: string` The Featurebase tag ID to remove from the conversation. ### Header Parameters - `"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"` - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Body Parameters - `actingAdminId: string` Required admin ID performing this tag removal. Must be a member of the organization so the mutation can be attributed to a real admin actor. ### Returns - `AttachedConversationTag object { id, name, type, 5 more }` - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `appliedAt: optional string` ISO timestamp when the tag was applied - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `type: "admin" or "customer" or "lead" or 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id: optional string` Actor identifier when available - `name: optional string` Actor display name when available - `removedAt: optional string` ISO timestamp when the tag was removed, if applicable - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `targetPartId: optional string` Reply/message ID used as the deterministic attachment target for this conversation tag mutation. ### Example ```http curl https://do.featurebase.app/v2/conversations/$ID/tags/$TAG_ID \ -X DELETE \ -H "Authorization: Bearer $FEATUREBASE_API_KEY" ``` #### Response ```json { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag", "appliedAt": "2025-01-15T10:30:00.000Z", "appliedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "removedAt": "2025-01-15T11:00:00.000Z", "removedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "targetPartId": "67890" } ``` ## Domain Types ### Attached Conversation Tag - `AttachedConversationTag object { id, name, type, 5 more }` - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `appliedAt: optional string` ISO timestamp when the tag was applied - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `type: "admin" or "customer" or "lead" or 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id: optional string` Actor identifier when available - `name: optional string` Actor display name when available - `removedAt: optional string` ISO timestamp when the tag was removed, if applicable - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `targetPartId: optional string` Reply/message ID used as the deterministic attachment target for this conversation tag mutation. ### Conversation Tag Mutation Actor - `ConversationTagMutationActor object { type, id, name }` Actor that applied the tag - `type: "admin" or "customer" or "lead" or 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id: optional string` Actor identifier when available - `name: optional string` Actor display name when available # Participants ## Add a contact to a conversation **post** `/v2/conversations/{id}/participants` Adds a contact (customer or lead) as a participant to an existing conversation. ### Path Parameters - `id` - The conversation ID (short ID) ### Request Body | Field | Type | Required | Description | | -------------------- | ------ | -------- | --------------------------------------------------------------------- | | `participant` | object | Yes | The contact to add (see below) | | `participant.id` | string | No* | The Featurebase ID (24-character ObjectId) - matches customer or lead | | `participant.userId` | string | No* | External user ID from your system - matches customer only | | `participant.email` | string | No* | Email address - matches customer only | | `actingAdminId` | string | No | Admin ID performing the action (for attribution) | \*At least one of `id`, `userId`, or `email` is required in the participant object. ### Lookup Priority 1. If `id` is provided, looks up by Featurebase ID (matches both customer and lead types) 1. If `userId` is provided, looks up by external user ID (matches customer type only) 1. If `email` is provided, looks up by email address (matches customer type only) ### Response Returns the updated conversation object. ### Example Request (by Featurebase ID) ```json { "participant": { "id": "676f0f6765bdaa7d7d760f88" }, "actingAdminId": "507f1f77bcf86cd799439011" } ``` ### Example Request (by external userId) ```json { "participant": { "userId": "user_123" } } ``` ### Example Request (by email) ```json { "participant": { "email": "john@example.com" } } ``` ### Example Response ```json { "object": "conversation", "id": "12345", "participants": [ { "type": "customer", "id": "676f0f6765bdaa7d7d760f88" }, { "type": "customer", "id": "676f0f6765bdaa7d7d760f89" } ], ... } ``` ### Version Availability This endpoint is only available in API version 2026-01-01.nova and newer. ### Path Parameters - `id: string` Conversation ID (short ID) ### Header Parameters - `"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"` - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Body Parameters - `participant: object { id, email, userId }` The contact to add as a participant. At least one of id, userId, or email is required. - `id: optional string` The Featurebase ID of the contact (customer or lead) - `email: optional string` The email address of the contact (matches customer type only) - `userId: optional string` The external user ID from your system (matches customer type only) - `actingAdminId: optional string` The admin ID performing this action. If not provided, changes are attributed to the system bot user. ### Returns - `Conversation object { id, adminAssigneeId, botConversationStateLastUpdatedAt, 26 more }` - `id: string` Unique conversation identifier - `adminAssigneeId: string` ID of the assigned admin - `botConversationStateLastUpdatedAt: string` ISO timestamp when bot state last changed - `brandId: string` ID of the brand associated with this conversation - `createdAt: string` ISO timestamp when conversation was created - `hasAdminOverriddenLanguage: boolean` Whether an admin has manually overridden the language for this conversation. When true, automatic language detection is disabled. - `isBlocked: boolean` Whether the user is blocked - `lastActivityAt: string` ISO timestamp of last activity - `object: "conversation"` Object type identifier - `"conversation"` - `participants: array of ConversationParticipant` Participants in this conversation - `id: string` Participant ID - `type: "customer" or "lead" or "admin" or 3 more` Type of participant - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `priority: boolean` Whether this conversation is marked as priority - `prioritySetAt: string` ISO timestamp when priority was set - `snoozedUntil: string` ISO timestamp until which conversation is snoozed - `state: "open" or "closed" or "snoozed"` Current state of the conversation - `"open"` - `"closed"` - `"snoozed"` - `tags: array of ConversationTag` Current tags applied anywhere in this conversation - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `teamAssigneeId: string` ID of the assigned team - `updatedAt: string` ISO timestamp when conversation was last updated - `userPreferredLanguage: string` User's preferred language - `waitingSince: string` ISO timestamp when conversation started waiting - `awaitingCustomerReply: optional boolean` Whether we are awaiting a customer reply - `botConversationState: optional "active" or "handed_off_to_human" or "resolved"` State of AI agent handling for this conversation - `"active"` - `"handed_off_to_human"` - `"resolved"` - `conversationParts: optional array of ConversationPart` Array of conversation parts (messages). Only included when fetching a single conversation by ID. - `UserMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Message from a customer or lead - `id: string` Unique part identifier - `bodyHtml: string` Message body content as HTML with signed image URLs - `bodyMarkdown: string` Message body content as markdown - `channel: "unknown" or "desktop" or "android" or 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "user_msg"` User message type - `"user_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `id: string` Author ID - `type: "customer" or "lead" or "admin" or 3 more` Type of author - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `email: optional string` Author email address - `name: optional string` Author display name - `profilePicture: optional string` Author profile picture URL - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `type: "admin" or "customer" or "lead" or 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id: optional string` Actor identifier when available - `name: optional string` Actor display name when available - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `AdminMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Message from an admin or support agent - `id: string` Unique part identifier - `bodyHtml: string` Message body content as HTML with signed image URLs - `bodyMarkdown: string` Message body content as markdown - `channel: "unknown" or "desktop" or "android" or 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_msg"` Admin message type - `"admin_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AdminNote object { id, bodyHtml, bodyMarkdown, 7 more }` Internal note visible only to admins - `id: string` Unique part identifier - `bodyHtml: string` Note body content as HTML with signed image URLs - `bodyMarkdown: string` Note body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_note"` Admin internal note type - `"admin_note"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `EmailMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Message sent via email - `id: string` Unique part identifier - `bodyHtml: string` Email body content as HTML with signed image URLs - `bodyMarkdown: string` Email body content as markdown - `channel: "email"` Email channel - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "email_msg"` Email message type - `"email_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `BotMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Automated message from AI or bot - `id: string` Unique part identifier - `bodyHtml: string` Bot message body content as HTML with signed image URLs - `bodyMarkdown: string` Bot message body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "bot_msg"` Bot message type - `"bot_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `channel: optional "unknown" or "desktop" or "android" or 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyOpts object { id, createdAt, object, 6 more }` Presents options for user to choose from - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_opts"` Quick reply options type - `"quick_reply_opts"` - `replyOptions: array of object { id, text }` Available reply options - `id: string` Option ID - `text: string` Option text - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyResp object { id, bodyHtml, bodyMarkdown, 8 more }` User's selection from quick reply options - `id: string` Unique part identifier - `bodyHtml: string` The selected option text as HTML - `bodyMarkdown: string` The selected option text as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_resp"` Quick reply response type - `"quick_reply_resp"` - `selectedOptionId: string` ID of the selected option - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `RatingRequested object { id, createdAt, csat, 3 more }` Represents a persisted CSAT request in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: object { channel, requestedAt, requestId, 7 more }` Canonical CSAT request payload for this thread event - `channel: "desktop" or "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" or "rated" or "canceled" or "expired"` Status of the CSAT request represented by this part - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt: optional string` ISO timestamp after which changing the rating is no longer allowed - `expiredAt: optional string` ISO timestamp when the request expired, when applicable - `lateSubmitWindowEndsAt: optional string` ISO timestamp after which late submission is no longer allowed - `ratedAgent: optional CsatRatedAgent` - `type: "teammate" or "fibi" or "chatbot"` Type of agent the CSAT request is attributed to - `"teammate"` - `"fibi"` - `"chatbot"` - `id: optional string` Identifier of the rated agent when applicable - `workflow: optional CsatWorkflowLink` - `workflowActionId: optional string` Workflow action ID associated with the CSAT request - `workflowId: optional string` Workflow ID associated with the CSAT request - `workflowRunId: optional string` Workflow run ID associated with the CSAT request - `workflowStepId: optional string` Workflow step ID associated with the CSAT request - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_requested"` CSAT rating requested part type - `"rating_requested"` - `updatedAt: string` ISO timestamp when the part was last updated - `RatingSubmitted object { id, createdAt, csat, 3 more }` Represents a persisted CSAT submission in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: object { channel, ratedAt, requestId, 7 more }` Canonical CSAT submission payload for this thread event - `channel: "desktop" or "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `ratedAt: string` ISO timestamp when the customer submitted the rating - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `score: number` CSAT score from 1 to 5 - `status: "rated"` Submitted ratings are always in the rated state - `"rated"` - `ratedAgent: optional CsatRatedAgent` - `remark: optional string` Optional remark left with the rating - `requestedAt: optional string` ISO timestamp when the request was created - `workflow: optional CsatWorkflowLink` - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_submitted"` CSAT rating submitted part type - `"rating_submitted"` - `updatedAt: string` ISO timestamp when the part was last updated - `AttrPrompt object { id, createdAt, form, 6 more }` Requests information from user via form - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `form: object { id, attributes }` Form configuration - `id: string` Form ID - `attributes: array of object { identifier, name, type }` Form fields - `identifier: string` Field identifier - `name: string` Field display name - `type: string` Field type - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_prompt"` Attribute collection prompt type - `"attr_prompt"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AttrComplete object { id, createdAt, object, 2 more }` Indicates form was completed - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_complete"` Attribute collection complete type - `"attr_complete"` - `updatedAt: string` ISO timestamp when the part was last updated - `Assign object { id, createdAt, object, 5 more }` Conversation assigned to admin or team - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "assign"` Assignment type - `"assign"` - `updatedAt: string` ISO timestamp when the part was last updated - `adminAssigneeId: optional string` ID of the admin assigned to the conversation - `adminAssignerId: optional string` ID of the admin who made the assignment - `teamAssigneeId: optional string` ID of the team assigned to the conversation - `Status object { id, createdAt, object, 4 more }` Conversation state changed (open/closed/snoozed) - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "status"` Status change type - `"status"` - `status: "open" or "closed" or "snoozed"` New conversation status - `"open"` - `"closed"` - `"snoozed"` - `updatedAt: string` ISO timestamp when the part was last updated - `snoozedUntil: optional string` ISO timestamp until conversation is snoozed (if snoozed) - `Tags object { id, action, createdAt, 8 more }` A tag was added to or removed from a specific reply - `id: string` Unique part identifier - `action: "added" or "removed"` Whether the tag was added or removed - `"added"` - `"removed"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `occurredAt: string` ISO timestamp when the tag mutation occurred - `partType: "tags"` Tag update type - `"tags"` - `tagId: string` Identifier of the affected tag - `updatedAt: string` ISO timestamp when the part was last updated - `actor: optional ConversationTagMutationActor` Actor that applied the tag - `tagName: optional string` Tag name at the time of the event or the best available current display name - `targetPartId: optional string` Conversation part that the tag mutation targeted - `WorkflowWait object { id, createdAt, object, 3 more }` Represents a workflow wait start, finish, or interruption in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "workflow_wait"` Workflow wait event part type - `"workflow_wait"` - `updatedAt: string` ISO timestamp when the part was last updated - `workflowWait: object { eventType, occurredAt, interruptedByUserType, 3 more }` Workflow wait event payload for this thread event - `eventType: "started" or "finished" or "interrupted"` Lifecycle stage of the workflow wait event - `"started"` - `"finished"` - `"interrupted"` - `occurredAt: string` ISO timestamp when the wait event occurred - `interruptedByUserType: optional "admin" or "customer" or "lead"` User type that interrupted the wait when applicable - `"admin"` - `"customer"` - `"lead"` - `waitLabel: optional string` Human-readable wait duration or preset label - `workflowId: optional string` Workflow ID associated with the wait event - `workflowName: optional string` Workflow display name at the time of the wait event - `Priority object { id, createdAt, isPriority, 3 more }` Conversation priority was updated - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `isPriority: boolean` Whether the conversation is now marked as priority - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "priority"` Priority change type - `"priority"` - `updatedAt: string` ISO timestamp when the part was last updated - `PartAdd object { id, createdAt, object, 3 more }` New participant joined the conversation - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `participant: object { id, type }` The added participant - `id: string` Participant ID - `type: "customer" or "lead" or "admin"` Participant type - `"customer"` - `"lead"` - `"admin"` - `partType: "part_add"` Participant added type - `"part_add"` - `updatedAt: string` ISO timestamp when the part was last updated - `csatDebug: optional object { requestId, status, changeLockWindowEndsAt, 2 more }` Minimal CSAT diagnostics for the current effective request. - `requestId: string` Canonical CSAT request ID used for the latest debug snapshot - `status: "pending" or "rated" or "canceled" or "expired"` Lifecycle status of the request represented in the debug snapshot - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt: optional string` ISO timestamp when rating edits stop being accepted - `emailDelivery: optional CsatEmailDelivery` - `status: "pending" or "sent" or "failed"` Email delivery status for the CSAT request when applicable - `"pending"` - `"sent"` - `"failed"` - `failedAt: optional string` ISO timestamp when the CSAT email failed - `failureReason: optional string` Operational failure reason for the CSAT email delivery - `messageId: optional string` Email message ID associated with delivery - `sentAt: optional string` ISO timestamp when the CSAT email was sent - `lateSubmitWindowEndsAt: optional string` ISO timestamp when first-time submissions stop being accepted - `csatHistory: optional array of object { channel, isLatestEffective, lastUpdatedAt, 14 more }` Historical CSAT requests for this conversation, ordered newest first. - `channel: "desktop" or "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `isLatestEffective: boolean` Whether this row represents the currently effective CSAT request for the conversation - `lastUpdatedAt: string` ISO timestamp when the request last changed - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" or "rated" or "canceled" or "expired"` Lifecycle status for this historical CSAT request - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt: optional string` ISO timestamp when the request was canceled - `changeLockWindowEndsAt: optional string` ISO timestamp when edits to an existing rating stop being accepted - `emailDelivery: optional CsatEmailDelivery` - `expiredAt: optional string` ISO timestamp when the request expired - `lateSubmitWindowEndsAt: optional string` ISO timestamp when first-time submissions stop being accepted - `ratedAgent: optional CsatRatedAgent` - `ratedAt: optional string` ISO timestamp when the request was rated - `remark: optional string` Submitted remark when present - `score: optional number` Submitted score when this request was rated - `workflow: optional CsatWorkflowLink` - `csatSummary: optional object { lastUpdatedAt, status, canceledAt, 10 more }` Derived CSAT summary for this conversation when a rating request or rating exists. - `lastUpdatedAt: string` ISO timestamp when the summary last changed - `status: "pending" or "rated" or "canceled" or "expired"` Current summary status for CSAT on this conversation - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt: optional string` ISO timestamp when the request was canceled - `channel: optional "desktop" or "email"` Channel used for the latest CSAT request when known - `"desktop"` - `"email"` - `expiredAt: optional string` ISO timestamp when the request expired - `ratedAgent: optional CsatRatedAgent` - `ratedAt: optional string` ISO timestamp when the customer submitted a rating - `remark: optional string` Optional remark left with the rating - `requestedAt: optional string` ISO timestamp when the latest CSAT request was created - `requestId: optional string` Canonical CSAT request ID - `requestSource: optional "workflow"` Source of the latest CSAT request when known - `"workflow"` - `score: optional number` CSAT score from 1 to 5 when rated - `workflow: optional CsatWorkflowLink` - `disableCustomerReply: optional boolean` Whether customer replies are disabled - `readReceipts: optional array of object { id, lastReadPartId, userType }` Read receipts indicating how far each participant has read in the conversation. Each receipt maps a user to their last-read conversation part. The tracked position reflects the system read state and may reference parts the user cannot directly view (e.g., a contact's read position may point to an internal admin note). Use these receipts to render read indicators and typing awareness, not to infer content access. - `id: string` The internal ID of the user - `lastReadPartId: string` The ID of the last conversation part this user has read. Note: This reflects the system-tracked read position and may reference a part the user cannot directly access (e.g., internal notes for contacts). The read state is advanced to the latest part in the conversation regardless of part visibility. - `userType: "admin" or "customer" or "lead"` Type of user who has read the conversation - `"admin"` - `"customer"` - `"lead"` - `source: optional object { bodyHtml, bodyMarkdown, channel, 4 more }` - `bodyHtml: string` Body of the initial message as HTML with signed image URLs - `bodyMarkdown: string` Body of the initial message as markdown - `channel: "unknown" or "desktop" or "android" or 2 more` Channel through which the conversation was initiated - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `author: optional ConversationParticipant` - `id: string` Participant ID - `type: "customer" or "lead" or "admin" or 3 more` Type of participant - `deliveredAs: optional "customer_initiated" or "admin_initiated"` How the conversation was initiated - `"customer_initiated"` - `"admin_initiated"` - `subject: optional string` Subject line for email conversations - `url: optional string` URL where the conversation was initiated - `title: optional string` Conversation title ### Example ```http curl https://do.featurebase.app/v2/conversations/$ID/participants \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $FEATUREBASE_API_KEY" \ -d '{ "participant": {}, "actingAdminId": "507f1f77bcf86cd799439011" }' ``` #### Response ```json { "id": "12345", "adminAssigneeId": "507f1f77bcf86cd799439011", "botConversationStateLastUpdatedAt": "2025-01-15T10:30:00.000Z", "brandId": "507f1f77bcf86cd799439011", "createdAt": "2025-01-15T10:30:00.000Z", "hasAdminOverriddenLanguage": false, "isBlocked": false, "lastActivityAt": "2025-01-15T12:30:00.000Z", "object": "conversation", "participants": [ { "id": "676f0f6765bdaa7d7d760f88", "type": "customer" } ], "priority": false, "prioritySetAt": "2025-01-15T10:30:00.000Z", "snoozedUntil": "2025-01-16T09:00:00.000Z", "state": "open", "tags": [ { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } ], "teamAssigneeId": "507f1f77bcf86cd799439012", "updatedAt": "2025-01-15T12:30:00.000Z", "userPreferredLanguage": "en", "waitingSince": "2025-01-15T10:30:00.000Z", "awaitingCustomerReply": true, "botConversationState": "active", "conversationParts": [ { "id": "1", "bodyHtml": "Hello, I have a question about your product.
", "bodyMarkdown": "Hello, I have a question about your product.", "channel": "desktop", "createdAt": "2025-01-15T10:30:00.000Z", "object": "conversation_part", "partType": "user_msg", "updatedAt": "2025-01-15T10:30:00.000Z", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/user.png" }, "redacted": false, "tagApplications": [ { "appliedAt": "2025-01-15T10:30:00.000Z", "tagId": "67ec1234abcd5678ef901234", "appliedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "removedAt": "2025-01-15T11:00:00.000Z", "removedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "tag": { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } } ] } ], "csatDebug": { "requestId": "csat_req_123", "status": "pending", "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z", "emailDelivery": { "status": "failed", "failedAt": "2025-01-15T10:31:00.000Z", "failureReason": "smtp_bounce", "messageId": "msg_123", "sentAt": "2025-01-15T10:31:00.000Z" }, "lateSubmitWindowEndsAt": "2025-01-16T10:30:00.000Z" }, "csatHistory": [ { "channel": "desktop", "isLatestEffective": true, "lastUpdatedAt": "2025-01-15T10:35:00.000Z", "requestedAt": "2025-01-15T10:30:00.000Z", "requestId": "csat_req_123", "requestSource": "workflow", "status": "pending", "canceledAt": "2025-01-15T10:32:00.000Z", "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z", "emailDelivery": { "status": "failed", "failedAt": "2025-01-15T10:31:00.000Z", "failureReason": "smtp_bounce", "messageId": "msg_123", "sentAt": "2025-01-15T10:31:00.000Z" }, "expiredAt": "2025-01-16T10:30:00.000Z", "lateSubmitWindowEndsAt": "2025-01-16T10:30:00.000Z", "ratedAgent": { "type": "teammate", "id": "507f1f77bcf86cd799439011" }, "ratedAt": "2025-01-15T10:35:00.000Z", "remark": "Thanks for the quick help.", "score": 4, "workflow": { "workflowActionId": "action_123", "workflowId": "507f1f77bcf86cd799439011", "workflowRunId": "run_123", "workflowStepId": "step_123" } } ], "csatSummary": { "lastUpdatedAt": "2025-01-15T10:35:00.000Z", "status": "pending", "canceledAt": "2025-01-15T10:35:00.000Z", "channel": "desktop", "expiredAt": "2025-01-15T10:35:00.000Z", "ratedAgent": { "type": "teammate", "id": "507f1f77bcf86cd799439011" }, "ratedAt": "2025-01-15T10:35:00.000Z", "remark": "Very helpful support.", "requestedAt": "2025-01-15T10:30:00.000Z", "requestId": "csat_req_123", "requestSource": "workflow", "score": 5, "workflow": { "workflowActionId": "action_123", "workflowId": "507f1f77bcf86cd799439011", "workflowRunId": "run_123", "workflowStepId": "step_123" } }, "disableCustomerReply": false, "readReceipts": [ { "id": "507f1f77bcf86cd799439011", "lastReadPartId": "8", "userType": "admin" } ], "source": { "bodyHtml": "Hi, I have a question about your enterprise plan...
", "bodyMarkdown": "Hi, I have a question about your enterprise plan...", "channel": "desktop", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer" }, "deliveredAs": "customer_initiated", "subject": "Question about pricing", "url": "https://example.com/pricing" }, "title": "Question about pricing" } ``` ## Remove a contact from a conversation **delete** `/v2/conversations/{id}/participants` Removes a contact (customer or lead) from an existing conversation. **Note:** You cannot remove the last participant from a conversation. ### Path Parameters - `id` - The conversation ID (short ID) ### Request Body | Field | Type | Required | Description | | --------------- | ------ | -------- | ------------------------------------------------------------------- | | `id` | string | Yes | The Featurebase ID of the contact to remove (24-character ObjectId) | | `actingAdminId` | string | No | Admin ID performing the action (for attribution) | ### Response Returns the updated conversation object. ### Example Request ```json { "id": "676f0f6765bdaa7d7d760f88", "actingAdminId": "507f1f77bcf86cd799439011" } ``` ### Example Response ```json { "object": "conversation", "id": "12345", "participants": [ { "type": "customer", "id": "676f0f6765bdaa7d7d760f89" } ], ... } ``` ### Error Cases - **400 Bad Request** - Cannot remove the last participant from a conversation - **404 Not Found** - Conversation or contact not found in participants ### Version Availability This endpoint is only available in API version 2026-01-01.nova and newer. ### Path Parameters - `id: string` Conversation ID (short ID) ### Header Parameters - `"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"` - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Body Parameters - `id: string` The Featurebase ID of the contact (customer or lead) to remove - `actingAdminId: optional string` The admin ID performing this action. If not provided, changes are attributed to the system bot user. ### Returns - `Conversation object { id, adminAssigneeId, botConversationStateLastUpdatedAt, 26 more }` - `id: string` Unique conversation identifier - `adminAssigneeId: string` ID of the assigned admin - `botConversationStateLastUpdatedAt: string` ISO timestamp when bot state last changed - `brandId: string` ID of the brand associated with this conversation - `createdAt: string` ISO timestamp when conversation was created - `hasAdminOverriddenLanguage: boolean` Whether an admin has manually overridden the language for this conversation. When true, automatic language detection is disabled. - `isBlocked: boolean` Whether the user is blocked - `lastActivityAt: string` ISO timestamp of last activity - `object: "conversation"` Object type identifier - `"conversation"` - `participants: array of ConversationParticipant` Participants in this conversation - `id: string` Participant ID - `type: "customer" or "lead" or "admin" or 3 more` Type of participant - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `priority: boolean` Whether this conversation is marked as priority - `prioritySetAt: string` ISO timestamp when priority was set - `snoozedUntil: string` ISO timestamp until which conversation is snoozed - `state: "open" or "closed" or "snoozed"` Current state of the conversation - `"open"` - `"closed"` - `"snoozed"` - `tags: array of ConversationTag` Current tags applied anywhere in this conversation - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `teamAssigneeId: string` ID of the assigned team - `updatedAt: string` ISO timestamp when conversation was last updated - `userPreferredLanguage: string` User's preferred language - `waitingSince: string` ISO timestamp when conversation started waiting - `awaitingCustomerReply: optional boolean` Whether we are awaiting a customer reply - `botConversationState: optional "active" or "handed_off_to_human" or "resolved"` State of AI agent handling for this conversation - `"active"` - `"handed_off_to_human"` - `"resolved"` - `conversationParts: optional array of ConversationPart` Array of conversation parts (messages). Only included when fetching a single conversation by ID. - `UserMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Message from a customer or lead - `id: string` Unique part identifier - `bodyHtml: string` Message body content as HTML with signed image URLs - `bodyMarkdown: string` Message body content as markdown - `channel: "unknown" or "desktop" or "android" or 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "user_msg"` User message type - `"user_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `id: string` Author ID - `type: "customer" or "lead" or "admin" or 3 more` Type of author - `"customer"` - `"lead"` - `"admin"` - `"bot"` - `"guest"` - `"integration"` - `email: optional string` Author email address - `name: optional string` Author display name - `profilePicture: optional string` Author profile picture URL - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `type: "admin" or "customer" or "lead" or 4 more` Actor that caused the tag mutation - `"admin"` - `"customer"` - `"lead"` - `"bot"` - `"integration"` - `"system"` - `"workflow"` - `id: optional string` Actor identifier when available - `name: optional string` Actor display name when available - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `AdminMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Message from an admin or support agent - `id: string` Unique part identifier - `bodyHtml: string` Message body content as HTML with signed image URLs - `bodyMarkdown: string` Message body content as markdown - `channel: "unknown" or "desktop" or "android" or 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_msg"` Admin message type - `"admin_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AdminNote object { id, bodyHtml, bodyMarkdown, 7 more }` Internal note visible only to admins - `id: string` Unique part identifier - `bodyHtml: string` Note body content as HTML with signed image URLs - `bodyMarkdown: string` Note body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "admin_note"` Admin internal note type - `"admin_note"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `EmailMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Message sent via email - `id: string` Unique part identifier - `bodyHtml: string` Email body content as HTML with signed image URLs - `bodyMarkdown: string` Email body content as markdown - `channel: "email"` Email channel - `"email"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "email_msg"` Email message type - `"email_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `BotMsg object { id, bodyHtml, bodyMarkdown, 8 more }` Automated message from AI or bot - `id: string` Unique part identifier - `bodyHtml: string` Bot message body content as HTML with signed image URLs - `bodyMarkdown: string` Bot message body content as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "bot_msg"` Bot message type - `"bot_msg"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `channel: optional "unknown" or "desktop" or "android" or 2 more` Channel through which the message was sent - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyOpts object { id, createdAt, object, 6 more }` Presents options for user to choose from - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_opts"` Quick reply options type - `"quick_reply_opts"` - `replyOptions: array of object { id, text }` Available reply options - `id: string` Option ID - `text: string` Option text - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `QuickReplyResp object { id, bodyHtml, bodyMarkdown, 8 more }` User's selection from quick reply options - `id: string` Unique part identifier - `bodyHtml: string` The selected option text as HTML - `bodyMarkdown: string` The selected option text as markdown - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "quick_reply_resp"` Quick reply response type - `"quick_reply_resp"` - `selectedOptionId: string` ID of the selected option - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `RatingRequested object { id, createdAt, csat, 3 more }` Represents a persisted CSAT request in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: object { channel, requestedAt, requestId, 7 more }` Canonical CSAT request payload for this thread event - `channel: "desktop" or "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" or "rated" or "canceled" or "expired"` Status of the CSAT request represented by this part - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt: optional string` ISO timestamp after which changing the rating is no longer allowed - `expiredAt: optional string` ISO timestamp when the request expired, when applicable - `lateSubmitWindowEndsAt: optional string` ISO timestamp after which late submission is no longer allowed - `ratedAgent: optional CsatRatedAgent` - `type: "teammate" or "fibi" or "chatbot"` Type of agent the CSAT request is attributed to - `"teammate"` - `"fibi"` - `"chatbot"` - `id: optional string` Identifier of the rated agent when applicable - `workflow: optional CsatWorkflowLink` - `workflowActionId: optional string` Workflow action ID associated with the CSAT request - `workflowId: optional string` Workflow ID associated with the CSAT request - `workflowRunId: optional string` Workflow run ID associated with the CSAT request - `workflowStepId: optional string` Workflow step ID associated with the CSAT request - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_requested"` CSAT rating requested part type - `"rating_requested"` - `updatedAt: string` ISO timestamp when the part was last updated - `RatingSubmitted object { id, createdAt, csat, 3 more }` Represents a persisted CSAT submission in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `csat: object { channel, ratedAt, requestId, 7 more }` Canonical CSAT submission payload for this thread event - `channel: "desktop" or "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `ratedAt: string` ISO timestamp when the customer submitted the rating - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `score: number` CSAT score from 1 to 5 - `status: "rated"` Submitted ratings are always in the rated state - `"rated"` - `ratedAgent: optional CsatRatedAgent` - `remark: optional string` Optional remark left with the rating - `requestedAt: optional string` ISO timestamp when the request was created - `workflow: optional CsatWorkflowLink` - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "rating_submitted"` CSAT rating submitted part type - `"rating_submitted"` - `updatedAt: string` ISO timestamp when the part was last updated - `AttrPrompt object { id, createdAt, form, 6 more }` Requests information from user via form - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `form: object { id, attributes }` Form configuration - `id: string` Form ID - `attributes: array of object { identifier, name, type }` Form fields - `identifier: string` Field identifier - `name: string` Field display name - `type: string` Field type - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_prompt"` Attribute collection prompt type - `"attr_prompt"` - `updatedAt: string` ISO timestamp when the part was last updated - `author: optional ConversationPartAuthor` - `redacted: optional boolean` Whether this message has been redacted - `tagApplications: optional array of ConversationTagApplication` Reply-level tag applications and provenance for this conversation part - `appliedAt: string` ISO timestamp when the tag was applied to this reply - `tagId: string` Identifier of the applied tag - `appliedBy: optional ConversationTagMutationActor` Actor that applied the tag - `removedAt: optional string` ISO timestamp when the tag was removed from this reply, if it was removed - `removedBy: optional ConversationTagMutationActor` Actor that applied the tag - `tag: optional ConversationTag` Resolved tag object when the tag still exists in the shared workspace catalog - `AttrComplete object { id, createdAt, object, 2 more }` Indicates form was completed - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "attr_complete"` Attribute collection complete type - `"attr_complete"` - `updatedAt: string` ISO timestamp when the part was last updated - `Assign object { id, createdAt, object, 5 more }` Conversation assigned to admin or team - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "assign"` Assignment type - `"assign"` - `updatedAt: string` ISO timestamp when the part was last updated - `adminAssigneeId: optional string` ID of the admin assigned to the conversation - `adminAssignerId: optional string` ID of the admin who made the assignment - `teamAssigneeId: optional string` ID of the team assigned to the conversation - `Status object { id, createdAt, object, 4 more }` Conversation state changed (open/closed/snoozed) - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "status"` Status change type - `"status"` - `status: "open" or "closed" or "snoozed"` New conversation status - `"open"` - `"closed"` - `"snoozed"` - `updatedAt: string` ISO timestamp when the part was last updated - `snoozedUntil: optional string` ISO timestamp until conversation is snoozed (if snoozed) - `Tags object { id, action, createdAt, 8 more }` A tag was added to or removed from a specific reply - `id: string` Unique part identifier - `action: "added" or "removed"` Whether the tag was added or removed - `"added"` - `"removed"` - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `occurredAt: string` ISO timestamp when the tag mutation occurred - `partType: "tags"` Tag update type - `"tags"` - `tagId: string` Identifier of the affected tag - `updatedAt: string` ISO timestamp when the part was last updated - `actor: optional ConversationTagMutationActor` Actor that applied the tag - `tagName: optional string` Tag name at the time of the event or the best available current display name - `targetPartId: optional string` Conversation part that the tag mutation targeted - `WorkflowWait object { id, createdAt, object, 3 more }` Represents a workflow wait start, finish, or interruption in the conversation thread - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "workflow_wait"` Workflow wait event part type - `"workflow_wait"` - `updatedAt: string` ISO timestamp when the part was last updated - `workflowWait: object { eventType, occurredAt, interruptedByUserType, 3 more }` Workflow wait event payload for this thread event - `eventType: "started" or "finished" or "interrupted"` Lifecycle stage of the workflow wait event - `"started"` - `"finished"` - `"interrupted"` - `occurredAt: string` ISO timestamp when the wait event occurred - `interruptedByUserType: optional "admin" or "customer" or "lead"` User type that interrupted the wait when applicable - `"admin"` - `"customer"` - `"lead"` - `waitLabel: optional string` Human-readable wait duration or preset label - `workflowId: optional string` Workflow ID associated with the wait event - `workflowName: optional string` Workflow display name at the time of the wait event - `Priority object { id, createdAt, isPriority, 3 more }` Conversation priority was updated - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `isPriority: boolean` Whether the conversation is now marked as priority - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `partType: "priority"` Priority change type - `"priority"` - `updatedAt: string` ISO timestamp when the part was last updated - `PartAdd object { id, createdAt, object, 3 more }` New participant joined the conversation - `id: string` Unique part identifier - `createdAt: string` ISO timestamp when the part was created - `object: "conversation_part"` Object type identifier - `"conversation_part"` - `participant: object { id, type }` The added participant - `id: string` Participant ID - `type: "customer" or "lead" or "admin"` Participant type - `"customer"` - `"lead"` - `"admin"` - `partType: "part_add"` Participant added type - `"part_add"` - `updatedAt: string` ISO timestamp when the part was last updated - `csatDebug: optional object { requestId, status, changeLockWindowEndsAt, 2 more }` Minimal CSAT diagnostics for the current effective request. - `requestId: string` Canonical CSAT request ID used for the latest debug snapshot - `status: "pending" or "rated" or "canceled" or "expired"` Lifecycle status of the request represented in the debug snapshot - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `changeLockWindowEndsAt: optional string` ISO timestamp when rating edits stop being accepted - `emailDelivery: optional CsatEmailDelivery` - `status: "pending" or "sent" or "failed"` Email delivery status for the CSAT request when applicable - `"pending"` - `"sent"` - `"failed"` - `failedAt: optional string` ISO timestamp when the CSAT email failed - `failureReason: optional string` Operational failure reason for the CSAT email delivery - `messageId: optional string` Email message ID associated with delivery - `sentAt: optional string` ISO timestamp when the CSAT email was sent - `lateSubmitWindowEndsAt: optional string` ISO timestamp when first-time submissions stop being accepted - `csatHistory: optional array of object { channel, isLatestEffective, lastUpdatedAt, 14 more }` Historical CSAT requests for this conversation, ordered newest first. - `channel: "desktop" or "email"` Channel used for the CSAT request - `"desktop"` - `"email"` - `isLatestEffective: boolean` Whether this row represents the currently effective CSAT request for the conversation - `lastUpdatedAt: string` ISO timestamp when the request last changed - `requestedAt: string` ISO timestamp when the request was created - `requestId: string` Canonical CSAT request ID - `requestSource: "workflow"` Source that created the CSAT request - `"workflow"` - `status: "pending" or "rated" or "canceled" or "expired"` Lifecycle status for this historical CSAT request - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt: optional string` ISO timestamp when the request was canceled - `changeLockWindowEndsAt: optional string` ISO timestamp when edits to an existing rating stop being accepted - `emailDelivery: optional CsatEmailDelivery` - `expiredAt: optional string` ISO timestamp when the request expired - `lateSubmitWindowEndsAt: optional string` ISO timestamp when first-time submissions stop being accepted - `ratedAgent: optional CsatRatedAgent` - `ratedAt: optional string` ISO timestamp when the request was rated - `remark: optional string` Submitted remark when present - `score: optional number` Submitted score when this request was rated - `workflow: optional CsatWorkflowLink` - `csatSummary: optional object { lastUpdatedAt, status, canceledAt, 10 more }` Derived CSAT summary for this conversation when a rating request or rating exists. - `lastUpdatedAt: string` ISO timestamp when the summary last changed - `status: "pending" or "rated" or "canceled" or "expired"` Current summary status for CSAT on this conversation - `"pending"` - `"rated"` - `"canceled"` - `"expired"` - `canceledAt: optional string` ISO timestamp when the request was canceled - `channel: optional "desktop" or "email"` Channel used for the latest CSAT request when known - `"desktop"` - `"email"` - `expiredAt: optional string` ISO timestamp when the request expired - `ratedAgent: optional CsatRatedAgent` - `ratedAt: optional string` ISO timestamp when the customer submitted a rating - `remark: optional string` Optional remark left with the rating - `requestedAt: optional string` ISO timestamp when the latest CSAT request was created - `requestId: optional string` Canonical CSAT request ID - `requestSource: optional "workflow"` Source of the latest CSAT request when known - `"workflow"` - `score: optional number` CSAT score from 1 to 5 when rated - `workflow: optional CsatWorkflowLink` - `disableCustomerReply: optional boolean` Whether customer replies are disabled - `readReceipts: optional array of object { id, lastReadPartId, userType }` Read receipts indicating how far each participant has read in the conversation. Each receipt maps a user to their last-read conversation part. The tracked position reflects the system read state and may reference parts the user cannot directly view (e.g., a contact's read position may point to an internal admin note). Use these receipts to render read indicators and typing awareness, not to infer content access. - `id: string` The internal ID of the user - `lastReadPartId: string` The ID of the last conversation part this user has read. Note: This reflects the system-tracked read position and may reference a part the user cannot directly access (e.g., internal notes for contacts). The read state is advanced to the latest part in the conversation regardless of part visibility. - `userType: "admin" or "customer" or "lead"` Type of user who has read the conversation - `"admin"` - `"customer"` - `"lead"` - `source: optional object { bodyHtml, bodyMarkdown, channel, 4 more }` - `bodyHtml: string` Body of the initial message as HTML with signed image URLs - `bodyMarkdown: string` Body of the initial message as markdown - `channel: "unknown" or "desktop" or "android" or 2 more` Channel through which the conversation was initiated - `"unknown"` - `"desktop"` - `"android"` - `"ios"` - `"email"` - `author: optional ConversationParticipant` - `id: string` Participant ID - `type: "customer" or "lead" or "admin" or 3 more` Type of participant - `deliveredAs: optional "customer_initiated" or "admin_initiated"` How the conversation was initiated - `"customer_initiated"` - `"admin_initiated"` - `subject: optional string` Subject line for email conversations - `url: optional string` URL where the conversation was initiated - `title: optional string` Conversation title ### Example ```http curl https://do.featurebase.app/v2/conversations/$ID/participants \ -X DELETE \ -H "Authorization: Bearer $FEATUREBASE_API_KEY" ``` #### Response ```json { "id": "12345", "adminAssigneeId": "507f1f77bcf86cd799439011", "botConversationStateLastUpdatedAt": "2025-01-15T10:30:00.000Z", "brandId": "507f1f77bcf86cd799439011", "createdAt": "2025-01-15T10:30:00.000Z", "hasAdminOverriddenLanguage": false, "isBlocked": false, "lastActivityAt": "2025-01-15T12:30:00.000Z", "object": "conversation", "participants": [ { "id": "676f0f6765bdaa7d7d760f88", "type": "customer" } ], "priority": false, "prioritySetAt": "2025-01-15T10:30:00.000Z", "snoozedUntil": "2025-01-16T09:00:00.000Z", "state": "open", "tags": [ { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } ], "teamAssigneeId": "507f1f77bcf86cd799439012", "updatedAt": "2025-01-15T12:30:00.000Z", "userPreferredLanguage": "en", "waitingSince": "2025-01-15T10:30:00.000Z", "awaitingCustomerReply": true, "botConversationState": "active", "conversationParts": [ { "id": "1", "bodyHtml": "Hello, I have a question about your product.
", "bodyMarkdown": "Hello, I have a question about your product.", "channel": "desktop", "createdAt": "2025-01-15T10:30:00.000Z", "object": "conversation_part", "partType": "user_msg", "updatedAt": "2025-01-15T10:30:00.000Z", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/user.png" }, "redacted": false, "tagApplications": [ { "appliedAt": "2025-01-15T10:30:00.000Z", "tagId": "67ec1234abcd5678ef901234", "appliedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "removedAt": "2025-01-15T11:00:00.000Z", "removedBy": { "type": "admin", "id": "507f1f77bcf86cd799439011", "name": "John Doe" }, "tag": { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } } ] } ], "csatDebug": { "requestId": "csat_req_123", "status": "pending", "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z", "emailDelivery": { "status": "failed", "failedAt": "2025-01-15T10:31:00.000Z", "failureReason": "smtp_bounce", "messageId": "msg_123", "sentAt": "2025-01-15T10:31:00.000Z" }, "lateSubmitWindowEndsAt": "2025-01-16T10:30:00.000Z" }, "csatHistory": [ { "channel": "desktop", "isLatestEffective": true, "lastUpdatedAt": "2025-01-15T10:35:00.000Z", "requestedAt": "2025-01-15T10:30:00.000Z", "requestId": "csat_req_123", "requestSource": "workflow", "status": "pending", "canceledAt": "2025-01-15T10:32:00.000Z", "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z", "emailDelivery": { "status": "failed", "failedAt": "2025-01-15T10:31:00.000Z", "failureReason": "smtp_bounce", "messageId": "msg_123", "sentAt": "2025-01-15T10:31:00.000Z" }, "expiredAt": "2025-01-16T10:30:00.000Z", "lateSubmitWindowEndsAt": "2025-01-16T10:30:00.000Z", "ratedAgent": { "type": "teammate", "id": "507f1f77bcf86cd799439011" }, "ratedAt": "2025-01-15T10:35:00.000Z", "remark": "Thanks for the quick help.", "score": 4, "workflow": { "workflowActionId": "action_123", "workflowId": "507f1f77bcf86cd799439011", "workflowRunId": "run_123", "workflowStepId": "step_123" } } ], "csatSummary": { "lastUpdatedAt": "2025-01-15T10:35:00.000Z", "status": "pending", "canceledAt": "2025-01-15T10:35:00.000Z", "channel": "desktop", "expiredAt": "2025-01-15T10:35:00.000Z", "ratedAgent": { "type": "teammate", "id": "507f1f77bcf86cd799439011" }, "ratedAt": "2025-01-15T10:35:00.000Z", "remark": "Very helpful support.", "requestedAt": "2025-01-15T10:30:00.000Z", "requestId": "csat_req_123", "requestSource": "workflow", "score": 5, "workflow": { "workflowActionId": "action_123", "workflowId": "507f1f77bcf86cd799439011", "workflowRunId": "run_123", "workflowStepId": "step_123" } }, "disableCustomerReply": false, "readReceipts": [ { "id": "507f1f77bcf86cd799439011", "lastReadPartId": "8", "userType": "admin" } ], "source": { "bodyHtml": "Hi, I have a question about your enterprise plan...
", "bodyMarkdown": "Hi, I have a question about your enterprise plan...", "channel": "desktop", "author": { "id": "676f0f6765bdaa7d7d760f88", "type": "customer" }, "deliveredAs": "customer_initiated", "subject": "Question about pricing", "url": "https://example.com/pricing" }, "title": "Question about pricing" } ```