API-триггер

Узел «API-триггер» позволяет программно инициировать исходящие звонки вашему голосовому агенту. Когда вы добавляете узел «API-триггер» в воркфлоу, Агентика генерирует уникальный URL эндпоинта, который внешние системы могут вызвать, чтобы начать разговор. Это удобно, если вы хотите запускать звонки из собственного бэкенда, CRM или инструментов автоматизации вроде n8n и Zapier.

Требования

Настроенный провайдер телефонии — без него исходящие звонки завершатся ошибкой
API-ключ для аутентификации

Где найти URL триггера

Когда вы добавляете узел «API-триггер» в воркфлоу, Агентика назначает ему уникальный UUID. Триггер предоставляет два URL с этим UUID:

production URL для опубликованного воркфлоу
test URL для последнего черновика

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

POST https://your-agentika-instance/api/v1/public/agent/{uuid}        # Продакшн
POST https://your-agentika-instance/api/v1/public/agent/test/{uuid}   # Тест

Если вы используете облачную версию, замените your-agentika-instance на api.agentika.ai.

Тестовый и продакшн URL

Режим	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://your-agentika-instance/api/v1/public/agent/{uuid} \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dg_your_api_key" \
  -d '{
    "phone_number": "+14155550100",
    "initial_context": {
      "customer_name": "Jane",
      "appointment_date": "March 15"
    }
  }'

curl -X POST https://your-agentika-instance/api/v1/public/agent/test/{uuid} \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dg_your_api_key" \
  -d '{
    "phone_number": "+14155550100",
    "initial_context": {
      "customer_name": "Jane",
      "appointment_date": "March 15"
    }
  }'

Используйте тестовый 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": "+14155550100",
    "initial_context": {
        "user": {
            "name": "John"
        }
    }
}

Имя пользователя можно использовать в промпте агента как {{user.name}}: в промптах узла «Агент» поля initial_context указываются напрямую по имени, без префикса initial_context.. Точный синтаксис для промптов и полезной нагрузки вебхуков см. в переменных шаблона. Подробнее о потоке данных через звонок см. в «Контекст и переменные».

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

По умолчанию звонки выполняются через исходящую конфигурацию телефонии вашей организации, используемую по умолчанию. Чтобы направить конкретный звонок через другую конфигурацию, например с регионального номера, передайте telephony_configuration_id в теле запроса.

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

ID отображается в каждой строке Конфигурации телефонии в панели управления. Конфигурация должна принадлежать той же организации, что и узел «API-триггер», иначе запрос вернёт 404.

Полное описание эндпоинта, включая все параметры и поля ответа, см. в API-справочнике.

Начало работы

Основные понятия

Конфигурации

Конструктор голосовых агентов

Телефония

Интеграции

API-триггер

Требования

Где найти URL триггера

Тестовый и продакшн URL

Выполнение запроса

Ответ

Коды ошибок

Начальный контекст

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

​Требования

​Где найти URL триггера

​Тестовый и продакшн URL

​Выполнение запроса

​Ответ

​Коды ошибок

​Начальный контекст

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

Требования

Где найти URL триггера

Тестовый и продакшн URL

Выполнение запроса

Ответ

Коды ошибок

Начальный контекст

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