跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt

Use this file to discover all available pages before exploring further.

向个人或小组发送及时和个性化的消息对于提供强大的客户体验和维持参与度至关重要。交易消息——如一次性密码 (OTP)、账单更新或活动确认——允许您从服务器分享有意义的实时更新。 本指南解释如何使用 OneSignal API 通过自定义数据和用户标识符发送交易消息（推送、电子邮件或 SMS）。

​
常见用例

使用交易消息来：
  • 发送登录和验证码 (OTP)
  • 确认订单、收据或订阅更改
  • 发送账单状态或续订提醒
  • 提醒用户有关约会或截止日期
  • 确认关键操作（例如注册或购买）

​
要求

在发送交易消息之前，我们建议阅读以下指南：

​
识别用户

要定向单个用户，您必须在 OneSignal 中识别他们。推荐的方法是设置 External ID，它应该映射到您在数据库或 CRM 中使用的用户标识符。 OneSignal 还支持每个用户最多 20 个别名，使您能够在您的系统中关联多个标识符（例如 other_user_id、facebook_id 等）。对于电子邮件和 SMS，您也可以分别使用电子邮件地址或电话号码直接发送消息。

​
定向用户

使用 创建消息 API 通过别名、电子邮件地址、电话号码或订阅 ID 定向用户，在推送、电子邮件和 SMS 渠道上发送交易消息。

​
发送到别名（推荐）

使用 include_aliases 来定向推荐的 external_id 或其他别名，如下所示： 
{
  "app_id": "YOUR_APP_ID",
  "include_aliases": {"external_id": ["userA", "userB"]},
  "contents": {"en": "English Message"},
  "target_channel": "push"
}

​
发送到订阅

如果您想要发送到特定的订阅，您可以使用 include_subscription_ids 属性。不推荐这个选项，因为用户可以有多个订阅。 
{
  "app_id": "YOUR_APP_ID",
  "include_subscription_ids": ["1dd608f2-c6a1-11e3-851d-000c2940e62c"],
  "contents": { "en": "English Message" }
}

​
发送到电子邮件地址

如果您有用户的电子邮件地址，您可以使用 include_email_tokens 属性向他们发送电子邮件。 包含的任何在您的 OneSignal 应用中不存在的电子邮件将自动创建新的电子邮件订阅。 
{
  "app_id": "YOUR_APP_ID",
  "include_email_tokens": ["user1@email.com", "user2@email.com"],
  "email_subject": "Welcome to Cat Facts!",
  "email_body": "<html><head>Welcome to Cat Facts</head><body><h1>Welcome to Cat Facts</h1><h4>Learn more about everyone's favorite furry companions!</h4><hr/><p>Hi Nick,</p><p>Thanks for subscribing to Cat Facts! We can't wait to surprise you with funny details about your favorite animal.</p><h5>Today's Cat Fact (March 27)</h5><p>In tigers and tabbies, the middle of the tongue is covered in backward-pointing spines, used for breaking off and gripping meat.</p><a href='https://catfac.ts/welcome'>Show me more Cat Facts</a><hr/><p><small>(c) 2018 Cat Facts, inc</small></p><p><small><a href='[unsubscribe_url]'>Unsubscribe</a></small></p></body></html>"
}

​
发送到电话号码

如果您有用户的电话号码，您可以使用 include_phone_numbers 属性向他们发送 SMS 和 MMS。 包含的任何在您的 OneSignal 应用中不存在的电话号码将自动创建新的 SMS 订阅。 
{
  "app_id": "YOUR_APP_ID",
  "include_phone_numbers": ["+15555555555"],
  "contents": { "en": "English Message" }
}

​
添加自定义数据

对于个性化内容，使用模板和 Liquid 语法将用户特定的 custom_data 传递给消息。 添加自定义数据的步骤：
  1. 通过仪表板或 创建模板 API 创建 模板。
  2. 在您的模板中添加 Liquid 变量（例如 {{ message.custom_data.order_id }}）。
  3. 在您的创建消息 API 调用中引用 template_id 和 custom_data。
{
  "app_id": "YOUR_APP_ID",
  "include_aliases": { "external_id": ["userA"] },
  "template_id": "8458af75-4da2-4ecf-afb5-f242a8926cc3",
  "custom_data": { "order_id": 123, "currency": "USD", "amount": 25 }
}

​
示例：一次性密码 (OTP)

  1. 使用别名、电子邮件或电话号码识别用户。
  2. 创建包含验证码的模板：
您的验证码是 {{ message.custom_data.verification_code }}
  1. 当用户请求访问时，在您的服务器上生成 verification_code。
  2. 将 verification_code 值输入到 API 请求中。
{
  "app_id": "YOUR_APP_ID",
  "include_aliases": { "external_id": ["userA"] },
  "template_id": "8458af75-4da2-4ecf-afb5-f242a8926cc3",
  "custom_data": { "verification_code": "123456" }
}
替代方案： 如果您不想使用模板和 custom_data，您可以通过字符串连接直接将变量值输入到消息中。例如： 
{
  "app_id": "YOUR_APP_ID",
  "include_aliases": {"external_id": ["userA"]},
  "contents": {"en": "Your verification code is " + verification_code}
}

​
故障排除

  • 对于 include_aliases，别名必须事先在用户上注册。
  • 对于电子邮件/SMS，确保格式正确。

​
附加资源