---
title: "Create a new conversation"
method: POST
path: "/conversation/create"
tags: ["Conversation"]
---

# Create a new conversation

`POST /conversation/create`

## Request

- Base URL: `https://api.chatbotkit.com/api/v1`
- URL: `https://api.chatbotkit.com/api/v1/conversation/create`
- Auth: HTTP bearer

Create a new conversation with the given parameters and optional
messages. The conversation will be initialized with the the backstory,
model, dataset, skillset and other configuration options of the bot.
Alternatively the conversation can be initialized directly with the
backstory, model, dataset, skillset and other configuration options.

An array of messages can be included in the request body to add to the
conversation.

## Request body

- union
  - object: A bot configuration that can be applied without a dedicated bot instance.
    - `name` string: The associated name
    - `description` string: The associated description
    - `meta` Meta: Meta data information
    - `botId` string, nullable: The ID of the bot this configuration is using
    - `contactId` string: The contact id assigned to this conversation
    - `taskId` string: The task id assigned to this conversation
    - `spaceId` string: The space id assigned to this conversation
    - `messages` object[]: An array of messages to be added to the conversation
      - `type` 'user' | 'bot' | 'reasoning' | 'context' | 'instruction' | 'backstory' | 'activity' | 'checkpoint', required: The type of the message
      - `text` string, required: The text of the message
  - object: A bot configuration that can be applied without a dedicated bot instance.
    - `name` string: The associated name
    - `description` string: The associated description
    - `meta` Meta: Meta data information
    - `model` string: A model definition
    - `backstory` string, nullable: The backstory this configuration is using
    - `datasetId` string, nullable: The id of the dataset this configuration is using
    - `skillsetId` string, nullable: The id of the skillset this configuration is using
    - `privacy` boolean: The privacy flag for this configuration
    - `moderation` boolean: The moderation flag for this configuration
    - `contactId` string: The contact id assigned to this conversation
    - `taskId` string: The task id assigned to this conversation
    - `spaceId` string: The space id assigned to this conversation
    - `messages` object[]: An array of messages to be added to the conversation
      - `type` 'user' | 'bot' | 'reasoning' | 'context' | 'instruction' | 'backstory' | 'activity' | 'checkpoint', required: The type of the message
      - `text` string, required: The text of the message

## Response `200`

The conversation was created successfully

- object
  - `id` string, required: The ID of the created conversation
  - `messages` object[]: An array of messages included in the conversation
    - `type` 'user' | 'bot' | 'reasoning' | 'context' | 'instruction' | 'backstory' | 'activity' | 'checkpoint', required: The type of the message
    - `text` string, required: The text of the message

## Other responses

- `default`: An error response

---

[API](https://skmtc.dev/chatbotkit/apis/cbk-api.md) · [All operations](https://skmtc.dev/chatbotkit/apis/cbk-api/llms.txt) · [OpenAPI document](https://skmtc.dev/chatbotkit/apis/cbk-api/revisions/13d250576136?raw)