---
title: "令牌"
description: "你可以放进消息里的每一个令牌、Pyn 用什么填充它、值缺失时回退到的文本，以及日期和姓名的格式。"
sidebar:
  order: 3
area: flows
feature: steps
appPath: /flows/home
lastVerified: 2026-11-15
version: "2026-10-23"
audience: admin
related:
  - flows/steps/format-a-message
  - flows/steps/choose-recipients-and-cc
  - flows/automations/enroll-from-a-spreadsheet
  - integrations/hibob/field-mapping
intercom:
  - id: "6024180"
    title: List of supported tokens
    url: https://intercom.help/pyn/en/articles/6024180-list-of-supported-tokens
    note: Pyn 1 article
  - id: "6010962"
    title: Add personalization tokens
    url: https://intercom.help/pyn/en/articles/6010962-add-personalization-tokens
    note: Pyn 1 article
  - id: "6005713"
    title: Personalize your content using tokens and custom senders
    url: https://intercom.help/pyn/en/articles/6005713-personalize-your-content-using-tokens-and-custom-senders
    note: Pyn 1 article
  - id: "6023197"
    title: Personalize your Buddy Pyns with Tokens
    url: https://intercom.help/pyn/en/articles/6023197-personalize-your-buddy-pyns-with-tokens
    note: Pyn 1 article
translation:
  source: flows/steps/reference-tokens.mdx
  sourceSha: e10e1379be5cfe5ae62f7a0ec7a37e8c261fc545
---

令牌是一个标记，Pyn 在为某一位收件人格式化消息时会替换它。在编辑器中输入 `@` 插入一个令牌；在 Raw HTML 电子邮件或 Raw HTML Block 中，把它写成 Liquid 标签，`{{ principal.preferredName }}`。`principal` 令牌对应已注册的员工，`recipient` 令牌对应收到消息的人；在发给员工本人的消息中，两者是同一个人。

