事务性消息与级联发送
事务性消息包括订单确认、登录验证码和配送通知。客户正在等待这些消息，因此它们会立即通过单独的队列发出：大规模群发不会延误它们。级联发送会依次通过多个渠道发送同一条消息。例如，先发 WhatsApp，如果 2 分钟内未送达，再发 SMS。
您可以从旅程中发送此类消息，也可以通过 API 从您自己的服务器发送。
事务性模板
要让消息被视为事务性消息，请在其模板中勾选事务性消息。此类消息发送时不检查订阅、频率限制和免打扰时段。通过 OneTrace.ru 邮件服务发送的邮件无需预热，并使用单独的发送流，邮件头中不含退订链接。
请勿将广告标记为事务性消息：这会侵犯收件人的权益，并损害发件人信誉。
如果收件人的渠道已关闭，即使是事务性消息也不会发出：
| 渠道 | 何时关闭 |
|---|---|
| 邮件 | 发往该地址的邮件因永久性错误被退回（邮箱不存在） |
| SMS、WhatsApp | 服务商报告号码不存在；客户在 WhatsApp 中发送了“stop” |
| Telegram | 客户向机器人发送了 /stop 或屏蔽了机器人 |
| Viber | 客户取消订阅了机器人 |
此类消息的状态为“已跳过”，原因是“该收件人的渠道已被封锁”。当客户重新订阅时，例如在机器人中点击“Start”，渠道会重新开放。垃圾邮件投诉不会关闭渠道：发往该地址的订单邮件仍会继续送达。
通过 API 发送
您的服务器通过 POST /api/v1/messages 请求发送消息。需要具有“发送单条消息”权限的私密密钥，参见API 密钥。
curl -X POST https://cdp.onetrace.ru/api/v1/messages \
-H "Authorization: Bearer $CDP_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-A-1001" \
-d '{
"identity": {"type": "email", "value": "anna@example.com"},
"template_id": 12,
"traits": {"first_name": "安娜"},
"data": {"order_id": "A-1001", "amount": 4990}
}'
| 字段 | 含义 |
|---|---|
identity |
收件人：标识符的类型和值，例如 email、phone、user_id、telegram_chat_id 等。如果档案不存在，会自动创建 |
template_id |
消息模板。其 id 显示在模板页面的地址中 |
integration_id |
模板所属渠道的集成。仅当该渠道有多个启用的集成时才需要 |
traits |
发送前写入档案的属性。在模板中使用 {{ traits.first_name }} |
data |
仅属于这条消息的数据。在模板中使用 {{ context.data.order_id }} |
响应 202 包含消息的 id 及其状态。GET /api/v1/messages/{id} 返回当前状态：queued、sent、delivered、failed、skipped 等，并附带跳过或出错的原因。
- **重试是安全的。**带有相同
Idempotency-Key请求头的请求会返回已创建的消息，不会发送第二条。请使用订单号或操作 id。 - 每个收件人的上限为通过 API 每小时 20 条消息。超出时会返回
429，并带有Retry-After请求头。 - 普通模板（未勾选“事务性”）也可以通过 API 发送。此时会检查所有消息规则。
在现成的 PHP 库中，对应的调用是 $onetrace->messages()->send(Identity::email('anna@example.com'), 12, ['data' => [...]], 'order-A-1001')，在 Laravel 包中是 messages()->send(...)。
旅程中的级联发送
从“动作”组向旅程添加级联发送节点。在按顺序的渠道字段中设置 2 到 5 个步骤。为每个步骤指定：
- 渠道的集成和模板。
- 等待：以什么作为成功，“已发送”“已送达”或“已读”。
- 等待时间：适用于“已送达”和“已读”，默认为 15 分钟。
在以下情况下，级联发送会进入下一步：
- 档案没有该渠道的地址或号码，或其渠道已关闭：该步骤会被立即跳过，不会创建消息；
- 消息未发出：发送出错，或因消息规则被跳过；
- 服务商报告未送达；
- 在等待时间内没有收到送达或已读确认。
并非所有渠道都支持等待送达和已读：
| 等待 | 渠道 |
|---|---|
| 已发送 | 全部 |
| 已送达 | SMS、WhatsApp、Viber、Telegram、Webhook；邮件仅限通过 OneTrace.ru 邮件服务发送，自有 SMTP 服务器不支持 |
| 已读 | 邮件、WhatsApp、Viber |
该节点有两个出口：已触达表示某一步骤的消息达到了目标；失败表示所有渠道都未成功。级联发送进行期间，参与者在该节点等待。
级联发送投递的是同一条消息。“购物车：push → 邮件 → SMS”这类旅程模板的机制不同：在客户下单之前，会间隔一段时间发送不同的消息。
通过 API 级联发送
请传入 steps 代替 template_id，其步骤与旅程节点中的相同：
{
"identity": {"type": "phone", "value": "+79991234567"},
"steps": [
{"integration_id": 3, "template_id": 21, "wait_for": "delivered", "timeout": {"amount": 2, "unit": "minute"}},
{"integration_id": 4, "template_id": 22, "wait_for": "sent"}
],
"data": {"code": "482913"}
}
wait_for 可取 sent、delivered 或 opened，timeout 的单位为 minute、hour、day、week。响应 202 包含级联的 id，GET /api/v1/messages/cascades/{id} 返回其状态：
status：running、reached或failed；- 当前步骤
step； - 成功的渠道
reached_channel； - 各步骤的消息
messages。
套餐
事务性消息和通过 API 发送适用于所有套餐。级联发送从“增长版”套餐起可用，参见套餐与付款。在“入门版”中，编辑器面板中的该节点会显示锁形图标，API 会返回 402。如果套餐降级，已运行的旅程中只会发送级联的第一步。