> ## 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 асистент с обширни опции за конфигурация.

## Engine режими

API поддържа три engine режима, всеки с различни възможности:

| Режим        | Описание                                   | Задължителни полета   |
| ------------ | ------------------------------------------ | --------------------- |
| `pipeline`   | Традиционна STT → LLM → TTS верига         | `llm_model_id`        |
| `multimodal` | Real-time multimodal AI                    | `multimodal_model_id` |
| `dualplex`   | Multimodal мозък + персонализиран TTS глас | `multimodal_model_id` |

### Request Body

#### Основни задължителни полета

<ParamField body="name" type="string" required>
  Името на асистента (максимум 255 символа)
</ParamField>

<ParamField body="voice_id" type="integer" required>
  ID на гласа за употреба от асистента. Използвайте [Get Voices](/api-reference/assistants/get-voices) endpoint с `mode` параметър за да получите съвместими гласове за вашия engine режим.
</ParamField>

<ParamField body="language_id" type="integer" required>
  ID на езика за асистента. Използвайте [Get Languages](/api-reference/assistants/get-languages) endpoint за да получите наличните езици.
</ParamField>

<ParamField body="type" type="string" required>
  Типът на асистента. Опции: `inbound`, `outbound`
</ParamField>

<ParamField body="mode" type="string" required>
  Engine режимът. Опции: `pipeline`, `multimodal`, `dualplex`
</ParamField>

<ParamField body="timezone" type="string" required>
  Часовата зона за асистента (напр. "Europe/Bucharest", "America/New\_York")
</ParamField>

<ParamField body="initial_message" type="string" required>
  Първоначалното съобщение, което асистентът ще изговори когато започне обаждането (максимум 200 символа)
</ParamField>

<ParamField body="system_prompt" type="string" required>
  System prompt-ът, който дефинира поведението и личността на асистента
</ParamField>

#### Полета специфични за режима

<ParamField body="llm_model_id" type="integer">
  ID на LLM модела за използване. **Задължително за `pipeline` режим.**

  Използвайте [Get Models](/api-reference/assistants/get-models) endpoint за да получите наличните модели.
</ParamField>

<ParamField body="multimodal_model_id" type="integer">
  ID на multimodal модела. **Задължително за `multimodal` и `dualplex` режими.**

  Използвайте [Get Models](/api-reference/assistants/get-models) endpoint за да получите наличните multimodal модели.
</ParamField>

<ParamField body="chat_llm_fallback_id" type="integer">
  Fallback LLM модел ID за tool calls в multimodal/dualplex режими. Незадължително.
</ParamField>

<ParamField body="turn_detection_threshold" type="number">
  Чувствителност за разпознаване на реплики за multimodal/dualplex режими (0-1). По подразбиране: автоматично
</ParamField>

#### Вторични езици

<ParamField body="secondary_language_ids" type="integer[]">
  Масив от допълнителни ID-та на езици, които асистентът може да говори. Асистентът ще разпознава автоматично и ще превключва езици.

  ```json theme={null}
  "secondary_language_ids": [2, 3, 4]
  ```
</ParamField>

#### Настройки на базата знания

<ParamField body="knowledgebase_id" type="integer">
  ID на базата знания за прикачване към този асистент
</ParamField>

<ParamField body="knowledgebase_mode" type="string">
  Как да се използва базата знания. Опции:

  * `function_call` - AI извиква функция за търсене (задължително за multimodal/dualplex)
  * `prompt` - Знанията се инжектират в prompt-а (само за pipeline)
</ParamField>

#### Телефонен номер

<ParamField body="phone_number_id" type="integer">
  ID на телефонен номер за присвояване на асистента. Трябва да принадлежи на вашия акаунт.

  <Warning>
    За `inbound` асистенти, телефонният номер не може да бъде от тип Caller ID и не може да бъде вече присвоен на друг inbound асистент.
  </Warning>
</ParamField>

