Обзор Customer Journey API

Customer Journey API позволяет бэкенду программно управлять Customer Journeys: создавать и редактировать определения Journey, перемещать Journey по их жизненному циклу (запуск, пауза, завершение, черновик, архивация), запускать работающий Journey из ваших собственных систем и получать статистику по каждому Journey.

Это тот же API, который использует конструктор Customer Journey, доступный через REST/JSON посредством моста gRPC-Gateway.

Базовый URL

https://journey.pushwoosh.com

Аутентификация

Каждый запрос должен содержать заголовок Authorization с серверным токеном доступа к API Pushwoosh:

Authorization: Api YOUR_API_TOKEN

Методы

Управление Journey

Жизненный цикл: POST /api/v3/journeygateway/{action}. Запуск, приостановка, завершение, перевод в черновик или архивация Journey по его UUID.
Создание и обновление: POST /api/v3/journeygateway и PUT /api/v3/journeygateway/{uuid}. Создание нового определения Journey или замена существующего.

Запуск Journey

Запуск через API: POST /api/journey/{id}/start/external. Добавление пользователей в точку входа API уже запущенного Journey.

Статистика и аудитория

Получение статистики Journey: GET /api/journey/{id}/statistics/external. Метрики доставки и конверсии по каждой точке.
Удаление пользователей из Journey: POST /api/journey/drop-users/external. Удаление пользователей из всех или выбранных активных Journey.

Справочник

Объект Journey: структура определения Journey (info, params, points, comments), возвращаемая методами жизненного цикла, создания и обновления.
Справочник по точкам: структура point_data для каждого типа точки: элементы входа, времени, разделения, действия и сообщений.

Lifecycle start в сравнении со Start by API

В Customer Journey есть две операции, которые звучат похоже, но работают по-разному.

Lifecycle start изменяет состояние Journey (например, с Draft на Running). Start by API добавляет пользователей в уже запущенный Journey. В таблице ниже приведено их сравнение.

	Lifecycle Start	Start by API
Эндпоинт	`POST /api/v3/journeygateway/start`	`POST /api/journey/{id}/start/external`
Что делает	Активирует Journey и переводит его в состояние Running	Добавляет пользователей в точку входа API уже запущенного Journey
Требуемое состояние Journey	Draft или Paused	Running (с точкой входа API)
Частота запуска	Один раз при смене состояния	Многократно, по мере необходимости входа пользователей

Формат запросов и ответов

Тип контента: application/json.
Имена полей v3 используют snake_case. Значения Enum сериализуются как их строковые имена (например, "STATUS_RUNNING", "POINT_TYPE_SEND_PUSH").
Методы gRPC-Gateway (/api/v3/journeygateway/...) возвращают объект Journey в случае успеха и стандартную оболочку ошибки gRPC-Gateway в случае неудачи: { "code": ..., "message": ..., "details": [...] }.
Устаревшие внешние методы (/api/journey/...) возвращают специфичное для метода тело JSON в случае успеха и { "success": false, "message": ... } с HTTP 400 при ошибках валидации.

Быстрый старт

curl -X POST https://journey.pushwoosh.com/api/v3/journeygateway/start \
  -H "Authorization: Api YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "uuid": "11111111-2222-3333-4444-555555555555" }'

Следующие шаги

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

Создание и обновление

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

Получение статистики Journey

Удаление пользователей из Journey

Объект Journey

Справочник по точкам