> ## 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 Отговор

> Генерирайте AI отговор използвайки асистент, идентифициран чрез външен клиентски идентификатор

Този endpoint генерира AI отговор за дадено съобщение използвайки вашия конфигуриран асистент. Той автоматично създава или използва повторно разговори въз основа на клиентския идентификатор, което го прави идеален за интегриране на AI отговори във външни платформи, CRM системи или персонализирани чат интерфейси.

<Info>
  **Ограничена скорост** — Този endpoint е ограничен до 5 заявки на минута за API токен за предотвратяване на злоупотреба.
</Info>

### Тяло на Заявката

<ParamField body="assistant_id" type="integer" required>
  ID-то на асистента, който да се използва за генериране на отговора. Трябва да принадлежи на вашия акаунт.
</ParamField>

<ParamField body="customer_identifier" type="string" required>
  Уникален идентификатор за клиента. Използва се за поддържане на контекста на разговора при множество съобщения.

  Примери: телефонен номер, имейл адрес, ID на контакт от CRM, Facebook потребителски ID.

  Максимална дължина: 255 символа.
</ParamField>

<ParamField body="message" type="string" required>
  Съобщението на клиента, на което да се отговори.
</ParamField>

<ParamField body="variables" type="object">
  Опционални контекстови променливи за предаване на асистента. Те се обединяват с всички съществуващи променливи на разговора.

  Полезни за предаване на клиентски данни, контекст на сесията или други метаданни.
</ParamField>

### Полета в Отговора

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

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

<ResponseField name="customer_identifier" type="string">
  Клиентският идентификатор предоставен в заявката
</ResponseField>

<ResponseField name="reply" type="string">
  AI-генерираният отговор на съобщението на клиента
</ResponseField>

<ResponseField name="function_calls" type="array">
  Масив от функционални извиквания направени от асистента по време на обработката на съобщението. Празен масив ако няма извикани функции.

  <Expandable title="Свойства на обекта функционално извикване">
    <ResponseField name="name" type="string">
      Името на функцията която е била извикана
    </ResponseField>

    <ResponseField name="arguments" type="object">
      Аргументите предадени на функцията
    </ResponseField>

    <ResponseField name="result" type="object">
      Резултатът върнат от функцията
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="ai_disabled" type="boolean">
  Показва дали AI отговорите са деактивирани за този разговор (например поради ръчно поемане)
</ResponseField>

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

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

<ResponseField name="error" type="string">
  Съобщение за грешка описващо какво се е объркало
</ResponseField>

