Запуск через API

POST https://journey.pushwoosh.com/api/journey/{id}/start/external

Добавляет группу пользователей в точку входа API Journey. Используйте этот вызов для запуска Journey с вашего бэкенда. Например, для запуска онбординга, когда пользователь завершает регистрацию на вашем сервере.

Предварительные условия

Journey находится в состоянии Running (Запущено).
Journey содержит ровно одну точку входа API (элемент «Запуск через API»), и этот элемент не деактивирован.
Имена атрибутов, которые вы отправляете, совпадают с атрибутами, настроенными в этой точке входа API.

Параметры пути

Имя	Тип	Описание
`id`	string	ID Journey запущенного Journey.

Заголовки запроса

Имя	Обязательный	Значение
`Content-Type`	Да	`application/json`
`Authorization`	Да	`Api <server_api_token>`. См. Токен Server API.

Тело запроса

Тело запроса содержит один объект payload. Вы должны указать ровно один из параметров users, hwids или filter, чтобы выбрать, кто войдет в Journey.

Поле	Тип	Описание
`payload.users`	string[]	User ID для входа. Взаимоисключающий с `hwids` и `filter`.
`payload.hwids`	string[]	HWID для входа. Взаимоисключающий с `users` и `filter`.
`payload.filter`	string	Выражение на языке сегментации (seglang), выбирающее аудиторию. Взаимоисключающий с `users` и `hwids`.
`payload.attribute_values`	map<string, string>	Необязательный. Значения для кастомных атрибутов, определенных в точке входа API. Каждый ключ должен соответствовать имени настроенного атрибута.

Примеры запросов

Добавление конкретных пользователей

curl -X POST 'https://journey.pushwoosh.com/api/journey/<journey_id>/start/external' \
  -H 'Authorization: Api YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "payload": {
      "users": ["user-123", "user-456"]
    }
  }'

Добавление конкретных пользователей с атрибутами

{
  "payload": {
    "users": ["user-123", "user-456"],
    "attribute_values": {
      "promo_code": "SUMMER25",
      "tier": "gold"
    }
  }
}

Добавление аудитории по фильтру

{
  "payload": {
    "filter": "A(\"XXXXX-XXXXX\").tags(\"City\").eq(\"London\")"
  }
}

Ответ

{
  "request_uuid": "9f8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"
}

Поле	Тип	Описание
`request_uuid`	string	Идентификатор принятого запроса на вход. Запрос обрабатывается асинхронно.

Ошибки валидации возвращают HTTP 400 с описательным сообщением. Распространенные случаи:

Сообщение	Причина
`one of users, hwids or filter must be provided`	Ни один из трех селекторов не был указан.
`only one of users, hwids or filter must be provided`	Было указано более одного селектора.
`Journey is not running`	Journey не находится в состоянии Running (Запущено).
`zero api start points`	В Journey нет точки входа API.
`there is more then one api start point`	В Journey более одной точки входа API.
`point is deactivated`	Точка входа API деактивирована.
`unknown attribute: <name>`	Ключ в `attribute_values` не настроен в точке входа API.
`Enhance your calm! only one request per minute is allowed`	Достигнут лимит частоты запросов (один запрос в минуту на одну точку входа).

Связанные материалы

Жизненный цикл

Получить статистику Journey

Язык сегментации