API-тригер

Вузол «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 запускають однакову версію.

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

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

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

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

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"
    }
  }'

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"
    }
  }'

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

Відповідь

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

{
  "status": "initiated",
  "workflow_run_id": 12345,
  "workflow_run_name": "WR-API-7823"
}

Помилки

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

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

initial_context — JSON-об’єкт з будь-якою інформацією, до якої голосовий агент повинен мати доступ під час дзвінка. На ці значення можна посилатись у промптах через шаблонні змінні — значення, обгорнуті в {{ і }}. Наприклад, якщо запит містить:

{
    "phone_number": "+380501234567",
    "initial_context": {
        "user": {
            "name": "Іван"
        }
    }
}

Ви можете послатись на ім’я абонента в промпті агента як {{user.name}} — у промптах вузлів агента поля initial_context вказуються напряму за назвою (без префікса initial_context.). Дивіться шаблонні змінні для точного синтаксису в промптах порівняно з тілом запиту вебхука.

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

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

{
  "phone_number": "+380501234567",
  "telephony_configuration_id": 42
}

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

Getting started

Build your First Agent

Voice Agent Builder

Передумови

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

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

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

Відповідь

Помилки

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

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

​Передумови

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

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

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

​Відповідь

​Помилки

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

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

Передумови

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

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

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

Відповідь

Помилки

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

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