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

# API-тригер

> Запускайте вихідні дзвінки із зовнішніх систем — вашого бекенду, CRM чи інструментів на кшталт n8n і Zapier.

Вузол «API-тригер» дозволяє програмно ініціювати вихідні дзвінки вашого голосового агента. Коли ви додаєте вузол «API-тригер» у сценарій, платформа генерує унікальний URL ендпоінта, який зовнішні системи можуть викликати, щоб почати розмову.

Це зручно, коли потрібно запускати дзвінки з вашого бекенду, CRM або інструментів автоматизації на кшталт n8n і Zapier.

## Передумови

* Налаштований провайдер телефонії — без нього вихідні дзвінки не пройдуть.
* API-ключ для автентифікації запитів.

## Пошук URL тригера

Коли ви додаєте вузол «API-тригер» у сценарій, платформа призначає йому унікальний UUID. Вузол тригера відкриває два URL з однаковим UUID:

* **Продакшн URL** для опублікованого сценарію.
* **Тестовий URL** для останньої чернетки.

Скопіювати будь-який з URL можна в діалозі налаштувань вузла тригера.

```
POST https://va.ukrgsm.com/api/v1/public/agent/{uuid}        # Продакшн
POST https://va.ukrgsm.com/api/v1/public/agent/test/{uuid}   # Тест
```

### Тест проти продакшн

| Режим    | URL                                | Що запускає                                                  |
| -------- | ---------------------------------- | ------------------------------------------------------------ |
| Продакшн | `/api/v1/public/agent/{uuid}`      | Опубліковану версію агента.                                  |
| Тест     | `/api/v1/public/agent/test/{uuid}` | Останню чернетку. Якщо чернетки немає — опубліковану версію. |

Використовуйте тестовий URL, поки вносите зміни, щоб продакшн-трафік продовжував іти на опубліковану версію.

Продакшн URL завжди виконує лише **опублікований** сценарій. Якщо ви оновили сценарій, але не опублікували його, продакшн-тригер продовжить запускати попередню опубліковану версію.

Після публікації чернетки обидва URL запускають однакову версію.

<Warning>
  Типова помилка — відредагувати сценарій, зберегти чернетку й одразу викликати продакшн URL тригера, очікуючи нову поведінку. Це не спрацює, поки сценарій не опубліковано. Використовуйте тестовий URL, щоб перевірити зміни чернетки перед публікацією.
</Warning>

Тіло запиту, заголовки й формат відповіді однакові для обох URL.

## Виконання запиту

Автентифікація — через передачу вашого API-ключа в заголовку `X-API-Key`. Тіло запиту вимагає `phone_number` і приймає необов'язкові поля `initial_context` та `telephony_configuration_id`.

<CodeGroup>
  ```bash Продакшн URL theme={null}
  curl -X POST https://va.ukrgsm.com/api/v1/public/agent/{uuid} \
    -H "Content-Type: application/json" \
    -H "X-API-Key: dg_your_api_key" \
    -d '{
      "phone_number": "+380501234567",
      "initial_context": {
        "name": "Іван",
        "min_sum": "1300"
      }
    }'
  ```

  ```bash Тестовий URL theme={null}
  curl -X POST https://va.ukrgsm.com/api/v1/public/agent/test/{uuid} \
    -H "Content-Type: application/json" \
    -H "X-API-Key: dg_your_api_key" \
    -d '{
      "phone_number": "+380501234567",
      "initial_context": {
        "name": "Іван",
        "min_sum": "1300"
      }
    }'
  ```
</CodeGroup>

Використовуйте тестовий URL, щоб перевірити зміни чернетки перед публікацією.

### Відповідь

Успішний запит повертає `workflow_run_id`, який можна використати, щоб отримати деталі запуску, записи й транскрипти.

```json theme={null}
{
  "status": "initiated",
  "workflow_run_id": 12345,
  "workflow_run_name": "WR-API-7823"
}
```

### Помилки

| Статус | Причина                                                                |
| ------ | ---------------------------------------------------------------------- |
| `400`  | Провайдер телефонії не налаштований, або дзвінок не вдалося ініціювати |
| `401`  | Відсутній або недійсний API-ключ                                       |
| `403`  | API-ключ не має доступу до цього агента                                |
| `404`  | Тригер не знайдено або він неактивний                                  |

## Початковий контекст

`initial_context` — JSON-об'єкт з будь-якою інформацією, до якої голосовий агент повинен мати доступ під час дзвінка. На ці значення можна посилатись у промптах через [шаблонні змінні](/voice-agent/template-variables) — значення, обгорнуті в `{{` і `}}`.

Наприклад, якщо запит містить:

```json theme={null}
{
    "phone_number": "+380501234567",
    "initial_context": {
        "user": {
            "name": "Іван"
        }
    }
}
```

Ви можете послатись на ім'я абонента в промпті агента як `{{user.name}}` — у промптах вузлів агента поля `initial_context` вказуються напряму за назвою (без префікса `initial_context.`). Дивіться [шаблонні змінні](/voice-agent/template-variables) для точного синтаксису в промптах порівняно з тілом запиту вебхука.

## Вибір конфігурації телефонії

За замовчуванням дзвінки здійснюються через типову вихідну конфігурацію телефонії вашої організації. Щоб направити конкретний дзвінок через іншу конфігурацію — наприклад, для набору з регіонального номера, — передайте `telephony_configuration_id` у тілі запиту.

```json theme={null}
{
  "phone_number": "+380501234567",
  "telephony_configuration_id": 42
}
```

Ідентифікатор показано в кожному рядку розділу конфігурацій телефонії в кабінеті. Конфігурація має належати тій самій організації, що й API-тригер, інакше запит поверне `404`.