Customer Journey API 概述

Customer Journey API 允许后端以编程方式管理 Customer Journey：创建和编辑 Journey 定义，在 Journey 的生命周期中移动（启动、暂停、完成、草稿、归档），从您自己的系统触发正在运行的 Journey，并拉取每个 Journey 的统计数据。

它与 Customer Journey 构建器使用的 API 相同，通过 gRPC-Gateway 桥接以 REST/JSON 形式暴露。

基础 URL

gRPC-Gateway 方法和旧版外部方法在不同的主机上提供服务：

方法	基础 URL
gRPC-Gateway：/api/v3/journeygateway/...（生命周期、创建、更新）	https://journey-api.svc-nue.pushwoosh.com
旧版外部：/api/journey/...（通过 API 启动、统计、移除用户）	https://journey.pushwoosh.com

提示

如果您使用专用区域或私有部署，请与您的 Pushwoosh 客户成功经理确认确切的基础 URL。

身份验证

每个请求都必须包含一个 Authorization 标头，其中包含一个服务器端的 Pushwoosh API 访问令牌：

Authorization: Api YOUR_API_TOKEN

注意

该令牌绑定到其所属的账户。所有操作都适用于该账户。请使用您为其他服务器到服务器 API 调用颁发的相同令牌，切勿在客户端应用程序中暴露它。

方法

管理 Journey

• 生命周期：POST /api/v3/journeygateway/{action}。通过其 UUID 启动、暂停、完成、设为草稿或归档一个 Journey。
• 创建和更新：POST /api/v3/journeygateway 和 PUT /api/v3/journeygateway/{uuid}。创建一个新的 Journey 定义或替换一个现有的定义。

触发 Journey

• 通过 API 启动：POST /api/journey/{id}/start/external。将用户注入到一个已在运行的 Journey 的 API 入口点。

统计和受众

• 获取 Journey 统计数据：GET /api/journey/{id}/statistics/external。每个节点的交付和转化指标。
• 从 Journey 中移除用户：POST /api/journey/drop-users/external。从所有或选定的活动 Journey 中移除用户。

参考

• Journey 对象：生命周期、创建和更新方法返回的 Journey 定义的结构（信息、参数、节点、评论）。
• 节点参考：每种节点类型的 point_data 结构：入口、计时、分支、操作和消息元素。

生命周期启动 vs 通过 API 启动

Customer Journey 有两个听起来相似但行为不同的操作。

生命周期启动 会改变 Journey 的状态（例如，从草稿变为 运行中）。 通过 API 启动 会将用户注入到一个已在运行的 Journey 中。下表对它们进行了并排比较。

	生命周期启动	通过 API 启动
端点	POST /api/v3/journeygateway/start	POST /api/journey/{id}/start/external
作用	激活 Journey 并将其移至 运行中 状态	将用户注入到一个已在运行的 Journey 的 API 入口点
要求的 Journey 状态	草稿或暂停	运行中（带有一个 API 启动节点）
运行频率	每次状态改变时运行一次	重复运行，根据用户进入的需求

请求和响应格式

• 内容类型：application/json。
• v3 字段名使用 snake_case。枚举值被序列化为其字符串名称（例如，"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 状态码。

快速入门

启动一个 Journey

curl -X POST https://journey-api.svc-nue.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 对象

节点参考