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

# Create Conversation

> Create a new conversation session with an AI assistant

This endpoint creates a new conversation session with an AI assistant. Use this to initiate a text-based chat session through your web widget or application.

### Request Body

**assistant\_id** `string` *required*

The UUID of the assistant to start the conversation with. Must be a valid assistant UUID that exists in the system.

**type** `string` (default: widget)

The type of conversation. Possible values:

* `widget` - Web widget conversation (default, charged)
* `test` - Test conversation (free, for development)

**variables** `object`

Custom variables to pass to the assistant. These variables can be used in the assistant's system prompt and initial message using `{{variable_name}}` syntax.

Common use cases:

* Pre-filling customer information from forms
* Passing context from your application
* Customizing assistant behavior per session

### Response Fields

**status** `boolean`

Indicates whether the request was successful

**conversation\_id** `string`

The unique UUID identifier for the created conversation. Use this ID for subsequent message requests.

**history** `array`

The initial conversation history. If the assistant has an initial message configured, it will be included here.

**Message object properties**

**role** `string`

The message role: `assistant` or `user`

**content** `string`

The message content

### Error Responses

**status** `boolean`

Will be `false` when an error occurs

**error** `string`

Error message describing what went wrong. Possible values:

* `Assistant not found` - The provided assistant\_id does not exist
* `Insufficient balance. Please top up your account.` - The assistant owner's account balance is too low

```bash cURL theme={null}
curl -X POST "https://app.lacy.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",
      "source": "pricing_page"
    }
  }'
```

```javascript JavaScript theme={null}
const response = await fetch('https://app.lacy.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',
      source: 'pricing_page'
    }
  })
});

const data = await response.json();
console.log(data.conversation_id);
```

```python Python theme={null}
import requests

response = requests.post(
    'https://app.lacy.ai/api/conversations',
    json={
        'assistant_id': '550e8400-e29b-41d4-a716-446655440000',
        'type': 'widget',
        'variables': {
            'customer_name': 'John Smith',
            'company': 'Acme Corp',
            'source': 'pricing_page'
        }
    }
)

data = response.json()
print(data['conversation_id'])
```

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

## Pricing

* **Widget conversations**: \$0.01 per user message
* **Test conversations**: Free (for development and testing)

## Next Steps

After creating a conversation, use the [Send Message](https://docs.lacy.ai/api-reference/conversations/send-message.md) endpoint to exchange messages with the assistant.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.