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" } ``` # Conversation Tags ## List workspace tags **get** `/v2/tags` Returns the live conversation tags available in the workspace tag catalog. These are the canonical tags that power conversation payloads, filters, and tag mutation endpoints. ### Header Parameters - `"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"` - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `data: array of ConversationTag` Array containing the actual response elements - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `nextCursor: string` Cursor to use for fetching the next page. Null if there are no more results. - `object: "list"` String representing the object type - `"list"` ### Example ```http curl https://do.featurebase.app/v2/tags \ -H "Authorization: Bearer $FEATUREBASE_API_KEY" ``` #### Response ```json { "data": [ { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } ], "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9", "object": "list" } ``` ## Create or rename a tag **post** `/v2/tags` Creates a new workspace conversation tag when only `name` is provided. If `id` is also provided, the existing tag is renamed instead. ### Header Parameters - `"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"` - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Body Parameters - `name: string` Tag name - `id: optional string` Optional existing tag ID. Provide this to rename an existing tag instead of creating a new one. - `actingAdminId: optional string` Optional admin ID for actor attribution and permission checks. ### Returns - `ConversationTag object { id, name, type }` - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` ### Example ```http curl https://do.featurebase.app/v2/tags \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $FEATUREBASE_API_KEY" \ -d '{ "name": "Churn", "id": "67ec1234abcd5678ef901234", "actingAdminId": "507f1f77bcf86cd799439011" }' ``` #### Response ```json { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } ``` ## Get tag by ID **get** `/v2/tags/{id}` Returns a single conversation tag by its Featurebase tag ID. Archived tags can still be retrieved directly by ID, while permanently deleted tags return `404`. ### Path Parameters - `id: string` The Featurebase tag ID ### Header Parameters - `"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"` - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `ConversationTag object { id, name, type }` - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` ### Example ```http curl https://do.featurebase.app/v2/tags/$ID \ -H "Authorization: Bearer $FEATUREBASE_API_KEY" ``` #### Response ```json { "id": "67ec1234abcd5678ef901234", "name": "Churn", "type": "tag" } ``` ## Delete a tag **delete** `/v2/tags/{id}` Deletes a conversation tag from the workspace catalog and removes it from aggregate conversation tag state. Archived and historical part applications remain part of the audit trail where applicable. ### Path Parameters - `id: string` The Featurebase tag 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` Optional admin ID for actor attribution and permission checks. ### Returns - `id: string` Unique tag identifier - `deleted: true` Whether the tag has been deleted - `true` - `object: "tag"` Object type identifier - `"tag"` ### Example ```http curl https://do.featurebase.app/v2/tags/$ID \ -X DELETE \ -H "Authorization: Bearer $FEATUREBASE_API_KEY" ``` #### Response ```json { "id": "67ec1234abcd5678ef901234", "deleted": true, "object": "tag" } ``` ## Domain Types ### Conversation Tag - `ConversationTag object { id, name, type }` - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` ### Conversation Tag List Response - `ConversationTagListResponse object { data, nextCursor, object }` - `data: array of ConversationTag` Array containing the actual response elements - `id: string` Unique tag identifier - `name: string` Current tag name - `type: "tag"` Object type identifier for a tag - `"tag"` - `nextCursor: string` Cursor to use for fetching the next page. Null if there are no more results. - `object: "list"` String representing the object type - `"list"` ### Conversation Tag Delete Response - `ConversationTagDeleteResponse object { id, deleted, object }` - `id: string` Unique tag identifier - `deleted: true` Whether the tag has been deleted - `true` - `object: "tag"` Object type identifier - `"tag"` # Tickets ## List tickets **get** `/v2/tickets` Returns a list of tickets in your organization using cursor-based pagination. ### Query Parameters | Parameter | Type | Description | | ------------------- | -------- | ---------------------------------------------------------------- | | `limit` | number | Number of tickets to return (1-100, default 10) | | `cursor` | string | Cursor from previous response for pagination | | `ticketCategoryIds` | string[] | Filter by ticket category IDs | | `statusIds` | string[] | Filter by status IDs | | `q` | string | Search query | | `assigneeId` | string | Filter by assignee ID | | `categoryType` | string | Filter by category type: "customer", "tracker", or "back-office" | | `sortBy` | string | Sort field: "date" (default), "recent", or "ticketNumber" | | `sortOrder` | string | Sort direction: "asc" or "desc" (default) | ### Response Returns a list object with `data` (array of ticket objects) and `nextCursor`. ### Query Parameters - `assigneeId: optional string` - `categoryType: optional "customer" or "tracker" or "back-office"` - `"customer"` - `"tracker"` - `"back-office"` - `cursor: optional string` An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page of results. - `limit: optional number` - `q: optional string` - `sortBy: optional "date" or "recent" or "ticketNumber"` - `"date"` - `"recent"` - `"ticketNumber"` - `sortOrder: optional "asc" or "desc"` - `"asc"` - `"desc"` - `statusIds: optional array of string` - `ticketCategoryIds: optional array of string` ### Header Parameters - `"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"` - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `data: array of Ticket` Array of tickets - `id: string` Unique identifier (MongoDB ID) - `assigneeId: string` Assigned admin ID - `author: object { id, email, name, 2 more }` Contact who created the ticket - `id: string` Author unique identifier - `email: string` Author email - `name: string` Author display name - `profilePicture: string` Author profile picture URL - `type: "admin" or "customer" or "guest" or 3 more` Type of user - `"admin"` - `"customer"` - `"guest"` - `"integration"` - `"bot"` - `"lead"` - `categoryType: "customer" or "tracker" or "back-office"` Ticket category type - `"customer"` - `"tracker"` - `"back-office"` - `companyId: string` Associated company ID - `content: string` Ticket content/description (HTML) - `createdAt: string` ISO 8601 creation timestamp - `customFields: map[unknown]` Custom field values keyed by field ID. File-type fields contain a JSON string of { key, name, url } with a signed download URL (1 hour expiry). For allowMultiple file fields, the value is a JSON string of an array of these objects. - `integrations: object { clickup, devops, github, 3 more }` Third-party integration links - `clickup: array of object { id, title, url }` - `id: string` ClickUp task ID - `title: string` ClickUp task title - `url: string` URL to the ClickUp task - `devops: array of object { id, projectId, projectName, 2 more }` - `id: number` Azure DevOps work item ID - `projectId: string` Azure DevOps project ID - `projectName: string` Azure DevOps project name - `title: string` Work item title - `url: string` URL to the work item - `github: array of object { id, number, repositoryFullName, 3 more }` - `id: string` GitHub issue ID - `number: string` GitHub issue number - `repositoryFullName: string` Full repository name (owner/repo) - `repositoryName: string` Repository name - `title: string` GitHub issue title - `url: string` URL to the GitHub issue - `hubspot: array of object { dealAmount, dealClosed, objectId, type }` - `dealAmount: number` Deal amount (for DEAL type) - `dealClosed: boolean` Whether the deal is closed (for DEAL type) - `objectId: number` HubSpot object ID - `type: "TICKET" or "DEAL" or "CONTACT"` HubSpot object type - `"TICKET"` - `"DEAL"` - `"CONTACT"` - `jira: array of object { issueId, issueUrl }` - `issueId: string` Jira issue ID - `issueUrl: string` URL to the Jira issue - `linear: array of object { issueId, issueUrl }` - `issueId: string` Linear issue ID - `issueUrl: string` URL to the Linear issue - `linkedConversations: array of object { id, role }` Linked conversations - `id: string` Conversation ID - `role: "customer" or "tracker" or "back-office"` Link role - `"customer"` - `"tracker"` - `"back-office"` - `object: "ticket"` Object type identifier - `"ticket"` - `open: boolean` Whether the ticket is open - `snoozedUntil: string` ISO 8601 timestamp until snoozed (from linked conversation) - `status: PostStatus` Current ticket status - `id: string` Unique identifier - `color: string` Color for UI display - `isDefault: boolean` Whether this is the default status for new posts - `name: string` Display name - `object: "post_status"` Object type identifier - `"post_status"` - `type: "reviewing" or "unstarted" or "active" or 2 more` The workflow stage this status represents - `"reviewing"` - `"unstarted"` - `"active"` - `"completed"` - `"canceled"` - `teamAssigneeId: string` Assigned team ID (from linked conversation) - `ticketCategoryId: string` Ticket category ID - `ticketNumber: number` Sequential display ID (e.g. TK-42) - `ticketUrl: string` Full URL to view the ticket - `title: string` Ticket title - `updatedAt: string` ISO 8601 last updated timestamp - `conversationParts: optional array of ConversationPart` Conversation message history. Only included when fetching a single ticket 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 - `"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 - `nextCursor: string` Cursor for fetching the next page - `object: "list"` Object type identifier - `"list"` ### Example ```http curl https://do.featurebase.app/v2/tickets \ -H "Authorization: Bearer $FEATUREBASE_API_KEY" ``` #### Response ```json { "data": [ { "id": "507f1f77bcf86cd799439011", "assigneeId": "507f1f77bcf86cd799439013", "author": { "id": "507f1f77bcf86cd799439011", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/john.png", "type": "customer" }, "categoryType": "customer", "companyId": "507f1f77bcf86cd799439015", "content": "I get a 403 error when logging in.
", "createdAt": "2025-01-15T10:30:00.000Z", "customFields": { "priority": "bar", "507f1f77bcf86cd799439099": "bar" }, "integrations": { "clickup": [ { "id": "86a1b2c3d", "title": "Fix login bug", "url": "https://app.clickup.com/t/86a1b2c3d" } ], "devops": [ { "id": 789, "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "projectName": "My Project", "title": "Implement SSO", "url": "https://dev.azure.com/org/project/_workitems/edit/789" } ], "github": [ { "id": "1234567890", "number": "42", "repositoryFullName": "acme/frontend", "repositoryName": "frontend", "title": "Login page returns 403", "url": "https://github.com/acme/frontend/issues/42" } ], "hubspot": [ { "dealAmount": 5000, "dealClosed": false, "objectId": 12345, "type": "DEAL" } ], "jira": [ { "issueId": "PROJ-456", "issueUrl": "https://company.atlassian.net/browse/PROJ-456" } ], "linear": [ { "issueId": "LIN-123", "issueUrl": "https://linear.app/team/issue/LIN-123" } ] }, "linkedConversations": [ { "id": "507f1f77bcf86cd799439011", "role": "customer" } ], "object": "ticket", "open": true, "snoozedUntil": "2025-01-16T09:00:00.000Z", "status": { "id": "507f1f77bcf86cd799439011", "color": "Blue", "isDefault": false, "name": "In Progress", "object": "post_status", "type": "active" }, "teamAssigneeId": "507f1f77bcf86cd799439014", "ticketCategoryId": "507f1f77bcf86cd799439011", "ticketNumber": 42, "ticketUrl": "https://feedback.example.com/p/cannot-login", "title": "Cannot login to dashboard", "updatedAt": "2025-01-15T12:30:00.000Z", "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" } } ] } ] } ], "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9", "object": "list" } ``` ## Create a ticket **post** `/v2/tickets` Creates a new ticket. ### Required Fields | Field | Type | Description | | ------------------ | ------ | ------------------------------------------------------------- | | `ticketCategoryId` | string | Ticket category ID | | `title` | string | Ticket title (min 2 characters) | | `author` | object | Author/contact info (id, userId, email, name, profilePicture) | ### Optional Fields | Field | Type | Description | | ---------------------- | ------- | ------------------------------------------ | | `content` | string | Ticket description (HTML) | | `customFields` | object | Custom field values | | `companyId` | string | Company to associate | | `linkedConversationId` | string | Conversation to link | | `assigneeId` | string | Admin to assign | | `statusId` | string | Initial status | | `createdAt` | string | ISO 8601 timestamp for backdating | | `skipNotifications` | boolean | Skip sending notifications (default false) | ### File Custom Fields File-type custom fields can be provided in two ways: **Method 1: Multipart upload** — Send the request as `multipart/form-data`. Put the JSON body in a field named `data`, and attach files with field names like `customFields.I get a 403 error when logging in.
", "createdAt": "2025-01-15T10:30:00.000Z", "linkedConversationId": "507f1f77bcf86cd799439012", "statusId": "507f1f77bcf86cd799439016" }' ``` #### Response ```json { "id": "507f1f77bcf86cd799439011", "assigneeId": "507f1f77bcf86cd799439013", "author": { "id": "507f1f77bcf86cd799439011", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/john.png", "type": "customer" }, "categoryType": "customer", "companyId": "507f1f77bcf86cd799439015", "content": "I get a 403 error when logging in.
", "createdAt": "2025-01-15T10:30:00.000Z", "customFields": { "priority": "bar", "507f1f77bcf86cd799439099": "bar" }, "integrations": { "clickup": [ { "id": "86a1b2c3d", "title": "Fix login bug", "url": "https://app.clickup.com/t/86a1b2c3d" } ], "devops": [ { "id": 789, "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "projectName": "My Project", "title": "Implement SSO", "url": "https://dev.azure.com/org/project/_workitems/edit/789" } ], "github": [ { "id": "1234567890", "number": "42", "repositoryFullName": "acme/frontend", "repositoryName": "frontend", "title": "Login page returns 403", "url": "https://github.com/acme/frontend/issues/42" } ], "hubspot": [ { "dealAmount": 5000, "dealClosed": false, "objectId": 12345, "type": "DEAL" } ], "jira": [ { "issueId": "PROJ-456", "issueUrl": "https://company.atlassian.net/browse/PROJ-456" } ], "linear": [ { "issueId": "LIN-123", "issueUrl": "https://linear.app/team/issue/LIN-123" } ] }, "linkedConversations": [ { "id": "507f1f77bcf86cd799439011", "role": "customer" } ], "object": "ticket", "open": true, "snoozedUntil": "2025-01-16T09:00:00.000Z", "status": { "id": "507f1f77bcf86cd799439011", "color": "Blue", "isDefault": false, "name": "In Progress", "object": "post_status", "type": "active" }, "teamAssigneeId": "507f1f77bcf86cd799439014", "ticketCategoryId": "507f1f77bcf86cd799439011", "ticketNumber": 42, "ticketUrl": "https://feedback.example.com/p/cannot-login", "title": "Cannot login to dashboard", "updatedAt": "2025-01-15T12:30:00.000Z", "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" } } ] } ] } ``` ## Get a ticket **get** `/v2/tickets/{id}` Retrieves a single ticket by its ticket number. ### Path Parameters - `id` - The ticket number (e.g. 42 from TK-42) ### Response Returns the ticket object, including `conversationParts` from the linked conversation (message history). ### Path Parameters - `id: number` ### Header Parameters - `"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"` - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `Ticket object { id, assigneeId, author, 18 more }` - `id: string` Unique identifier (MongoDB ID) - `assigneeId: string` Assigned admin ID - `author: object { id, email, name, 2 more }` Contact who created the ticket - `id: string` Author unique identifier - `email: string` Author email - `name: string` Author display name - `profilePicture: string` Author profile picture URL - `type: "admin" or "customer" or "guest" or 3 more` Type of user - `"admin"` - `"customer"` - `"guest"` - `"integration"` - `"bot"` - `"lead"` - `categoryType: "customer" or "tracker" or "back-office"` Ticket category type - `"customer"` - `"tracker"` - `"back-office"` - `companyId: string` Associated company ID - `content: string` Ticket content/description (HTML) - `createdAt: string` ISO 8601 creation timestamp - `customFields: map[unknown]` Custom field values keyed by field ID. File-type fields contain a JSON string of { key, name, url } with a signed download URL (1 hour expiry). For allowMultiple file fields, the value is a JSON string of an array of these objects. - `integrations: object { clickup, devops, github, 3 more }` Third-party integration links - `clickup: array of object { id, title, url }` - `id: string` ClickUp task ID - `title: string` ClickUp task title - `url: string` URL to the ClickUp task - `devops: array of object { id, projectId, projectName, 2 more }` - `id: number` Azure DevOps work item ID - `projectId: string` Azure DevOps project ID - `projectName: string` Azure DevOps project name - `title: string` Work item title - `url: string` URL to the work item - `github: array of object { id, number, repositoryFullName, 3 more }` - `id: string` GitHub issue ID - `number: string` GitHub issue number - `repositoryFullName: string` Full repository name (owner/repo) - `repositoryName: string` Repository name - `title: string` GitHub issue title - `url: string` URL to the GitHub issue - `hubspot: array of object { dealAmount, dealClosed, objectId, type }` - `dealAmount: number` Deal amount (for DEAL type) - `dealClosed: boolean` Whether the deal is closed (for DEAL type) - `objectId: number` HubSpot object ID - `type: "TICKET" or "DEAL" or "CONTACT"` HubSpot object type - `"TICKET"` - `"DEAL"` - `"CONTACT"` - `jira: array of object { issueId, issueUrl }` - `issueId: string` Jira issue ID - `issueUrl: string` URL to the Jira issue - `linear: array of object { issueId, issueUrl }` - `issueId: string` Linear issue ID - `issueUrl: string` URL to the Linear issue - `linkedConversations: array of object { id, role }` Linked conversations - `id: string` Conversation ID - `role: "customer" or "tracker" or "back-office"` Link role - `"customer"` - `"tracker"` - `"back-office"` - `object: "ticket"` Object type identifier - `"ticket"` - `open: boolean` Whether the ticket is open - `snoozedUntil: string` ISO 8601 timestamp until snoozed (from linked conversation) - `status: PostStatus` Current ticket status - `id: string` Unique identifier - `color: string` Color for UI display - `isDefault: boolean` Whether this is the default status for new posts - `name: string` Display name - `object: "post_status"` Object type identifier - `"post_status"` - `type: "reviewing" or "unstarted" or "active" or 2 more` The workflow stage this status represents - `"reviewing"` - `"unstarted"` - `"active"` - `"completed"` - `"canceled"` - `teamAssigneeId: string` Assigned team ID (from linked conversation) - `ticketCategoryId: string` Ticket category ID - `ticketNumber: number` Sequential display ID (e.g. TK-42) - `ticketUrl: string` Full URL to view the ticket - `title: string` Ticket title - `updatedAt: string` ISO 8601 last updated timestamp - `conversationParts: optional array of ConversationPart` Conversation message history. Only included when fetching a single ticket 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 - `"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/tickets/$ID \ -H "Authorization: Bearer $FEATUREBASE_API_KEY" ``` #### Response ```json { "id": "507f1f77bcf86cd799439011", "assigneeId": "507f1f77bcf86cd799439013", "author": { "id": "507f1f77bcf86cd799439011", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/john.png", "type": "customer" }, "categoryType": "customer", "companyId": "507f1f77bcf86cd799439015", "content": "I get a 403 error when logging in.
", "createdAt": "2025-01-15T10:30:00.000Z", "customFields": { "priority": "bar", "507f1f77bcf86cd799439099": "bar" }, "integrations": { "clickup": [ { "id": "86a1b2c3d", "title": "Fix login bug", "url": "https://app.clickup.com/t/86a1b2c3d" } ], "devops": [ { "id": 789, "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "projectName": "My Project", "title": "Implement SSO", "url": "https://dev.azure.com/org/project/_workitems/edit/789" } ], "github": [ { "id": "1234567890", "number": "42", "repositoryFullName": "acme/frontend", "repositoryName": "frontend", "title": "Login page returns 403", "url": "https://github.com/acme/frontend/issues/42" } ], "hubspot": [ { "dealAmount": 5000, "dealClosed": false, "objectId": 12345, "type": "DEAL" } ], "jira": [ { "issueId": "PROJ-456", "issueUrl": "https://company.atlassian.net/browse/PROJ-456" } ], "linear": [ { "issueId": "LIN-123", "issueUrl": "https://linear.app/team/issue/LIN-123" } ] }, "linkedConversations": [ { "id": "507f1f77bcf86cd799439011", "role": "customer" } ], "object": "ticket", "open": true, "snoozedUntil": "2025-01-16T09:00:00.000Z", "status": { "id": "507f1f77bcf86cd799439011", "color": "Blue", "isDefault": false, "name": "In Progress", "object": "post_status", "type": "active" }, "teamAssigneeId": "507f1f77bcf86cd799439014", "ticketCategoryId": "507f1f77bcf86cd799439011", "ticketNumber": 42, "ticketUrl": "https://feedback.example.com/p/cannot-login", "title": "Cannot login to dashboard", "updatedAt": "2025-01-15T12:30:00.000Z", "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" } } ] } ] } ``` ## Update a ticket **patch** `/v2/tickets/{id}` Updates a ticket's properties. Only provided fields will be updated. ### Path Parameters - `id` - The ticket number ### Request Body All fields are optional. | Field | Type | Description | | ------------------- | ----------- | -------------------------------------------------- | | `title` | string | Update title | | `content` | string | Update description (HTML) | | `statusId` | string | Set status by ID | | `open` | boolean | Close (false) or reopen (true) the ticket | | `assigneeId` | string/null | Assign/unassign admin | | `companyId` | string/null | Update company association | | `customFields` | object | Update custom field values | | `snoozedUntil` | string/null | Snooze until ISO 8601 timestamp (null to unsnooze) | | `skipNotifications` | boolean | Skip notifications (default false) | ### Closing a Ticket Set `open: false` to close the ticket. Closing a ticket will also unsnooze it. The status is not changed automatically — use `statusId` to change the status explicitly. ### File Custom Fields File-type custom fields support the same two upload methods as ticket creation: multipart upload (`customFields.Updated description.
", "snoozedUntil": "2025-01-16T09:00:00.000Z", "statusId": "507f1f77bcf86cd799439016", "title": "Updated ticket title" }' ``` #### Response ```json { "id": "507f1f77bcf86cd799439011", "assigneeId": "507f1f77bcf86cd799439013", "author": { "id": "507f1f77bcf86cd799439011", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/john.png", "type": "customer" }, "categoryType": "customer", "companyId": "507f1f77bcf86cd799439015", "content": "I get a 403 error when logging in.
", "createdAt": "2025-01-15T10:30:00.000Z", "customFields": { "priority": "bar", "507f1f77bcf86cd799439099": "bar" }, "integrations": { "clickup": [ { "id": "86a1b2c3d", "title": "Fix login bug", "url": "https://app.clickup.com/t/86a1b2c3d" } ], "devops": [ { "id": 789, "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "projectName": "My Project", "title": "Implement SSO", "url": "https://dev.azure.com/org/project/_workitems/edit/789" } ], "github": [ { "id": "1234567890", "number": "42", "repositoryFullName": "acme/frontend", "repositoryName": "frontend", "title": "Login page returns 403", "url": "https://github.com/acme/frontend/issues/42" } ], "hubspot": [ { "dealAmount": 5000, "dealClosed": false, "objectId": 12345, "type": "DEAL" } ], "jira": [ { "issueId": "PROJ-456", "issueUrl": "https://company.atlassian.net/browse/PROJ-456" } ], "linear": [ { "issueId": "LIN-123", "issueUrl": "https://linear.app/team/issue/LIN-123" } ] }, "linkedConversations": [ { "id": "507f1f77bcf86cd799439011", "role": "customer" } ], "object": "ticket", "open": true, "snoozedUntil": "2025-01-16T09:00:00.000Z", "status": { "id": "507f1f77bcf86cd799439011", "color": "Blue", "isDefault": false, "name": "In Progress", "object": "post_status", "type": "active" }, "teamAssigneeId": "507f1f77bcf86cd799439014", "ticketCategoryId": "507f1f77bcf86cd799439011", "ticketNumber": 42, "ticketUrl": "https://feedback.example.com/p/cannot-login", "title": "Cannot login to dashboard", "updatedAt": "2025-01-15T12:30:00.000Z", "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" } } ] } ] } ``` ## Delete a ticket **delete** `/v2/tickets/{id}` Permanently deletes a ticket by its ticket number. ### Path Parameters - `id` - The ticket number ### Response Returns a deletion confirmation: ```json { "id": "507f1f77bcf86cd799439011", "object": "ticket", "deleted": true } ``` ### Behavior - **Customer-facing tickets**: Deletes the ticket and its linked conversation. - **Back-office / tracker tickets**: Deletes the ticket and unlinks it from the conversation (conversation is preserved). ### Caution This operation is **irreversible**. ### Path Parameters - `id: number` ### 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 ticket - `deleted: true` Indicates the resource was deleted - `true` - `object: "ticket"` Object type identifier - `"ticket"` ### Example ```http curl https://do.featurebase.app/v2/tickets/$ID \ -X DELETE \ -H "Authorization: Bearer $FEATUREBASE_API_KEY" ``` #### Response ```json { "id": "507f1f77bcf86cd799439011", "deleted": true, "object": "ticket" } ``` ## Reply to a ticket **post** `/v2/tickets/{id}/reply` Adds a reply to a ticket's linked conversation. Supports both contact and admin replies. ### Path Parameters - `id` - The ticket number ### Contact Reply | Field | Type | Required | Description | | ------------------- | -------- | -------- | ---------------------------------------- | | `type` | string | Yes | Must be "contact" | | `contactId` | string | No* | Featurebase contact ID | | `contactEmail` | string | No* | Contact email | | `body` | string | Yes | Message content (HTML) | | `messageType` | string | No | Always "comment" for contacts | | `attachmentUrls` | string[] | No | Attachment URLs (max 10) | | `skipNotifications` | boolean | No | Skip notifications (default false) | | `createdAt` | string | No | ISO 8601 timestamp to backdate the reply | \*At least one of `contactId` or `contactEmail` is required. ### Admin Reply | Field | Type | Required | Description | | ------------------- | -------- | -------- | ------------------------------------------------ | | `type` | string | Yes | Must be "admin" | | `adminId` | string | Yes | ID of the admin authoring the reply | | `body` | string | Yes | Message content (HTML) | | `messageType` | string | No | "comment" (default) or "note" for internal notes | | `attachmentUrls` | string[] | No | Attachment URLs (max 10) | | `skipNotifications` | boolean | No | Skip notifications (default false) | | `createdAt` | string | No | ISO 8601 timestamp to backdate the reply | ### Response Returns a reply confirmation object. ### Path Parameters - `id: number` ### 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 { body, type, attachmentUrls, 5 more } or object { adminId, body, type, 4 more }` - `object { body, type, attachmentUrls, 5 more }` - `body: string` - `type: "contact"` - `"contact"` - `attachmentUrls: optional array of string` - `contactEmail: optional string` - `contactId: optional string` - `createdAt: optional string` - `messageType: optional "comment"` - `"comment"` - `skipNotifications: optional boolean` - `object { adminId, body, type, 4 more }` - `adminId: string` - `body: string` - `type: "admin"` - `"admin"` - `attachmentUrls: optional array of string` - `createdAt: optional string` - `messageType: optional "comment" or "note"` - `"comment"` - `"note"` - `skipNotifications: optional boolean` ### Returns - `Ticket object { id, assigneeId, author, 18 more }` - `id: string` Unique identifier (MongoDB ID) - `assigneeId: string` Assigned admin ID - `author: object { id, email, name, 2 more }` Contact who created the ticket - `id: string` Author unique identifier - `email: string` Author email - `name: string` Author display name - `profilePicture: string` Author profile picture URL - `type: "admin" or "customer" or "guest" or 3 more` Type of user - `"admin"` - `"customer"` - `"guest"` - `"integration"` - `"bot"` - `"lead"` - `categoryType: "customer" or "tracker" or "back-office"` Ticket category type - `"customer"` - `"tracker"` - `"back-office"` - `companyId: string` Associated company ID - `content: string` Ticket content/description (HTML) - `createdAt: string` ISO 8601 creation timestamp - `customFields: map[unknown]` Custom field values keyed by field ID. File-type fields contain a JSON string of { key, name, url } with a signed download URL (1 hour expiry). For allowMultiple file fields, the value is a JSON string of an array of these objects. - `integrations: object { clickup, devops, github, 3 more }` Third-party integration links - `clickup: array of object { id, title, url }` - `id: string` ClickUp task ID - `title: string` ClickUp task title - `url: string` URL to the ClickUp task - `devops: array of object { id, projectId, projectName, 2 more }` - `id: number` Azure DevOps work item ID - `projectId: string` Azure DevOps project ID - `projectName: string` Azure DevOps project name - `title: string` Work item title - `url: string` URL to the work item - `github: array of object { id, number, repositoryFullName, 3 more }` - `id: string` GitHub issue ID - `number: string` GitHub issue number - `repositoryFullName: string` Full repository name (owner/repo) - `repositoryName: string` Repository name - `title: string` GitHub issue title - `url: string` URL to the GitHub issue - `hubspot: array of object { dealAmount, dealClosed, objectId, type }` - `dealAmount: number` Deal amount (for DEAL type) - `dealClosed: boolean` Whether the deal is closed (for DEAL type) - `objectId: number` HubSpot object ID - `type: "TICKET" or "DEAL" or "CONTACT"` HubSpot object type - `"TICKET"` - `"DEAL"` - `"CONTACT"` - `jira: array of object { issueId, issueUrl }` - `issueId: string` Jira issue ID - `issueUrl: string` URL to the Jira issue - `linear: array of object { issueId, issueUrl }` - `issueId: string` Linear issue ID - `issueUrl: string` URL to the Linear issue - `linkedConversations: array of object { id, role }` Linked conversations - `id: string` Conversation ID - `role: "customer" or "tracker" or "back-office"` Link role - `"customer"` - `"tracker"` - `"back-office"` - `object: "ticket"` Object type identifier - `"ticket"` - `open: boolean` Whether the ticket is open - `snoozedUntil: string` ISO 8601 timestamp until snoozed (from linked conversation) - `status: PostStatus` Current ticket status - `id: string` Unique identifier - `color: string` Color for UI display - `isDefault: boolean` Whether this is the default status for new posts - `name: string` Display name - `object: "post_status"` Object type identifier - `"post_status"` - `type: "reviewing" or "unstarted" or "active" or 2 more` The workflow stage this status represents - `"reviewing"` - `"unstarted"` - `"active"` - `"completed"` - `"canceled"` - `teamAssigneeId: string` Assigned team ID (from linked conversation) - `ticketCategoryId: string` Ticket category ID - `ticketNumber: number` Sequential display ID (e.g. TK-42) - `ticketUrl: string` Full URL to view the ticket - `title: string` Ticket title - `updatedAt: string` ISO 8601 last updated timestamp - `conversationParts: optional array of ConversationPart` Conversation message history. Only included when fetching a single ticket 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 - `"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/tickets/$ID/reply \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $FEATUREBASE_API_KEY" \ -d '{ "body": "Thank you for your help!
", "type": "contact", "contactEmail": "john@example.com", "contactId": "507f1f77bcf86cd799439011", "createdAt": "2025-01-15T10:30:00.000Z", "messageType": "comment" }' ``` #### Response ```json { "id": "507f1f77bcf86cd799439011", "assigneeId": "507f1f77bcf86cd799439013", "author": { "id": "507f1f77bcf86cd799439011", "email": "john@example.com", "name": "John Doe", "profilePicture": "https://cdn.example.com/avatars/john.png", "type": "customer" }, "categoryType": "customer", "companyId": "507f1f77bcf86cd799439015", "content": "I get a 403 error when logging in.
", "createdAt": "2025-01-15T10:30:00.000Z", "customFields": { "priority": "bar", "507f1f77bcf86cd799439099": "bar" }, "integrations": { "clickup": [ { "id": "86a1b2c3d", "title": "Fix login bug", "url": "https://app.clickup.com/t/86a1b2c3d" } ], "devops": [ { "id": 789, "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "projectName": "My Project", "title": "Implement SSO", "url": "https://dev.azure.com/org/project/_workitems/edit/789" } ], "github": [ { "id": "1234567890", "number": "42", "repositoryFullName": "acme/frontend", "repositoryName": "frontend", "title": "Login page returns 403", "url": "https://github.com/acme/frontend/issues/42" } ], "hubspot": [ { "dealAmount": 5000, "dealClosed": false, "objectId": 12345, "type": "DEAL" } ], "jira": [ { "issueId": "PROJ-456", "issueUrl": "https://company.atlassian.net/browse/PROJ-456" } ], "linear": [ { "issueId": "LIN-123", "issueUrl": "https://linear.app/team/issue/LIN-123" } ] }, "linkedConversations": [ { "id": "507f1f77bcf86cd799439011", "role": "customer" } ], "object": "ticket", "open": true, "snoozedUntil": "2025-01-16T09:00:00.000Z", "status": { "id": "507f1f77bcf86cd799439011", "color": "Blue", "isDefault": false, "name": "In Progress", "object": "post_status", "type": "active" }, "teamAssigneeId": "507f1f77bcf86cd799439014", "ticketCategoryId": "507f1f77bcf86cd799439011", "ticketNumber": 42, "ticketUrl": "https://feedback.example.com/p/cannot-login", "title": "Cannot login to dashboard", "updatedAt": "2025-01-15T12:30:00.000Z", "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" } } ] } ] } ``` ## Domain Types ### Author Input - `AuthorInput object { id, email, name, 2 more }` Author to attribute the post to. If not provided, uses the authenticated user. Supports multiple identification methods: id (Featurebase ID), userId (external SSO ID), or email. - `id: optional string` Featurebase user ID to attribute content to - `email: optional string` Author email (used to find or create user) - `name: optional string` Author display name - `profilePicture: optional string` Author profile picture URL - `userId: optional string` External user ID from your system (matched via SSO) ### Ticket - `Ticket object { id, assigneeId, author, 18 more }` - `id: string` Unique identifier (MongoDB ID) - `assigneeId: string` Assigned admin ID - `author: object { id, email, name, 2 more }` Contact who created the ticket - `id: string` Author unique identifier - `email: string` Author email - `name: string` Author display name - `profilePicture: string` Author profile picture URL - `type: "admin" or "customer" or "guest" or 3 more` Type of user - `"admin"` - `"customer"` - `"guest"` - `"integration"` - `"bot"` - `"lead"` - `categoryType: "customer" or "tracker" or "back-office"` Ticket category type - `"customer"` - `"tracker"` - `"back-office"` - `companyId: string` Associated company ID - `content: string` Ticket content/description (HTML) - `createdAt: string` ISO 8601 creation timestamp - `customFields: map[unknown]` Custom field values keyed by field ID. File-type fields contain a JSON string of { key, name, url } with a signed download URL (1 hour expiry). For allowMultiple file fields, the value is a JSON string of an array of these objects. - `integrations: object { clickup, devops, github, 3 more }` Third-party integration links - `clickup: array of object { id, title, url }` - `id: string` ClickUp task ID - `title: string` ClickUp task title - `url: string` URL to the ClickUp task - `devops: array of object { id, projectId, projectName, 2 more }` - `id: number` Azure DevOps work item ID - `projectId: string` Azure DevOps project ID - `projectName: string` Azure DevOps project name - `title: string` Work item title - `url: string` URL to the work item - `github: array of object { id, number, repositoryFullName, 3 more }` - `id: string` GitHub issue ID - `number: string` GitHub issue number - `repositoryFullName: string` Full repository name (owner/repo) - `repositoryName: string` Repository name - `title: string` GitHub issue title - `url: string` URL to the GitHub issue - `hubspot: array of object { dealAmount, dealClosed, objectId, type }` - `dealAmount: number` Deal amount (for DEAL type) - `dealClosed: boolean` Whether the deal is closed (for DEAL type) - `objectId: number` HubSpot object ID - `type: "TICKET" or "DEAL" or "CONTACT"` HubSpot object type - `"TICKET"` - `"DEAL"` - `"CONTACT"` - `jira: array of object { issueId, issueUrl }` - `issueId: string` Jira issue ID - `issueUrl: string` URL to the Jira issue - `linear: array of object { issueId, issueUrl }` - `issueId: string` Linear issue ID - `issueUrl: string` URL to the Linear issue - `linkedConversations: array of object { id, role }` Linked conversations - `id: string` Conversation ID - `role: "customer" or "tracker" or "back-office"` Link role - `"customer"` - `"tracker"` - `"back-office"` - `object: "ticket"` Object type identifier - `"ticket"` - `open: boolean` Whether the ticket is open - `snoozedUntil: string` ISO 8601 timestamp until snoozed (from linked conversation) - `status: PostStatus` Current ticket status - `id: string` Unique identifier - `color: string` Color for UI display - `isDefault: boolean` Whether this is the default status for new posts - `name: string` Display name - `object: "post_status"` Object type identifier - `"post_status"` - `type: "reviewing" or "unstarted" or "active" or 2 more` The workflow stage this status represents - `"reviewing"` - `"unstarted"` - `"active"` - `"completed"` - `"canceled"` - `teamAssigneeId: string` Assigned team ID (from linked conversation) - `ticketCategoryId: string` Ticket category ID - `ticketNumber: number` Sequential display ID (e.g. TK-42) - `ticketUrl: string` Full URL to view the ticket - `title: string` Ticket title - `updatedAt: string` ISO 8601 last updated timestamp - `conversationParts: optional array of ConversationPart` Conversation message history. Only included when fetching a single ticket 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 - `"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 ### Ticket Delete Response - `TicketDeleteResponse object { id, deleted, object }` - `id: string` Unique identifier of the deleted ticket - `deleted: true` Indicates the resource was deleted - `true` - `object: "ticket"` Object type identifier - `"ticket"` # Custom Fields ## List custom fields **get** `/v2/tickets/custom_fields` Returns all custom fields configured in your organization that can be used on tickets. This endpoint returns all custom fields at once. No pagination is supported. ### Custom Field Object Each custom field includes: - `id` - Unique field identifier - `label` - Field label displayed to users - `type` - Field type (text, number, select, multi-select, checkbox, date, file) - `required` - Whether the field is required - `placeholder` - Placeholder text (for text/number fields) - `public` - Whether the field value is publicly visible - `internal` - Whether the field is for internal use only - `options` - Array of options (for select/multi-select fields) - `allowMultiple` - Whether multiple files can be uploaded (file fields only) ### Header Parameters - `"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"` - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `CustomFieldList object { data, nextCursor, object, pagination }` - `data: array of CustomField` Array of custom fields - `id: string` Unique identifier - `label: string` Field label displayed to users - `object: "custom_field"` Object type identifier - `"custom_field"` - `type: "text" or "number" or "select" or 4 more` Field type - `"text"` - `"number"` - `"select"` - `"multi-select"` - `"checkbox"` - `"date"` - `"file"` - `allowMultiple: optional boolean` Whether multiple files can be uploaded (file fields only) - `createdAt: optional string` ISO timestamp when created - `internal: optional boolean` Whether the field is for internal use only - `options: optional array of object { id, label }` Options for select/multi-select fields - `id: string` Option unique identifier - `label: string` Option display label - `placeholder: optional string` Placeholder text - `public: optional boolean` Whether the field value is publicly visible - `required: optional boolean` Whether the field is required - `updatedAt: optional string` ISO timestamp when last updated - `nextCursor: string` Cursor for fetching the next page (cursor-based pagination) - `object: "list"` Object type identifier - `"list"` - `pagination: optional object { limit, page, total, totalPages }` Pagination metadata for page-based requests - `limit: number` Items per page - `page: number` Current page number - `total: number` Total number of items - `totalPages: number` Total number of pages ### Example ```http curl https://do.featurebase.app/v2/tickets/custom_fields \ -H "Authorization: Bearer $FEATUREBASE_API_KEY" ``` #### Response ```json { "data": [ { "id": "65d26304b2e65b1e1278170c", "label": "Your @username", "object": "custom_field", "type": "text", "allowMultiple": false, "createdAt": "2025-04-06T14:11:58.141Z", "internal": false, "options": [ { "id": "65d26304b2e65b1e1278170d", "label": "High Priority" } ], "placeholder": "Enter your username", "public": false, "required": true, "updatedAt": "2025-04-06T14:11:58.141Z" } ], "nextCursor": null, "object": "list", "pagination": { "limit": 10, "page": 1, "total": 42, "totalPages": 5 } } ``` ## Get a custom field by ID **get** `/v2/tickets/custom_fields/{id}` Retrieves a single custom field by its unique identifier. ### Response Returns a custom field object with: - `id` - Unique field identifier - `label` - Field label displayed to users - `type` - Field type (text, number, select, multi-select, checkbox, date, file) - `required` - Whether the field is required - `placeholder` - Placeholder text (for text/number fields) - `public` - Whether the field value is publicly visible - `internal` - Whether the field is for internal use only - `options` - Array of options (for select/multi-select fields) - `allowMultiple` - Whether multiple files can be uploaded (file fields only) ### Path Parameters - `id: string` Custom field unique identifier ### Header Parameters - `"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"` - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `CustomField object { id, label, object, 9 more }` - `id: string` Unique identifier - `label: string` Field label displayed to users - `object: "custom_field"` Object type identifier - `"custom_field"` - `type: "text" or "number" or "select" or 4 more` Field type - `"text"` - `"number"` - `"select"` - `"multi-select"` - `"checkbox"` - `"date"` - `"file"` - `allowMultiple: optional boolean` Whether multiple files can be uploaded (file fields only) - `createdAt: optional string` ISO timestamp when created - `internal: optional boolean` Whether the field is for internal use only - `options: optional array of object { id, label }` Options for select/multi-select fields - `id: string` Option unique identifier - `label: string` Option display label - `placeholder: optional string` Placeholder text - `public: optional boolean` Whether the field value is publicly visible - `required: optional boolean` Whether the field is required - `updatedAt: optional string` ISO timestamp when last updated ### Example ```http curl https://do.featurebase.app/v2/tickets/custom_fields/$ID \ -H "Authorization: Bearer $FEATUREBASE_API_KEY" ``` #### Response ```json { "id": "65d26304b2e65b1e1278170c", "label": "Your @username", "object": "custom_field", "type": "text", "allowMultiple": false, "createdAt": "2025-04-06T14:11:58.141Z", "internal": false, "options": [ { "id": "65d26304b2e65b1e1278170d", "label": "High Priority" } ], "placeholder": "Enter your username", "public": false, "required": true, "updatedAt": "2025-04-06T14:11:58.141Z" } ``` # Categories ## List ticket categories **get** `/v2/tickets/categories` Returns all ticket categories for the authenticated organization. Ticket categories organize tickets into distinct containers. Each category can have different: - Access controls (public, private, segment-restricted) - Feature toggles (comments, posting enabled) - Custom fields Use the `supportBoard` and `supportBoardType` fields to identify ticket categories. This endpoint returns all categories without pagination. ### 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 - `access: object { adminOnly, allowedRoles, deniedRoles, segments }` - `adminOnly: boolean` If true, only admins can see this board - `allowedRoles: array of string` Role IDs allowed access (empty = all) - `deniedRoles: array of string` Role IDs explicitly denied access - `segments: array of string` Segment IDs that can access (empty = all) - `createdAt: string` ISO 8601 timestamp when created - `customFields: array of string` Custom field IDs attached to this board - `features: object { commentsEnabled, createdDatesVisible, postingEnabled }` - `commentsEnabled: boolean` Whether users can comment on posts - `createdDatesVisible: boolean` Whether creation dates are visible on posts - `postingEnabled: boolean` Whether users can create new posts - `icon: object { type, value } or object { type, value } or object { type, value }` The board's icon. Can be one of three types: - **emoji**: A single emoji character (e.g., 💡, 🚀, ⭐) - **icon**: A predefined icon from the built-in library (e.g., lightbulb, bug, star) - **url**: A custom image URL (HTTPS required) Can be `null` if no icon is set. - `EmojiIcon object { type, value }` An emoji character as the board icon - `type: "emoji"` Emoji icon type - `"emoji"` - `value: string` A single emoji character - `PredefinedIcon object { type, value }` A predefined icon from the built-in icon library - `type: "icon"` Predefined icon type - `"icon"` - `value: string` Icon name from the predefined icon set (e.g., lightbulb, bug, star, rocket, flag, heart, check, question, megaphone, gift) - `URLIcon object { type, value }` A custom icon loaded from an external URL - `type: "url"` External URL icon type - `"url"` - `value: string` HTTPS URL to a custom icon image (PNG, SVG, or WebP recommended) - `localization: object { description, formPlaceholder, heroDescription, 3 more }` - `description: map[string]` Localized description - `formPlaceholder: map[string]` Placeholder text in the post creation form - `heroDescription: map[string]` Hero description/subtitle - `heroTitle: map[string]` Hero title shown on the board page - `name: map[string]` Localized board name (language code → text) - `submitButtonText: map[string]` Submit button text - `name: string` Display name in organization's default locale - `object: "board"` Object type identifier - `"board"` - `postDefaults: object { visibility }` - `visibility: "public" or "authorOnly" or "companyOnly"` Default visibility for new posts - `"public"` - `"authorOnly"` - `"companyOnly"` ### Example ```http curl https://do.featurebase.app/v2/tickets/categories \ -H "Authorization: Bearer $FEATUREBASE_API_KEY" ``` #### Response ```json [ { "id": "507f1f77bcf86cd799439011", "access": { "adminOnly": false, "allowedRoles": [ "string" ], "deniedRoles": [ "role_blocked" ], "segments": [ "string" ] }, "createdAt": "2023-12-12T00:00:00.000Z", "customFields": [ "cf_priority", "cf_category" ], "features": { "commentsEnabled": true, "createdDatesVisible": true, "postingEnabled": true }, "icon": { "type": "emoji", "value": "💡" }, "localization": { "description": { "en": "Submit and vote on feature ideas" }, "formPlaceholder": { "en": "Describe your feature idea..." }, "heroDescription": { "foo": "string" }, "heroTitle": { "en": "Share your ideas" }, "name": { "en": "Feature Requests", "es": "Solicitudes de funciones" }, "submitButtonText": { "en": "Submit Feedback" } }, "name": "Feature Requests", "object": "board", "postDefaults": { "visibility": "public" } } ] ``` ## Get a ticket category by ID **get** `/v2/tickets/categories/{id}` Retrieves a single ticket category by its unique identifier. Returns the full category object including access controls, feature toggles, and localization settings. ### Path Parameters - `id: string` Board unique identifier ### Header Parameters - `"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"` - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `Board object { id, access, createdAt, 7 more }` - `id: string` Unique identifier - `access: object { adminOnly, allowedRoles, deniedRoles, segments }` - `adminOnly: boolean` If true, only admins can see this board - `allowedRoles: array of string` Role IDs allowed access (empty = all) - `deniedRoles: array of string` Role IDs explicitly denied access - `segments: array of string` Segment IDs that can access (empty = all) - `createdAt: string` ISO 8601 timestamp when created - `customFields: array of string` Custom field IDs attached to this board - `features: object { commentsEnabled, createdDatesVisible, postingEnabled }` - `commentsEnabled: boolean` Whether users can comment on posts - `createdDatesVisible: boolean` Whether creation dates are visible on posts - `postingEnabled: boolean` Whether users can create new posts - `icon: object { type, value } or object { type, value } or object { type, value }` The board's icon. Can be one of three types: - **emoji**: A single emoji character (e.g., 💡, 🚀, ⭐) - **icon**: A predefined icon from the built-in library (e.g., lightbulb, bug, star) - **url**: A custom image URL (HTTPS required) Can be `null` if no icon is set. - `EmojiIcon object { type, value }` An emoji character as the board icon - `type: "emoji"` Emoji icon type - `"emoji"` - `value: string` A single emoji character - `PredefinedIcon object { type, value }` A predefined icon from the built-in icon library - `type: "icon"` Predefined icon type - `"icon"` - `value: string` Icon name from the predefined icon set (e.g., lightbulb, bug, star, rocket, flag, heart, check, question, megaphone, gift) - `URLIcon object { type, value }` A custom icon loaded from an external URL - `type: "url"` External URL icon type - `"url"` - `value: string` HTTPS URL to a custom icon image (PNG, SVG, or WebP recommended) - `localization: object { description, formPlaceholder, heroDescription, 3 more }` - `description: map[string]` Localized description - `formPlaceholder: map[string]` Placeholder text in the post creation form - `heroDescription: map[string]` Hero description/subtitle - `heroTitle: map[string]` Hero title shown on the board page - `name: map[string]` Localized board name (language code → text) - `submitButtonText: map[string]` Submit button text - `name: string` Display name in organization's default locale - `object: "board"` Object type identifier - `"board"` - `postDefaults: object { visibility }` - `visibility: "public" or "authorOnly" or "companyOnly"` Default visibility for new posts - `"public"` - `"authorOnly"` - `"companyOnly"` ### Example ```http curl https://do.featurebase.app/v2/tickets/categories/$ID \ -H "Authorization: Bearer $FEATUREBASE_API_KEY" ``` #### Response ```json { "id": "507f1f77bcf86cd799439011", "access": { "adminOnly": false, "allowedRoles": [ "string" ], "deniedRoles": [ "role_blocked" ], "segments": [ "string" ] }, "createdAt": "2023-12-12T00:00:00.000Z", "customFields": [ "cf_priority", "cf_category" ], "features": { "commentsEnabled": true, "createdDatesVisible": true, "postingEnabled": true }, "icon": { "type": "emoji", "value": "💡" }, "localization": { "description": { "en": "Submit and vote on feature ideas" }, "formPlaceholder": { "en": "Describe your feature idea..." }, "heroDescription": { "foo": "string" }, "heroTitle": { "en": "Share your ideas" }, "name": { "en": "Feature Requests", "es": "Solicitudes de funciones" }, "submitButtonText": { "en": "Submit Feedback" } }, "name": "Feature Requests", "object": "board", "postDefaults": { "visibility": "public" } } ``` ## Domain Types ### Category List Response - `CategoryListResponse = array of Board` - `id: string` Unique identifier - `access: object { adminOnly, allowedRoles, deniedRoles, segments }` - `adminOnly: boolean` If true, only admins can see this board - `allowedRoles: array of string` Role IDs allowed access (empty = all) - `deniedRoles: array of string` Role IDs explicitly denied access - `segments: array of string` Segment IDs that can access (empty = all) - `createdAt: string` ISO 8601 timestamp when created - `customFields: array of string` Custom field IDs attached to this board - `features: object { commentsEnabled, createdDatesVisible, postingEnabled }` - `commentsEnabled: boolean` Whether users can comment on posts - `createdDatesVisible: boolean` Whether creation dates are visible on posts - `postingEnabled: boolean` Whether users can create new posts - `icon: object { type, value } or object { type, value } or object { type, value }` The board's icon. Can be one of three types: - **emoji**: A single emoji character (e.g., 💡, 🚀, ⭐) - **icon**: A predefined icon from the built-in library (e.g., lightbulb, bug, star) - **url**: A custom image URL (HTTPS required) Can be `null` if no icon is set. - `EmojiIcon object { type, value }` An emoji character as the board icon - `type: "emoji"` Emoji icon type - `"emoji"` - `value: string` A single emoji character - `PredefinedIcon object { type, value }` A predefined icon from the built-in icon library - `type: "icon"` Predefined icon type - `"icon"` - `value: string` Icon name from the predefined icon set (e.g., lightbulb, bug, star, rocket, flag, heart, check, question, megaphone, gift) - `URLIcon object { type, value }` A custom icon loaded from an external URL - `type: "url"` External URL icon type - `"url"` - `value: string` HTTPS URL to a custom icon image (PNG, SVG, or WebP recommended) - `localization: object { description, formPlaceholder, heroDescription, 3 more }` - `description: map[string]` Localized description - `formPlaceholder: map[string]` Placeholder text in the post creation form - `heroDescription: map[string]` Hero description/subtitle - `heroTitle: map[string]` Hero title shown on the board page - `name: map[string]` Localized board name (language code → text) - `submitButtonText: map[string]` Submit button text - `name: string` Display name in organization's default locale - `object: "board"` Object type identifier - `"board"` - `postDefaults: object { visibility }` - `visibility: "public" or "authorOnly" or "companyOnly"` Default visibility for new posts - `"public"` - `"authorOnly"` - `"companyOnly"` # Statuses ## List ticket statuses **get** `/v2/tickets/statuses` Returns all ticket statuses for the authenticated organization. Ticket statuses define workflow stages. Each status has: - A display name and color - A type indicating the workflow stage (reviewing, unstarted, active, completed, canceled) - A flag indicating if it's the default status for new tickets This endpoint returns all statuses without pagination. ### 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 - `color: string` Color for UI display - `isDefault: boolean` Whether this is the default status for new posts - `name: string` Display name - `object: "post_status"` Object type identifier - `"post_status"` - `type: "reviewing" or "unstarted" or "active" or 2 more` The workflow stage this status represents - `"reviewing"` - `"unstarted"` - `"active"` - `"completed"` - `"canceled"` ### Example ```http curl https://do.featurebase.app/v2/tickets/statuses \ -H "Authorization: Bearer $FEATUREBASE_API_KEY" ``` #### Response ```json [ { "id": "507f1f77bcf86cd799439011", "color": "Blue", "isDefault": false, "name": "In Progress", "object": "post_status", "type": "active" } ] ``` ## Get a ticket status by ID **get** `/v2/tickets/statuses/{id}` Retrieves a single ticket status by its unique identifier. Returns the status object including name, color, type, and default flag. ### Path Parameters - `id: string` Post status unique identifier ### Header Parameters - `"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"` - `"2026-01-01.nova"` - `"2025-12-12.clover"` ### Returns - `PostStatus object { id, color, isDefault, 3 more }` - `id: string` Unique identifier - `color: string` Color for UI display - `isDefault: boolean` Whether this is the default status for new posts - `name: string` Display name - `object: "post_status"` Object type identifier - `"post_status"` - `type: "reviewing" or "unstarted" or "active" or 2 more` The workflow stage this status represents - `"reviewing"` - `"unstarted"` - `"active"` - `"completed"` - `"canceled"` ### Example ```http curl https://do.featurebase.app/v2/tickets/statuses/$ID \ -H "Authorization: Bearer $FEATUREBASE_API_KEY" ``` #### Response ```json { "id": "507f1f77bcf86cd799439011", "color": "Blue", "isDefault": false, "name": "In Progress", "object": "post_status", "type": "active" } ``` ## Domain Types ### Status List Response - `StatusListResponse = array of PostStatus` - `id: string` Unique identifier - `color: string` Color for UI display - `isDefault: boolean` Whether this is the default status for new posts - `name: string` Display name - `object: "post_status"` Object type identifier - `"post_status"` - `type: "reviewing" or "unstarted" or "active" or 2 more` The workflow stage this status represents - `"reviewing"` - `"unstarted"` - `"active"` - `"completed"` - `"canceled"`