#### Персонализирани Mid-Call инструменти

<ParamField body="tool_ids" type="integer[]">
  Масив от ID-та на персонализирани mid-call инструменти за прикачване. Всеки инструмент трябва да принадлежи на вашия акаунт.

  ```json theme={null}
  "tool_ids": [1, 5, 12]
  ```
</ParamField>

#### Вградени инструменти

<ParamField body="tools" type="array">
  Масив от вградени инструменти за активиране. Всеки инструмент има `type` и полета специфични за инструмента.

  <Expandable title="Типове инструменти">
    **call\_transfer** - Прехвърля обаждането към друг телефонен номер

    * `phone_number` (задължително): Телефонен номер за прехвърляне (напр. "+1234567890")
    * `description`: Кога да се прехвърли обаждането
    * `custom`: Ако е true, AI може да определи номера за прехвърляне динамично
    * `timezone`: Часова зона за достъпност на прехвърлянето
    * `warm_transfer`: Изпрати съобщение на клиента преди прехвърляне (по подразбиране: `false`)
    * `warm_transfer_message`: Prompt който казва на AI какво да каже преди прехвърляне (напр. "Tell the customer that the call is being transferred.")

    **warm\_call\_transfer** - Топло прехвърляне с briefing на супервизора

    * `supervisor_phone` (задължително): Телефонен номер за набиране за топлото прехвърляне (напр. "+14155552001"). Ако `custom_sip` е активиран, това е SIP адрес или вътрешен номер.
    * `outbound_phone_id` (задължително): ID на телефонния номер използван за набиране на супервизора. Използвайте [Get Phone Numbers](/api-reference/assistants/get-phone-numbers) за да намерите налични номера.
    * `description` (задължително): **Кога да се прехвърли** — описва кога AI трябва да инициира топлото прехвърляне (напр. "Transfer the call to a human supervisor when the customer requests to speak with a real person.")
    * `custom_sip`: Активирайте за да въведете персонализиран SIP адрес или вътрешен номер вместо телефонен номер (по подразбиране: `false`)
    * `caller_id_mode`: Какъв телефонен номер вижда супервизорът при получаване на обаждането. Опции: `outbound_number` (по подразбиране — показва outbound телефонния номер), `customer_number` (показва номера на обаждащия се), `custom` (показва персонализиран номер)
    * `custom_caller_id`: Персонализиран телефонен номер показван на супервизора. Използва се само когато `caller_id_mode` е `custom`.
    * `hold_music`: Аудио изпълнявано на обаждащия се докато чака. Опции: `hold_music` (по подразбиране — изпълнява музика по подразбиране за чакане), `none` (тишина, без музика)
    * `hold_music_volume`: Ниво на звука за музиката при чакане, 0-100 (по подразбиране: `80`)
    * `hold_message`: Съобщение изговаряно на обаждащия се преди да го поставят на чакане (по подразбиране: "Please hold while I connect you with a supervisor.")
    * `summary_instructions`: Инструкции за това как AI трябва да информира супервизора за обаждането (по подразбиране: "Introduce the conversation from your perspective:\n- WHO is calling (name, company if mentioned)\n- WHY they called (their goal or problem)\n- WHY a human is needed at this point\n\nKeep it brief (2-3 sentences).")
    * `briefing_initial_message`: Първото съобщение което AI казва на супервизора когато отговори (по подразбиране: "Hello! I have a caller on the line who needs your assistance. May I brief you on the situation?")
    * `connected_message`: Съобщение изговаряно на обаждащия се след като супервизорът е свързан (по подразбиране: "You are now connected with a supervisor. I'll leave you to it.")

    **end\_call** - Приключи обаждането програмно

    * `description`: Кога AI трябва да приключи обаждането

    **dtmf\_input** - Изпрати DTMF тонове (въвеждане с клавиатура)

    * `description`: Кога да се използва DTMF въвеждане (за IVR навигация)

    **collect\_keypad** - Събери въвеждане с клавиатура от обаждащия се

    * `timeout`: Секунди за чакане на въвеждане, 1-30 (по подразбиране: 5)
    * `stop_key`: Клавиш който приключва въвеждането. Опции: `#` (по подразбиране), `*`

    **calendar\_integration** - Планирай срещи чрез Cal.com

    * `calcom_api_key` (задължително): Вашият Cal.com API ключ
    * `calcom_event_slug` (задължително): Slug-ът на типа събитие от Cal.com
    * `calcom_team_slug`: Team slug ако събитието принадлежи на Cal.com екип
    * `calcom_endpoint`: Cal.com API регион. Опции: `us` (по подразбиране — `https://api.cal.com`), `eu` (`https://api.cal.eu`), `custom` (използва `calcom_custom_endpoint`)
    * `calcom_custom_endpoint`: Персонализиран Cal.com API базов URL. Използва се само когато `calcom_endpoint` е `custom` (напр. `https://my-calcom-instance.com`).
    * `calcom_booking_fields`: Масив от персонализирани полета за резервация за събитието. Всяко поле има:
      * `slug` (задължително): Идентификатор на полето
      * `type` (задължително): Тип поле (напр. "text", "email", "phone", "select")
      * `label` (задължително): Етикет за показване
      * `required`: Дали полето е задължително (по подразбиране: `false`)
      * `options`: Масив от опции за select полета
    * `description`: Кога да се предложи планиране
  </Expandable>

  ```json theme={null}
  "tools": [
    {
      "type": "call_transfer",
      "phone_number": "+1234567890",
      "description": "Transfer when customer requests human support"
    },
    {
      "type": "warm_call_transfer",
      "supervisor_phone": "+1234567891",
      "outbound_phone_id": 7,
      "description": "Transfer the call to a human supervisor when the customer requests to speak with a real person.",
      "custom_sip": false,
      "caller_id_mode": "outbound_number",
      "hold_music": "hold_music",
      "hold_music_volume": 80,
      "hold_message": "Please hold while I connect you with a supervisor.",
      "summary_instructions": "Introduce the conversation from your perspective:\n- WHO is calling (name, company if mentioned)\n- WHY they called (their goal or problem)\n- WHY a human is needed at this point\n\nKeep it brief (2-3 sentences).",
      "briefing_initial_message": "Hello! I have a caller on the line who needs your assistance. May I brief you on the situation?",
      "connected_message": "You are now connected with a supervisor. I'll leave you to it."
    },
    {
      "type": "collect_keypad",
      "timeout": 5,
      "stop_key": "#"
    },
    {
      "type": "end_call",
      "description": "End call when customer confirms satisfaction"
    }
  ]
  ```
