> ## Documentation Index
> Fetch the complete documentation index at: https://docs.famulor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create conversation

> Start a new conversation session with a Famulor AI chatbot via API. Initialise context, user metadata and channel for WhatsApp, web chat or voice chat.

Create a new conversation with your Famulor AI assistant. Use this endpoint to start a widget or test conversation and receive the initial history.

### Request Body

<ParamField body="assistant_id" type="string" required>
  UUID of the assistant that should handle the conversation
</ParamField>

<ParamField body="type" type="string" default="widget">
  Conversation type. Options: `widget` (paid) or `test` (free for development)
</ParamField>

<ParamField body="variables" type="object" optional>
  Custom variables injected into the assistant context (accessible via `{{variable_name}}`)

  <Expandable title="variables examples">
    <ParamField body="customer_name" type="string">
      Name for greeting or personalization
    </ParamField>

    <ParamField body="company" type="string">
      Company name to reference in replies
    </ParamField>

    <ParamField body="source" type="string">
      Traffic or page source (e.g., `pricing_page`)
    </ParamField>
  </Expandable>
</ParamField>

### Request Examples

### Response Fields

<ResponseField name="status" type="boolean" required>
  Indicates whether the request succeeded
</ResponseField>

<ResponseField name="conversation_id" type="string" required>
  UUID of the created conversation; use it for subsequent messages
</ResponseField>

<ResponseField name="history" type="array">
  Initial conversation history. Empty if the assistant has no initial message.

  <Expandable title="history items">
    <ResponseField name="role" type="string">
      Message role (`assistant` or `user`)
    </ResponseField>

    <ResponseField name="content" type="string">
      Message text content
    </ResponseField>
  </Expandable>
</ResponseField>

### Response Examples

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "status": true,
    "conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "history": [
      {
        "role": "assistant",
        "content": "Hello John Smith! Welcome to Acme Corp support. How can I help you today?"
      }
    ]
  }
  ```

  ```json 200 Success (no initial message) theme={null}
  {
    "status": true,
    "conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "history": []
  }
  ```

  ```json 404 Assistant Not Found theme={null}
  {
    "status": false,
    "error": "Assistant not found"
  }
  ```

  ```json 400 Insufficient Balance theme={null}
  {
    "status": false,
    "error": "Insufficient balance. Please top up your account."
  }
  ```
</ResponseExample>

### Notes

* `type: "widget"` conversations are billed; `type: "test"` is free for development.
* Provide meaningful `variables` to personalize the assistant's first reply.
* Continue the chat with [`Send Message`](/en/api-reference/ai-chatbot/send-conversation) and fetch history with [`Get Conversation`](/en/api-reference/ai-chatbot/get-conversation).