Conversations

Create a conversation

Creates a new conversation. Supports both contact-initiated (customer/lead) and admin-initiated (outreach) conversations.

POST

/v2/conversations

curl --request POST \
  --url https://do.featurebase.app/v2/conversations \
  --header 'Authorization: Bearer <token>' \
  --header 'Featurebase-Version: 2026-08-19.orbit' \
  --header 'Content-Type: application/json' \
  --data '
{
  "bodyMarkdown": "Hello, I have a question about your product.\n\n![screenshot](https://example.com/image.png)",
  "channel": "desktop",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "from": {
    "id": "676f0f6765bdaa7d7d760f88",
    "type": "contact"
  },
  "recipients": {
    "bcc": {
      "emails": [
        "john@example.com"
      ],
      "ids": [
        "676f0f6765bdaa7d7d760f88"
      ]
    },
    "cc": {
      "emails": [
        "john@example.com"
      ],
      "ids": [
        "676f0f6765bdaa7d7d760f88"
      ]
    },
    "to": {
      "emails": [
        "john@example.com"
      ],
      "ids": [
        "676f0f6765bdaa7d7d760f88"
      ]
    }
  },
  "skipNotifications": false,
  "subject": "Following up on your inquiry"
}
'

{
  "adminAssigneeId": "507f1f77bcf86cd799439011",
  "awaitingCustomerReply": true,
  "botConversationState": "active",
  "botConversationStateLastUpdatedAt": "2025-01-15T10:30:00.000Z",
  "brandId": "507f1f77bcf86cd799439011",
  "conversationParts": [
    {
      "author": {
        "email": "john@example.com",
        "id": "676f0f6765bdaa7d7d760f88",
        "name": "John Doe",
        "profilePicture": "https://cdn.example.com/avatars/user.png",
        "type": "customer"
      },
      "bodyHtml": "<p>Hello, I have a question about your product.</p>",
      "bodyMarkdown": "Hello, I have a question about your product.",
      "channel": "desktop",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "id": "1",
      "object": "conversation_part",
      "partType": "user_msg",
      "redacted": false,
      "slack": {
        "channelId": "C01EFGH",
        "messageTs": "1705313410.001200",
        "teamId": "T01ABCD",
        "threadTs": "1705313400.001100"
      },
      "tagApplications": [
        {}
      ],
      "updatedAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "createdAt": "2025-01-15T10:30:00.000Z",
  "csatDebug": {
    "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z",
    "emailDelivery": {
      "attempts": 2,
      "claimedAt": "2025-01-15T10:30:59.000Z",
      "failedAt": "2025-01-15T10:31:00.000Z",
      "failureReason": "smtp_bounce",
      "idempotencyKey": "csat:req_123:user_123",
      "messageId": "msg_123",
      "nextAttemptAt": "2025-01-15T10:36:00.000Z",
      "sentAt": "2025-01-15T10:31:00.000Z",
      "status": "failed"
    },
    "lateSubmitWindowEndsAt": "2025-01-16T10:30:00.000Z",
    "requestId": "csat_req_123",
    "slackDelivery": {
      "channelId": "C01EFGH",
      "failedAt": "2025-01-15T10:31:00.000Z",
      "failureReason": "missing_slack_thread_metadata",
      "messageTs": "1705313400.001100",
      "postedAt": "2025-01-15T10:31:00.000Z",
      "status": "posted",
      "teamId": "T01ABCD"
    },
    "status": "pending"
  },
  "csatHistory": [
    {
      "canceledAt": "2025-01-15T10:32:00.000Z",
      "changeLockWindowEndsAt": "2025-01-16T12:30:00.000Z",
      "channel": "desktop",
      "emailDelivery": {
        "attempts": 2,
        "claimedAt": "2025-01-15T10:30:59.000Z",
        "failedAt": "2025-01-15T10:31:00.000Z",
        "failureReason": "smtp_bounce",
        "idempotencyKey": "csat:req_123:user_123",
        "messageId": "msg_123",
        "nextAttemptAt": "2025-01-15T10:36:00.000Z",
        "sentAt": "2025-01-15T10:31:00.000Z",
        "status": "failed"
      },
      "expiredAt": "2025-01-16T10:30:00.000Z",
      "isLatestEffective": true,

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

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

{
  "from": {
    "type": "admin",
    "id": "507f1f77bcf86cd799439011"
  },
  "bodyMarkdown": "Hi! Just following up on your inquiry.",
  "channel": "desktop",
  "recipients": {
    "to": {
      "ids": ["676f0f6765bdaa7d7d760f88"]
    }
  }
}

Example Admin Outreach (Email)

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

{
  "object": "conversation",
  "id": "12345",
  "state": "open",
  "priority": false,
  "adminAssigneeId": null,
  "participants": [
    { "type": "customer", "id": "676f0f6765bdaa7d7d760f88" }
  ],
  "source": {
    "channel": "desktop",
    "deliveredAs": "customer_initiated",
    "bodyHtml": "<p>Hello, I have a question about your product.</p>",
    "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.

Autorizaciones

Authorizationstringheaderobligatorio

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

Encabezados

Featurebase-Versionenum<string>header

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

Opciones disponibles: 2026-08-19.orbit, 2026-01-01.nova, 2025-12-12.clover

Ejemplo: 2026-08-19.orbit

Cuerpo

bodyMarkdownstringobligatorio

The content of the initial message in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored.

Minimum string length: 1

Ejemplo:

Hello, I have a question about your product.

![screenshot](https://example.com/image.png)

channelenum<string>default:desktop

The channel for the conversation. Defaults to "desktop" (SDK/widget).

Opciones disponibles: desktop, email

Ejemplo: desktop

createdAtstring | null

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.

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

fromobjectobligatorio

The author initiating the conversation. Use type "contact" for customer/lead or "admin" for outreach.

Conversation initiated by a contact

Mostrar child attributes

recipientsobject

Recipients for admin-initiated outreach. Required when from.type is "admin". Specify at least one recipient in the "to" field.

Mostrar child attributes

skipNotificationsbooleandefault:false

Skip admin notifications (push and activity email) for a conversation started by a contact (default: false). Useful for bulk imports.

Ejemplo: false

subjectstring

Subject line for the email. Required when channel is "email" and from.type is "admin".

Maximum string length: 500

Ejemplo: Following up on your inquiry

Respuesta

Created

adminAssigneeIdstring | nullobligatorio

ID of the assigned admin

Ejemplo: 507f1f77bcf86cd799439011

awaitingCustomerReplyboolean

Whether we are awaiting a customer reply

Ejemplo: true

botConversationStateenum<string>

State of AI agent handling for this conversation

Opciones disponibles: active, handed_off_to_human, resolved

Ejemplo: active

botConversationStateLastUpdatedAtstring | nullobligatorio

ISO timestamp when bot state last changed

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

brandIdstring | nullobligatorio

ID of the brand associated with this conversation

Ejemplo: 507f1f77bcf86cd799439011

conversationPartsobject[]

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

Mostrar child attributes

createdAtstringobligatorio

ISO timestamp when conversation was created

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

csatDebugobject

Minimal CSAT diagnostics for the current effective request.

Mostrar child attributes

csatHistoryobject[]

Historical CSAT requests for this conversation, ordered newest first.

Mostrar child attributes

csatSummaryobject

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

Mostrar child attributes

customAttributeValuesobject[]

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

Mostrar child attributes

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

Ejemplo: false

hasAdminOverriddenLanguagebooleanobligatorio

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

Ejemplo: false

idstringobligatorio

Unique conversation identifier

Ejemplo: 12345

isBlockedbooleanobligatorio

Whether the user is blocked

Ejemplo: false

lastActivityAtstring | nullobligatorio

ISO timestamp of last activity

Ejemplo: 2025-01-15T12:30:00.000Z

objectenum<string>obligatorio

Object type identifier

Opciones disponibles: conversation

Ejemplo: conversation

participantsobject[]obligatorio

Participants in this conversation

Mostrar child attributes

prioritybooleanobligatorio

Whether this conversation is marked as priority

Ejemplo: false

prioritySetAtstring | nullobligatorio

ISO timestamp when priority was set

Ejemplo: 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.

Mostrar child attributes

snoozedUntilstring | nullobligatorio

ISO timestamp until which conversation is snoozed

Ejemplo: 2025-01-16T09:00:00.000Z

sourceobject

Mostrar child attributes

stateenum<string>obligatorio

Current state of the conversation

Opciones disponibles: open, closed, snoozed

Ejemplo: open

tagsobject[]obligatorio

Current tags applied anywhere in this conversation

Mostrar child attributes

teamAssigneeIdstring | nullobligatorio

ID of the assigned team

Ejemplo: 507f1f77bcf86cd799439012

titlestring

Conversation title

Ejemplo: Question about pricing

updatedAtstringobligatorio

ISO timestamp when conversation was last updated

Ejemplo: 2025-01-15T12:30:00.000Z

userPreferredLanguagestringobligatorio

User's preferred language

Ejemplo: en

waitingSincestring | nullobligatorio

ISO timestamp when conversation started waiting

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

¿Aún necesitas ayuda? Pregunta al equipo