# Conversations

Conversations are messenger/inbox conversations in your Featurebase organization. Use this endpoint to list and retrieve conversation information.

## List conversations

 - [GET /v2/conversations](https://docs.featurebase.app/rest-api/conversations/listconversations.md): Returns a list of conversations in your organization using cursor-based pagination.

### Query Parameters

- limit - Number of conversations to return (1-100, default 10)
- cursor - Cursor from previous response for pagination

### Response Format

Returns a list object with:
- object - Always "list"
- data - Array of conversation objects
- nextCursor - Cursor for the next page, or null if no more results

### Conversation Object

Each conversation includes:
- 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
- createdAt - Creation timestamp
- updatedAt - Last update timestamp

### Example

json
{
  "object": "list",
  "data": [
    {
      "object": "conversation",
      "id": "12345",
      "title": "Question about pricing",
      "state": "open",
      "priority": false,
      "adminAssigneeId": null,
      "participants": [
        { "type": "customer", "id": "676f0f6765bdaa7d7d760f88" }
      ],
      ...
    }
  ],
  "nextCursor": "eyJpZCI6IjEyMzQ1In0="
}


### Version Availability

This endpoint is only available in API version 2026-01-01.nova and newer.

## Create a conversation

 - [POST /v2/conversations](https://docs.featurebase.app/rest-api/conversations/createconversation.md): 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.

## Get conversation by ID

 - [GET /v2/conversations/{id}](https://docs.featurebase.app/rest-api/conversations/getconversationbyid.md): 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.

## Delete a conversation

 - [DELETE /v2/conversations/{id}](https://docs.featurebase.app/rest-api/conversations/deleteconversation.md): 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.

## Update a conversation

 - [PATCH /v2/conversations/{id}](https://docs.featurebase.app/rest-api/conversations/updateconversation.md): 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.

## Reply to a conversation

 - [POST /v2/conversations/{id}/reply](https://docs.featurebase.app/rest-api/conversations/replytoconversation.md): 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" |

*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 |

### 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.

## Add a contact to a conversation

 - [POST /v2/conversations/{id}/participants](https://docs.featurebase.app/rest-api/conversations/addparticipanttoconversation.md): 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)
2. If userId is provided, looks up by external user ID (matches customer type only)
3. 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.

## Remove a contact from a conversation

 - [DELETE /v2/conversations/{id}/participants](https://docs.featurebase.app/rest-api/conversations/removeparticipantfromconversation.md): 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.

## Redact a conversation part

 - [POST /v2/conversations/redact](https://docs.featurebase.app/rest-api/conversations/redactconversationpart.md): 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.