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

# Create conversation

> Start a new chat conversation session with an AI assistant.

Creates a new conversation session with an AI assistant. Use this to initiate text-based chat through your web widget or application. The response includes a `conversation_id` to use for subsequent messages.

## Endpoint

`POST /conversations`

<Note>
  This endpoint does not require authentication. It is called from your client application using the assistant's public UUID.
</Note>

## Request

<ParamField body="assistant_id" type="string" required>
  UUID of the assistant to start the conversation with.
</ParamField>

<ParamField body="type" type="string" default="widget">
  Conversation type:

  * `widget` — Web widget conversation. Charged at \$0.01 per user message.
  * `test` — Free test conversation for development.
</ParamField>

<ParamField body="variables" type="object">
  Custom variables to pass to the assistant. Accessible in the system prompt and initial message via `{{variable_name}}`.
</ParamField>

## Response

<ResponseField name="status" type="boolean">Whether the request was successful.</ResponseField>
<ResponseField name="conversation_id" type="string">UUID of the created conversation. Use this for subsequent [Send message](/api-reference/conversations/send-message) calls.</ResponseField>

<ResponseField name="history" type="array">
  Initial conversation history. Contains the assistant's opening message if one is configured.

  <Expandable title="Message properties">
    <ResponseField name="role" type="string">Message sender: `assistant` or `user`.</ResponseField>
    <ResponseField name="content" type="string">Message content.</ResponseField>
  </Expandable>
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://portal.intellixent.ai/api/conversations" \
    -H "Content-Type: application/json" \
    -d '{
      "assistant_id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "widget",
      "variables": {
        "customer_name": "John Smith",
        "company": "Acme Corp"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://portal.intellixent.ai/api/conversations', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      assistant_id: '550e8400-e29b-41d4-a716-446655440000',
      type: 'widget',
      variables: {
        customer_name: 'John Smith',
        company: 'Acme Corp'
      }
    })
  });

  const data = await response.json();
  const conversationId = data.conversation_id;
  ```
</CodeGroup>

```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 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."
}
```

After creating a conversation, use the [Send message](/api-reference/conversations/send-message) endpoint to exchange messages.