> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autocalls.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

<ParamField body="assistant_id" type="string" required>
  The UUID of the assistant to start the conversation with. Must be a valid assistant UUID that exists in the system.
</ParamField>

<ParamField body="type" type="string" default="widget">
  The type of conversation. Possible values:

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

<ParamField body="variables" type="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
</ParamField>

### Response Fields

<ResponseField name="status" type="boolean">
  Indicates whether the request was successful
</ResponseField>

<ResponseField name="conversation_id" type="string">
  The unique UUID identifier for the created conversation. Use this ID for subsequent message requests.
</ResponseField>

<ResponseField name="history" type="array">
  The initial conversation history. If the assistant has an initial message configured, it will be included here.

  <Expandable title="Message object properties">
    <ResponseField name="role" type="string">
      The message role: `assistant` or `user`
    </ResponseField>

    <ResponseField name="content" type="string">
      The message content
    </ResponseField>
  </Expandable>
</ResponseField>

### Error Responses

<ResponseField name="status" type="boolean">
  Will be `false` when an error occurs
</ResponseField>

<ResponseField name="error" type="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
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://app.autocalls.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.autocalls.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.autocalls.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'])
  ```
</RequestExample>

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

## 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](/api-reference/conversations/send-message) endpoint to exchange messages with the assistant.