Skip to main content
Conversations

Remove a contact from a conversation

Removes a contact (customer or lead) from an existing conversation.

DELETE
/v2/conversations/{id}/participants

Note: You cannot remove the last participant from a conversation.

Path Parameters

  • id - The conversation ID (short ID)

Request Body

FieldTypeRequiredDescription
idstringYesThe Featurebase ID of the contact to remove (24-character ObjectId)
actingAdminIdstringNoAdmin ID performing the action (for attribution)

Response

Returns the updated conversation object.

Example Request

{
  "id": "676f0f6765bdaa7d7d760f88",
  "actingAdminId": "507f1f77bcf86cd799439011"
}

Example Response

{
  "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.

Authorizations

Authorizationstringheaderrequired

API key as Bearer token. Use: Authorization: Bearer sk_...

Path Parameters

idstringrequired

Conversation ID (short ID)

Required string length: 1 - 16
Pattern: ^[a-zA-Z0-9]+$
Example: 12345

Headers

Featurebase-Versionenum<string>header

API version for this request. Defaults to your organization's configured API version if not specified.

Available options: 2026-08-19.orbit, 2026-01-01.nova, 2025-12-12.clover
Example: 2026-08-19.orbit

Body

application/json
actingAdminIdstring

The admin ID performing this action. If not provided, changes are attributed to the system bot user.

Example: 507f1f77bcf86cd799439011
idstringrequired

The Featurebase ID of the contact (customer or lead) to remove

Example: 676f0f6765bdaa7d7d760f88

Response

application/json

Success

adminAssigneeIdstring | nullrequired

ID of the assigned admin

Example: 507f1f77bcf86cd799439011
awaitingCustomerReplyboolean

Whether we are awaiting a customer reply

Example: true
botConversationStateenum<string>

State of AI agent handling for this conversation

Available options: active, handed_off_to_human, resolved
Example: active
botConversationStateLastUpdatedAtstring | nullrequired

ISO timestamp when bot state last changed

Example: 2025-01-15T10:30:00.000Z
brandIdstring | nullrequired

ID of the brand associated with this conversation

Example: 507f1f77bcf86cd799439011
conversationPartsobject[]

Array of conversation parts (messages). Only included when fetching a single conversation by ID.

createdAtstringrequired

ISO timestamp when conversation was created

Example: 2025-01-15T10:30:00.000Z
csatDebugobject

Minimal CSAT diagnostics for the current effective request.

csatHistoryobject[]

Historical CSAT requests for this conversation, ordered newest first.

csatSummaryobject

Derived CSAT summary for this conversation when a rating request or rating exists.

customAttributeValuesobject[]

Custom conversation attribute values expanded with definition metadata. Returned only when include=customAttributeDefinitions is provided.

customAttributesobject

Custom conversation attributes keyed by custom attribute ID. Only org-defined, non-archived conversation attributes are returned; internal workflow metadata is omitted.

disableCustomerReplyboolean

Whether customer replies are disabled

Example: false
hasAdminOverriddenLanguagebooleanrequired

Whether an admin has manually overridden the language for this conversation. When true, automatic language detection is disabled.

Example: false
idstringrequired

Unique conversation identifier

Example: 12345
isBlockedbooleanrequired

Whether the user is blocked

Example: false
lastActivityAtstring | nullrequired

ISO timestamp of last activity

Example: 2025-01-15T12:30:00.000Z
objectenum<string>required

Object type identifier

Available options: conversation
Example: conversation
participantsobject[]required

Participants in this conversation

prioritybooleanrequired

Whether this conversation is marked as priority

Example: false
prioritySetAtstring | nullrequired

ISO timestamp when priority was set

Example: 2025-01-15T10:30:00.000Z
readReceiptsobject[]

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.

snoozedUntilstring | nullrequired

ISO timestamp until which conversation is snoozed

Example: 2025-01-16T09:00:00.000Z
sourceobject
stateenum<string>required

Current state of the conversation

Available options: open, closed, snoozed
Example: open
tagsobject[]required

Current tags applied anywhere in this conversation

teamAssigneeIdstring | nullrequired

ID of the assigned team

Example: 507f1f77bcf86cd799439012
titlestring

Conversation title

Example: Question about pricing
updatedAtstringrequired

ISO timestamp when conversation was last updated

Example: 2025-01-15T12:30:00.000Z
userPreferredLanguagestringrequired

User's preferred language

Example: en
waitingSincestring | nullrequired

ISO timestamp when conversation started waiting

Example: 2025-01-15T10:30:00.000Z

Still need help? Ask the team