</ParamField>

#### Настройки за глас и TTS

<ParamField body="tts_emotion_enabled" type="boolean" default="true">
  Дали да се активира емоционален text-to-speech синтез
</ParamField>

<ParamField body="voice_stability" type="number" default="0.70">
  Настройка за стабилност на гласа (0-1). По-високо = по-последователен глас
</ParamField>

<ParamField body="voice_similarity" type="number" default="0.50">
  Настройка за прилика на гласа (0-1). По-високо = по-близо до оригиналния глас
</ParamField>

<ParamField body="speech_speed" type="number" default="1.00">
  Множител за скорост на говорене (0.7-1.2)
</ParamField>

<ParamField body="llm_temperature" type="number" default="0.10">
  Настройка за LLM temperature (0-1). По-ниско = по-детерминистично
</ParamField>

<ParamField body="synthesizer_provider_id" type="integer">
  ID на персонализиран TTS доставчик. Избира се автоматично на базата на езика, ако не е предоставено. Използвайте [Get Synthesizer Providers](/api-reference/assistants/get-synthesizer-providers) endpoint за да откриете наличните доставчици.
</ParamField>

<ParamField body="transcriber_provider_id" type="integer">
  ID на персонализиран STT доставчик. Избира се автоматично на базата на езика, ако не е предоставено. Само за pipeline режим. Използвайте [Get Transcriber Providers](/api-reference/assistants/get-transcriber-providers) endpoint за да откриете наличните доставчици.