<ResponseField name="error_code" type="string">
  Код за грешка четим от машини. Възможни стойности:

  * `ASSISTANT_NOT_FOUND` - ID-то на асистента е невалидно или не принадлежи на вашия акаунт
  * `INSUFFICIENT_BALANCE` - Баланса на вашия акаунт е твърде нисък за обработка на съобщението
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://call.aiployees.com/api/user/ai/generate-reply" \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "assistant_id": 123,
      "customer_identifier": "+14155551234",
      "message": "Hi, I would like to schedule an appointment",
      "variables": {
        "customer_name": "John Smith",
        "source": "whatsapp"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://call.aiployees.com/api/user/ai/generate-reply', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      assistant_id: 123,
      customer_identifier: '+14155551234',
      message: 'Hi, I would like to schedule an appointment',
      variables: {
        customer_name: 'John Smith',
        source: 'whatsapp'
      }
    })
  });

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

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

  response = requests.post(
      'https://call.aiployees.com/api/user/ai/generate-reply',
      headers={
          'Authorization': 'Bearer YOUR_API_TOKEN',
          'Content-Type': 'application/json'
      },
      json={
          'assistant_id': 123,
          'customer_identifier': '+14155551234',
          'message': 'Hi, I would like to schedule an appointment',
          'variables': {
              'customer_name': 'John Smith',
              'source': 'whatsapp'
          }
      }
  )

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

  ```php PHP theme={null}
  $response = Http::withToken('YOUR_API_TOKEN')
      ->post('https://call.aiployees.com/api/user/ai/generate-reply', [
          'assistant_id' => 123,
          'customer_identifier' => '+14155551234',
          'message' => 'Hi, I would like to schedule an appointment',
          'variables' => [
              'customer_name' => 'John Smith',
              'source' => 'whatsapp'
          ]
      ]);

  $reply = $response->json()['reply'];
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "success": true,
    "conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "customer_identifier": "+14155551234",
    "reply": "Hi John! I'd be happy to help you schedule an appointment. What day and time work best for you?",
    "function_calls": [],
    "ai_disabled": false
  }
  ```

  ```json 200 Success (With Function Calls) theme={null}
  {
    "success": true,
    "conversation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "customer_identifier": "+14155551234",
    "reply": "I've checked our calendar and we have availability tomorrow at 2 PM and Friday at 10 AM. Which works better for you?",
    "function_calls": [
      {
        "name": "check_availability",
        "arguments": {
          "start_date": "2025-01-08",
          "days": 7
        },
        "result": {
          "slots": ["2025-01-08 14:00", "2025-01-10 10:00"]
        }
      }
    ],
    "ai_disabled": false
  }
  ```

  ```json 404 Assistant Not Found theme={null}
  {
    "success": false,
    "error": "Assistant not found or does not belong to you",
    "error_code": "ASSISTANT_NOT_FOUND"
  }
  ```

  ```json 402 Insufficient Balance theme={null}
  {
    "success": false,
    "error": "Insufficient balance. Please top up your account.",
    "error_code": "INSUFFICIENT_BALANCE"
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "The assistant id field is required.",
    "errors": {
      "assistant_id": ["The assistant id field is required."]
    }
  }
  ```

  ```json 429 Rate Limited theme={null}
  {
    "message": "Too Many Attempts.",
    "retry_after": 60
  }
  ```
</ResponseExample>

## Случаи на Употреба

### Многоканални AI Отговори

Използвайте този endpoint за добавяне на AI отговори към всяка платформа за съобщения:

1. Получете съобщение от WhatsApp, Facebook, SMS или всеки друг канал
2. Извикайте този endpoint със съобщението и клиентския идентификатор
3. Изпратете AI отговора обратно през оригиналния канал

### CRM Интеграция

Интегрирайте AI отговори в своята CRM или helpdesk система:

1. Използвайте ID-то на контакта от CRM като `customer_identifier`
2. Предайте клиентски данни като `variables` за персонализирани отговори
3. Разговорът се запазва между сесиите използвайки същия идентификатор

### Персонализирани Чат Интерфейси

Изградете свой собствен чат интерфейс захранван от вашия Aiplocalls асистент:

1. Генерирайте уникален идентификатор за всяка потребителска сесия
2. Изпращайте съобщения чрез този endpoint
3. Показвайте AI отговорите във вашия интерфейс

## Запазване на Разговора

Разговорите се запазват автоматично въз основа на комбинацията `assistant_id` и `customer_identifier`:

* **Същия идентификатор**: Съобщенията се добавят към съществуващия разговор, запазвайки пълния контекст
* **Нов идентификатор**: Създава се нов разговор за клиента
* **Обединяване на променливи**: Когато се предоставят променливи, те се обединяват със съществуващите променливи на разговора

## Най-добри Практики

1. **Използвайте последователни идентификатори**: Винаги използвайте същия формат за клиентски идентификатори (например винаги E.164 за телефонни номера)
2. **Предавайте релевантен контекст**: Използвайте полето `variables` за предоставяне на клиентски данни, които помагат на AI да персонализира отговорите
3. **Обработвайте ограниченията на скоростта**: Имплементирайте логика за повторни опити с експоненциално забавяне за ограничени по скорост заявки
4. **Запазвайте ID-тата на разговорите**: Запазете върнатото `conversation_id` за по-късна справка или отстраняване на грешки
5. **Наблюдавайте разходите**: Проследявайте използването за управление на разходите, особено за високообемни интеграции