当值缺失时，令牌会渲染为下表所示的回退文本，除非你在令牌上设置了自己的回退值。姓名、部门和职位来自[目录](https://support.pyn.ai/zh-cn/directory/employees/)中的员工记录。

## 编辑器中的令牌

| 令牌 | 值 | 回退 |
| --- | --- | --- |
| `date.reference` | 该注册的参考日期 | reference date |
| `principal.preferredName` | 常用名，否则为显示名称的第一个词 | Employee |
| `principal.firstName` | 显示名称（或法定姓名）的第一个词 | Employee |
| `principal.preferredFullName` | 常用名加上显示名称中的姓氏 | Employee |
| `principal.legalName` | 法定姓名，否则为显示名称 | Employee |
| `principal.jobTitle` | 职位 | Job Title |
| `principal.department` | 部门 | department |
| `principal.location` | 地点 | location |
| `principal.startDate` | 入职日期 | start date |
| `principal.startDate.dayAfter` | 入职日期的后一天 | start date |
| `principal.startDate.nextBusinessDay` | 入职日期之后的下一个工作日 | start date |
| `principal.tenure` | 发送时距司龄起算日期（或入职日期）的整年数："1 year"、"3 years" | tenure |
| `principal.birthday` | 以日和月表示的生日，例如 "28 Jul" | Birthday |
| `principal.nextBirthday` | 参考日期当天或之后的下一个生日 | next Birthday |
| `principal.nextAnniversary` | 参考日期当天或之后的下一个入职周年纪念日 | next Anniversary |
| `principal.managerName` | 经理的显示名称 | Manager |
| `principal.managerPreferredName` | 经理的常用名 | Manager |
| `principal.managerEmail` | 经理的工作邮箱 | manager email |
| `principal.buddy.name` | 伙伴的显示名称 | Buddy |
| `principal.buddy.preferredName` | 伙伴的常用名 | Buddy |
| `principal.buddy.preferredFullName` | 伙伴的常用名和姓氏 | Buddy |
| `principal.buddy.email` | 伙伴的工作邮箱 | buddy email |
| `principal.buddy.startDate.nextBusinessDay` | 伙伴入职日期之后的工作日 | start date |
| `principal.hrbp.name` | HR 业务伙伴的显示名称 | HRBP |
| `principal.hrbp.preferredName` | HR 业务伙伴的常用名 | HRBP |
| `principal.hrbp.preferredFullName` | HR 业务伙伴的常用名和姓氏 | HRBP |
| `principal.hrbp.email` | HR 业务伙伴的工作邮箱 | HRBP email |
| `recipient.preferredName`、`recipient.firstName`、`recipient.preferredFullName`、`recipient.legalName` | 同上，针对收件人 | Employee |
| `recipient.department`、`recipient.location` | 同上，针对收件人 | department、location |
| `recipient.startDate` | 收件人的入职日期 | start date |
| `recipient.birthday`、`recipient.nextBirthday`、`recipient.nextAnniversary` | 同上，针对收件人 | Birthday、next Birthday、next Anniversary |
| `recipient.surveyLink` | 存储在收件人记录上的一个链接；渲染为链接，或者什么都不显示 | |

电子邮件的 **Subject** 提供较小的一组：主体和收件人的常用名、生日、下一个生日和下一个周年纪念日。Jira 工单的 **Summary** 和 **Description** 提供十二个 `principal` 令牌：`principal.department`、`principal.email`、`principal.employeeNumber`、`principal.jobTitle`、`principal.legalName`、`principal.location`、`principal.managerEmail`、`principal.managerName`、`principal.name`、`principal.preferredFullName`、`principal.preferredName` 和 `principal.startDate`。

## Raw HTML 的令牌

Raw HTML 电子邮件或 [Raw HTML Block](https://support.pyn.ai/zh-cn/flows/steps/format-a-message/#raw-html-block) 按 Liquid 名称解析上面的每一个令牌，另外还有这些：

| 令牌 | 值 | 回退 |
| --- | --- | --- |
| `company.name` | 工作区的公司名称 | company |
| `date.today` | 发送日期 | today |
| `date.tomorrow` | 发送日期的后一天 | tomorrow |
| `principal.name`、`recipient.name` | 显示名称 | Employee |
| `principal.email`、`recipient.email` | 工作邮箱 | email address |
| `principal.personalEmail`、`recipient.personalEmail` | 个人邮箱 | personal email address |
| `principal.endDate`、`recipient.endDate` | 离职日期 | end date |
| `principal.city`、`principal.country`、`recipient.city`、`recipient.country` | 城市和国家 | city、country |
| `recipient.jobTitle` | 收件人的职位 | Job Title |
| `recipient.tenure` | 发送时距收件人司龄起算日期（或入职日期）的年数，四舍五入到整年，渲染为 `1 year` 或 `N years` | tenure |

Pyn 不认识的 Liquid 名称会按原样留在电子邮件中。

## 自定义令牌和员工字段令牌

- `custom.<column>`：用来注册此人的邮件合并电子表格中的一列，以驼峰式命名（`Start Location` 变成 `custom.startLocation`）。用 **Insert widget**、**Custom Token** 插入。回退为列名；没有值的 **Custom Token Block** 渲染为你的回退文本，或者什么都不显示。见[从电子表格注册](https://support.pyn.ai/zh-cn/flows/automations/enroll-from-a-spreadsheet/)。
- 员工字段令牌：员工记录上的任意字段，用 **Insert token**、**Employee Field** 选择，应用于主体或收件人，并可输入一个可选的回退值。没有回退值时，缺失的值渲染为空。

## 格式

- 日期按收件人的区域设置渲染为星期、日、月和年，例如 "Thu, 22 Oct 2026"。生日渲染为日和月。
- `date.today` 和 `date.tomorrow` 取自该投递的排定时间；在没有发送时间的预览中，它们显示回退文本。
- 司龄四舍五入到整年，所以入职十一个月的人显示为 "1 year"。
- 位于加粗或带颜色文本段中的令牌保留该格式。

## Pyn 不再填充的名称

以下来自 Pyn Classic 的名称仍被接受，但渲染为空：`date.nextBusinessDay`、每一个 `manager.*` 令牌（改用 `principal.managerName`、`principal.managerPreferredName` 和 `principal.managerEmail`）、`principal.homeAddress`、`principal.employeeNumber`、`principal.employmentType`、`principal.mobilePhone`、`principal.brand`、`principal.buddy.jobTitle`、`principal.buddy.location`、`principal.buddy.startDate`、`principal.buddy.startDate.dayAfter`、`principal.returnsFromLeaveOn`、它们对应的 `recipient` 版本，以及 `recipient.startDate.dayAfter` 和 `recipient.startDate.nextBusinessDay`。

## 相关

- [设置消息格式](https://support.pyn.ai/zh-cn/flows/steps/format-a-message/)，了解如何插入令牌、自定义令牌和员工字段。
- [选择收件人和抄送](https://support.pyn.ai/zh-cn/flows/steps/choose-recipients-and-cc/)，了解每个步骤上主体和收件人各是谁。
- [从电子表格注册](https://support.pyn.ai/zh-cn/flows/automations/enroll-from-a-spreadsheet/)，了解自定义令牌列。
- [HiBob 字段映射](https://support.pyn.ai/zh-cn/integrations/hibob/field-mapping/)，了解连接 HiBob 后每个令牌背后的 Bob 字段。