</ParamField>

#### Настройки за поведение при обаждане

<ParamField body="allow_interruptions" type="boolean" default="true">
  Дали да се позволяват прекъсвания от обаждащия се.

  <Warning>Не може да се деактивира за `multimodal` и `dualplex` режими.</Warning>
</ParamField>

<ParamField body="fillers" type="boolean" default="false">
  Дали да се използват filler звуци по време на обработка (напр. "um", "let me check").

  <Warning>Достъпно само за `pipeline` режим.</Warning>
</ParamField>

<ParamField body="filler_config" type="object">
  Персонализирани профили за filler думи по категория. Ако не са предоставени, се задават по подразбиране на базата на езика на асистента. Всяка категория е масив от кратки фрази.

  * `positive`: Filler думи за позитивни/утвърдителни отговори (напр. "Great!", "Perfect!")
  * `negative`: Filler думи за негативни/неутрални отговори (напр. "Hmm.", "Mhm.")
  * `question`: Filler думи при обработка на въпрос (напр. "Hmm.", "Let me think.")
  * `neutral`: Filler думи за неутрални потвърждения (напр. "Ok.", "I understand.")

  ```json theme={null}
  "filler_config": {
    "positive": ["Super!", "Great!", "Perfect!"],
    "negative": ["Hmm.", "Mhm.", "I see."],
    "question": ["Hmm.", "Let me check.", "Good question."],
    "neutral": ["Ok.", "I understand.", "Noted."]
  }
  ```
</ParamField>

<ParamField body="record" type="boolean" default="false">
  Дали да се записва обаждането
</ParamField>

<ParamField body="enable_noise_cancellation" type="boolean" default="true">
  Дали да се активира шумопотискане
</ParamField>

<ParamField body="wait_for_customer" type="boolean" default="false">
  Ако е true, асистентът чака клиентът да заговори първи
</ParamField>

#### Настройки за време

<ParamField body="max_duration" type="integer" default="600">
  Максимална продължителност на обаждането в секунди (20-1200)
</ParamField>

<ParamField body="max_silence_duration" type="integer" default="40">
  Максимална продължителност на тишина преди повторно ангажиране в секунди (1-360)
</ParamField>

<ParamField body="max_initial_silence_duration" type="integer">
  Максимална тишина в началото на обаждането преди приключване (1-120 секунди). Незадължително.
</ParamField>

<ParamField body="ringing_time" type="integer" default="30">
  Максимално време за звънене преди отказване (1-60 секунди)
</ParamField>

#### Настройки за повторно ангажиране

<ParamField body="reengagement_interval" type="integer" default="30">
  Интервал за повторно ангажиране в секунди (7-600)
</ParamField>

<ParamField body="reengagement_prompt" type="string">
  Персонализиран prompt за съобщения за повторно ангажиране (максимум 1000 символа)

  Пример: `"Are you still there? Do you have any other questions?"`
</ParamField>

#### Настройки за гласова поща

<ParamField body="end_call_on_voicemail" type="boolean" default="true">
  Дали да се приключи обаждането когато се засече гласова поща
</ParamField>

<ParamField body="voice_mail_message" type="string">
  Съобщение за оставяне в гласовата поща преди затваряне (максимум 1000 символа)
</ParamField>

#### Разпознаване на край

<ParamField body="endpoint_type" type="string" default="vad">
  Тип разпознаване на гласова активност. Опции: `vad`, `ai`
</ParamField>

<ParamField body="endpoint_sensitivity" type="number" default="0.5">
  Ниво на чувствителност на endpoint (0-5)
</ParamField>

