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

# Създаване на разговор

> Създаване на нова сесия за разговор с AI асистент

Този endpoint създава нова сесия за разговор с AI асистент. Използвайте го за инициране на текстова чат сесия чрез вашия уеб widget или приложение.

### Request Body

<ParamField body="assistant_id" type="string" required>
  UUID на асистента, с който да започне разговора. Трябва да бъде валиден UUID на асистент, който съществува в системата.
</ParamField>

<ParamField body="type" type="string" default="widget">
  Типът на разговора. Възможни стойности:

  * `widget` - Разговор чрез уеб widget (по подразбиране, таксуван)
  * `test` - Тестов разговор (безплатен, за разработка)
</ParamField>

<ParamField body="variables" type="object">
  Персонализирани променливи за предаване към асистента. Тези променливи могат да се използват в системния prompt на асистента и първоначалното съобщение със синтаксис `{{variable_name}}`.

  Обичайни случаи на употреба:

  * Предварително попълване на клиентска информация от форми
  * Предаване на контекст от вашето приложение
  * Персонализиране на поведението на асистента за всяка сесия
</ParamField>

### Response Fields

<ResponseField name="status" type="boolean">
  Показва дали заявката е била успешна
</ResponseField>

<ResponseField name="conversation_id" type="string">
  Уникалният UUID идентификатор за създадения разговор. Използвайте този ID за последващи заявки за съобщения.
</ResponseField>

<ResponseField name="history" type="array">
  Първоначалната история на разговора. Ако асистентът има конфигурирано първоначално съобщение, то ще бъде включено тук.

  <Expandable title="Свойства на обекта съобщение">
    <ResponseField name="role" type="string">
      Ролята на съобщението: `assistant` или `user`
    </ResponseField>

    <ResponseField name="content" type="string">
      Съдържанието на съобщението
    </ResponseField>
  </Expandable>
</ResponseField>

### Отговори при грешка

<ResponseField name="status" type="boolean">
  Ще бъде `false` когато възникне грешка
</ResponseField>

<ResponseField name="error" type="string">
  Съобщение за грешка, описващо какво се е объркало. Възможни стойности:

  * `Assistant not found` - Предоставеният assistant\_id не съществува
  * `Insufficient balance. Please top up your account.` - Балансът в акаунта на собственика на асистента е твърде нисък
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://call.aiployees.com/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://call.aiployees.com/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://call.aiployees.com/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>

## Ценообразуване

* **Widget разговори**: \$0.01 на потребителско съобщение
* **Тестови разговори**: Безплатни (за разработка и тестване)

## Следващи стъпки

След създаване на разговор, използвайте endpoint-а [Изпращане на съобщение](/api-reference/conversations/send-message) за обмен на съобщения с асистента.