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

# Отримання даних перед дзвінком

> Отримуйте дані клієнта з вашої CRM чи ERP ще до початку дзвінка, щоб голосовий агент міг привітати абонента на ім'я й посилатись на деталі його акаунта.

Отримання даних перед дзвінком дозволяє збагатити контекст дзвінка зовнішніми даними ще до того, як голосовий агент почне говорити. Коли ця опція увімкнена на вузлі [**Початок дзвінка**](/voice-agent/start-call), платформа надсилає HTTP-запит до вашого API одразу після ініціації дзвінка. Поки триває очікування відповіді, абонент чує гудки виклику. Щойно дані надходять, вони додаються до `initial_context` дзвінка і стають доступні як шаблонні змінні у промптах і привітанні.

## Як це працює

1. Дзвінок надходить (вхідний) або ініціюється (вихідний).
2. Платформа надсилає **POST**-запит на налаштований ендпоінт зі стандартизованим тілом.
3. Абонент чує гудки виклику, поки триває очікування відповіді.
4. Ваш API повертає JSON-об'єкт з полем `initial_context`.
5. Змінні додаються до початкового контексту дзвінка.
6. Голосовий агент починає розмову з повним доступом до отриманих даних через синтаксис `{{назва_змінної}}`.

## Налаштування

Відкрийте редактор вузла [**Початок дзвінка**](/voice-agent/start-call) і розгорніть додаткові налаштування. Увімкніть **Отримання даних перед дзвінком** і налаштуйте:

| Поле               | Опис                                                                                                                          |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| **URL ендпоінта**  | URL, на який буде надіслано POST-запит.                                                                                       |
| **Автентифікація** | Необов'язкові облікові дані для автентифікації запиту. Підтримується API-ключ, bearer-токен, basic auth та власний заголовок. |

## Формат запиту

Платформа надсилає `POST`-запит з таким JSON-тілом:

```json theme={null}
{
  "event": "call_inbound",
  "call_inbound": {
    "agent_id": 123,
    "from_number": "+380501234567",
    "to_number": "+380671234567"
  }
}
```

| Поле                       | Опис                                                      |
| -------------------------- | --------------------------------------------------------- |
| `event`                    | Завжди `"call_inbound"`.                                  |
| `call_inbound.agent_id`    | ID сценарію (агента).                                     |
| `call_inbound.from_number` | Номер абонента (`caller_number` з початкового контексту). |
| `call_inbound.to_number`   | Набраний номер (`called_number` з початкового контексту). |

Заголовок `Content-Type` встановлюється як `application/json`. Якщо налаштовано облікові дані, додається відповідний заголовок автентифікації.

## Очікуваний формат відповіді

Ваш API має повернути **JSON-об'єкт** зі статусом `2xx`. Змінні, які потрібно додати в контекст дзвінка, розмістіть у ключі `initial_context`:

```json theme={null}
{
  "call_inbound": {
    "initial_context": {
      "customer_name": "Іван Петренко",
      "account_status": "active",
      "loyalty_tier": "gold",
      "open_tickets": 2
    }
  }
}
```

`initial_context` також можна розмістити на верхньому рівні:

```json theme={null}
{
  "initial_context": {
    "customer_name": "Іван Петренко",
    "account_status": "active"
  }
}
```

<Note>
  Застарілий ключ `dynamic_variables` досі приймається як синонім `initial_context`, тож наявні інтеграції продовжують працювати без змін. Для нових інтеграцій використовуйте `initial_context`. Якщо відповідь містить обидва ключі, пріоритет має `initial_context`.
</Note>

Після отримання відповіді ці значення доступні всюди, де підтримуються шаблонні змінні:

* **Привітання**: `Вітаю, {{customer_name}}, дякуємо за дзвінок!`
* **Промпт**: `Клієнт має статус {{loyalty_tier}} і {{open_tickets}} відкритих звернень.`

<Note>
  Якщо відповідь не є коректним JSON-об'єктом, не містить `initial_context` (чи застарілого `dynamic_variables`), або запит завершується помилкою чи таймаутом, дзвінок продовжується у звичайному режимі без додаткового контексту. Отримання даних перед дзвінком ніколи не блокує й не зриває дзвінок.
</Note>

## Вкладені змінні

Якщо `initial_context` містить вкладені об'єкти, звертайтесь до них через крапкову нотацію:

```json theme={null}
{
  "call_inbound": {
    "initial_context": {
      "customer": {
        "name": "Іван Петренко",
        "address": {
          "city": "Київ"
        }
      }
    }
  }
}
```

Доступ у промптах: `{{customer.name}}` і `{{customer.address.city}}`.

## Таймаут

Запит має **10-секундний таймаут**. Якщо ваш API не відповідає в цей час, дзвінок продовжується без отриманих даних. Проєктуйте ендпоінт так, щоб він відповідав якомога швидше — це мінімізує тривалість гудків очікування.

## Тестування тестовими дзвінками

Коли надходить реальний телефонний дзвінок, контекстні змінні `caller_number` і `called_number` автоматично встановлюються провайдером телефонії та передаються в запиті отримання даних як `from_number` і `to_number`. Однак під час тестового дзвінка — веб-дзвінка (WebRTC) або тестового телефонного дзвінка з редактора сценарію — ці змінні за замовчуванням недоступні.

Щоб симулювати дані телефонії під час тестування:

1. Відкрийте сценарій і перейдіть у **Налаштування**.
2. У розділі **Контекстні змінні** додайте:
   * `caller_number` — номер, який симулює абонента (наприклад, `+380501234567`).
   * `called_number` — номер, на який ніби здійснюється дзвінок (наприклад, `+380671234567`).
3. Збережіть налаштування.

Тепер при тестовому дзвінку (веб чи телефонному) ці значення надсилатимуться в запиті отримання даних на ваш ендпоінт, дозволяючи протестувати весь потік так, ніби це реальний вхідний дзвінок.

<Note>
  Ці контекстні змінні використовуються лише під час тестових дзвінків з редактора сценарію. У продакшн-дзвінках (вхідних і вихідних кампаніях) використовуються реальні дані телефонії, а ці значення ігноруються.
</Note>

## Приклад інтеграції

Простий ендпоінт на Node.js, що шукає клієнта за номером телефону:

```javascript theme={null}
app.post("/pre-call", async (req, res) => {
  const { call_inbound } = req.body;

  const customer = await db.customers.findOne({
    phone: call_inbound.from_number,
  });

  if (!customer) {
    return res.json({});
  }

  res.json({
    call_inbound: {
      initial_context: {
        customer_name: customer.name,
        account_status: customer.status,
        loyalty_tier: customer.tier,
      },
    },
  });
});
```