<ParamField body="interrupt_sensitivity" type="number" default="0.5">
  Ниво на чувствителност за прекъсвания (0-5)
</ParamField>

<ParamField body="min_interrupt_words" type="integer">
  Минимален брой думи преди да се позволи прекъсване (0-10). Задайте за активиране.
</ParamField>

#### Околен звук

<ParamField body="ambient_sound" type="string">
  Фонов околен звук. Опции: `off`, `office`, `city`, `forest`, `crowded_room`, `cafe`, `nature`
</ParamField>

<ParamField body="ambient_sound_volume" type="number" default="0.5">
  Ниво на звука на околния звук (0-1)
</ParamField>

#### Конфигурация на webhook

<ParamField body="is_webhook_active" type="boolean" default="false">
  Дали webhook уведомленията са активни
</ParamField>

<ParamField body="webhook_url" type="string">
  URL на webhook за уведомления след обаждане. **Задължително ако `is_webhook_active` е true.**
</ParamField>

<ParamField body="send_webhook_only_on_completed" type="boolean" default="true">
  Дали да се изпращат webhook-ове само при завършени обаждания (не неуспешни/неотговорени)
</ParamField>

<ParamField body="include_recording_in_webhook" type="boolean" default="true">
  Дали да се включва URL за записа в webhook payload-а
</ParamField>

#### Оценяване след обаждане

<ParamField body="post_call_evaluation" type="boolean" default="true">
  Дали да се активира AI оценяване след обаждане
</ParamField>

<ParamField body="post_call_schema" type="array">
  Дефиниция на схемата за извличане на данни след обаждане

  <Expandable title="post_call_schema свойства">
    <ParamField body="name" type="string" required>
      Име на полето (3-16 символа, малки букви, само алфа-цифрови символи и подчертавки)
    </ParamField>

    <ParamField body="type" type="string" required>
      Тип данни. Опции: `string`, `number`, `bool`
    </ParamField>

    <ParamField body="description" type="string" required>
      Описание на това, което представлява това поле (3-255 символа)
    </ParamField>
  </Expandable>

  ```json theme={null}
  "post_call_schema": [
    {"name": "status", "type": "bool", "description": "Was the call objective achieved"},
    {"name": "summary", "type": "string", "description": "Brief summary of the call"}
  ]
  ```
</ParamField>

#### Променливи

<ParamField body="variables" type="object">
  Ключ-стойност двойки на персонализирани променливи достъпни в prompt-овете чрез `{{variable_name}}`

  ```json theme={null}
  "variables": {
    "company_name": "Acme Corp",
    "product": "Premium Widget",
    "support_email": "support@acme.com"
  }
  ```
</ParamField>

#### Настройки за приключена беседа

<ParamField body="conversation_inactivity_timeout" type="integer" default="30">
  Минути бездействие в чата преди беседата да се счита за приключена (1-1440)
</ParamField>

<ParamField body="conversation_ended_retrigger" type="boolean" default="false">
  Дали да се позволява повторно задействане на беседата след като приключи поради бездействие
</ParamField>

<ParamField body="conversation_ended_webhook_url" type="string">
  Webhook URL извикван когато chat беседата приключи поради бездействие. Отделен от основния call webhook.
</ParamField>

***

## Примерни заявки

### Pipeline режим асистент

```json theme={null}
{
  "name": "Sales Assistant",
  "voice_id": 1,
  "language_id": 1,
  "type": "outbound",
  "mode": "pipeline",
  "timezone": "Europe/Bucharest",
  "initial_message": "Hello! How can I help you today?",
  "system_prompt": "You are a professional sales assistant...",
  "llm_model_id": 2,
  "secondary_language_ids": [2, 3],
  "knowledgebase_id": 1,
  "knowledgebase_mode": "prompt",
  "fillers": true,
  "filler_config": {
    "positive": ["Great!", "Perfect!", "Awesome!"],
    "negative": ["Hmm.", "I see."],
    "question": ["Good question.", "Let me check."],
    "neutral": ["Ok.", "Noted.", "I understand."]
  },
  "tool_ids": [1, 5],
  "tools": [
    {
      "type": "end_call",
      "description": "End call when customer is satisfied"
    },
    {
      "type": "call_transfer",
      "phone_number": "+1234567890",
      "description": "Transfer to support"
    },
    {
      "type": "warm_call_transfer",
      "supervisor_phone": "+1234567891",
      "outbound_phone_id": 7,
      "description": "Transfer the call to a human supervisor when the customer requests to speak with a real person.",
      "custom_sip": false,
      "caller_id_mode": "outbound_number",
      "hold_music": "hold_music",
      "hold_music_volume": 80,
      "hold_message": "Please hold while I connect you with a supervisor.",
      "summary_instructions": "Introduce the conversation from your perspective:\n- WHO is calling (name, company if mentioned)\n- WHY they called (their goal or problem)\n- WHY a human is needed at this point\n\nKeep it brief (2-3 sentences).",
      "briefing_initial_message": "Hello! I have a caller on the line who needs your assistance. May I brief you on the situation?",
      "connected_message": "You are now connected with a supervisor. I'll leave you to it."
    },
    {
      "type": "collect_keypad",
      "timeout": 5,
      "stop_key": "#"
    }
  ],
  "reengagement_interval": 20,
  "reengagement_prompt": "Are you still there?"
}
```

### Multimodal режим асистент

```json theme={null}
{
  "name": "Support Bot",
  "voice_id": 41,
  "language_id": 1,
  "type": "inbound",
  "mode": "multimodal",
  "timezone": "America/New_York",
  "initial_message": "Hi! Welcome to support.",
  "system_prompt": "You are a helpful support agent...",
  "multimodal_model_id": 1,
  "chat_llm_fallback_id": 2,
  "turn_detection_threshold": 0.7,
  "knowledgebase_id": 1,
  "knowledgebase_mode": "function_call",
  "tts_emotion_enabled": false
}
```

### Dualplex режим асистент

```json theme={null}
{
  "name": "Premium Agent",
  "voice_id": 1,
  "language_id": 2,
  "type": "outbound",
  "mode": "dualplex",
  "timezone": "Europe/Bucharest",
  "initial_message": "Buna ziua!",
  "system_prompt": "Esti un asistent profesionist...",
  "multimodal_model_id": 4,
  "chat_llm_fallback_id": 2,
  "secondary_language_ids": [1, 3],
  "knowledgebase_id": 1,
  "knowledgebase_mode": "function_call",
  "ambient_sound": "office",
  "ambient_sound_volume": 0.3
}
```

***

## Отговор

<ResponseField name="message" type="string">
  Съобщение за успех потвърждаващо създаването на асистента
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="свойства">
    <ResponseField name="id" type="integer">
      Уникалният идентификатор на създадения асистент
    </ResponseField>

    <ResponseField name="name" type="string">
      Името на асистента
    </ResponseField>

    <ResponseField name="status" type="string">
      Текущият статус (`inactive` за нови асистенти)
    </ResponseField>

    <ResponseField name="type" type="string">
      Типът (`inbound` или `outbound`)
    </ResponseField>

    <ResponseField name="mode" type="string">
      Engine режимът (`pipeline`, `multimodal`, или `dualplex`)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 201 Success Response theme={null}
  {
    "message": "Assistant created successfully",
    "data": {
      "id": 789,
      "name": "Sales Assistant",
      "status": "inactive",
      "type": "outbound",
      "mode": "pipeline"
    }
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "Validation failed",
    "errors": {
      "name": ["The name field is required."],
      "voice_id": ["The selected voice is not compatible with the chosen engine type."],
      "knowledgebase_mode": ["Only function_call mode is available for multimodal assistants."]
    }
  }
  ```
</ResponseExample>