--- title: Notifications Templates description: The templates endpoints manage notifications templates and notifications contents. Each content is based on one specific template. Each template can be associated with multiple contents. component: pingone-api page_id: pingone-api:platform:notifications/notifications-templates canonical_url: https://developer.pingidentity.com/pingone-api/platform/notifications/notifications-templates.html section_ids: notifications-templates-settings: Notifications templates settings notification-templates-assignment-and-initiation: Notification templates assignment and initiation runtime-logic-for-content-selection: Runtime logic for content selection content-language-selection-examples: Content language selection examples creating-custom-contents: Creating custom contents variants: Variants variables: Variables predefined-variables: Predefined variables dynamic-variables: Dynamic variables filtering-result-data: Filtering result data ordering-result-data: Ordering result data properties: Properties template-properties: Template Properties notifications-templates-content-properties: Content Properties notifications-templates-events-generated: Notifications Templates events generated response-codes: Response codes --- # Notifications Templates The templates endpoints manage notifications templates and notifications contents. Each content is based on one specific template. Each template can be associated with multiple contents. Each environment has a set of predefined notifications templates it can access. A template represents a specific process flow, for example, `device_pairing` or `strong_authentication`, that requires a notification. Each template defines the `deliveryMethods` (`Email`, `SMS`, `Voice`, `WhatsApp`, or `Push`) that it supports. You can read templates with this API, but you cannot create, update, or delete them. []() ## Notifications templates settings | Template name | ID | Description | Delivery methods | Supported predefined variables | Dynamic variables allowed | | --------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | Account Created | `account_created` | Users will receive this message when their account is created as a result of a PingOne DaVinci flow | `Email` | `environmenturl` (required) | Yes | | Credential Issued | `credential_issued` | Users will receive this message when a credential is issued to them | `SMS`, `Email`, `Push` | `credential.name` (optional), `user.username` (optional), `user.name.given` (optional), `user.name.family` (optional) | No | | Credential Revoked | `credential_revoked` | Users will receive this message when a credential they have is revoked | `SMS`, `Email`, `Push` | `credential.name` (optional), `user.username` (optional), `user.name.given` (optional), `user.name.family` (optional) | No | | Credential Updated | `credential_updated` | Users will receive this message when a credential they have is updated | `SMS`, `Email`, `Push` | `credential.name` (optional), `user.username` (optional), `user.name.given` (optional), `user.name.family` (optional) | No | | Credential Verification Push | `credential_verification` | Users' digital wallet will receive this message as a pushed notification of creation of a credential verification session | `Push` | None | No | | Device pairing | `device_pairing` | Users will receive this message to pair their device for strong authentication | `SMS`, `Email`, `Voice`, `WhatsApp` | `otp` (required), `user.username` (optional), `user.name.given` (optional), `user.name.family` (optional), `current-year` (optional). For WhatsApp content, only `otp` is supported. | Yes (for delivery methods other than WhatsApp) | | Digital Wallet Pairing | `digital_wallet_pairing` | Users will receive this message to setup and pair a digital wallet | `SMS`, `Email` | `app.open.url` (required), `user.username` (optional), `user.name.given` (optional), `user.name.family` (optional) | No | | Email Address Verification (Admin) | `email_verification_admin` | Admins will receive this message to verify their email address | `Email` | `code` (required), `user.username` (optional), `user.name.given` (optional), `user.name.family` (optional) | No | | Email Address Verification (User) | `email_verification_user` | Users will receive this message to verify their email address | `Email` | `code` (required), `user.username` (optional), `user.name.given` (optional), `user.name.family` (optional) | No | | Email and Phone Verification for Verify | `email_phone_verification` | Users will receive this message to verify their phone number or email address for a verify transaction | `SMS`, `Email` | `otp` (required), `user.username` (optional), `user.name.given` (optional), `user.name.family` (optional) | No | | General | `general` | Use this multi-purpose template to create custom notifications | `SMS`, `Email`, `Voice` | `user.username` (optional), `user.name.given` (optional), `user.name.family` (optional), `current-year` (optional) | Yes | | ID Verification | `id_verification` | Users will receive this message to verify their email address | `SMS`, `Email` | `app.open.url` (required), `user.username` (optional), `user.name.given` (optional), `user.name.family` (optional) | No | | New Device Paired | `new_device_paired` | When a new device is paired, a notification will be sent to the user that a device has been registered to their account | `SMS`, `Email` | `device.name` (required), `org.name` (optional), `report.fraud` (optional) - inserts a link for reporting fraudulent pairing attempts | No | | Password Change (Admin) - DaVinci | `password_change_admin` | Users will receive this email when their password is changed by an administrator in a PingOne DaVinci flow. Learn more in the [PingOne Connector](https://docs.pingidentity.com/connectors/p1_connector.html) documentation. | `Email` | | Yes | | Password Change (End User) - DaVinci | `password_change_user` | Users will receive this email when they change their own password in a PingOne DaVinci flow. Learn more in the [PingOne Connector](https://docs.pingidentity.com/connectors/p1_connector.html) documentation. | `Email` | `user.time` (required), `user.device` (required) | Yes | | Password Recovery | `recovery_code_template` | Users who need to reset their password will receive this message | `Email` | `code.value` (required), `user.username` (optional), `user.name.given` (optional), `user.name.family` (optional) | No | | Strong Authentication | `strong_authentication` | Users will receive this message for strong authentication | `SMS`, `Email`, `Push`, `Voice`, `WhatsApp` | `otp` (required for `SMS`, `Email`, `Voice`), `user.username` (optional), `user.name.given` (optional), `user.name.family` (optional), `current-year` (optional). For WhatsApp content, only `otp` is supported. | Yes (for delivery methods other than WhatsApp) | | Transaction | `transaction` | Users will receive this message for transaction approval | `SMS`, `Email`, `Push`, `Voice` | `otp` (required for `SMS`, `Email`, `Voice`), `user.username` (optional), `user.name.given` (optional), `user.name.family` (optional) | Yes | | Verification Code | `verification_code_template` | Users will receive this message to verify their email address | `Email` | `code.value` (required), `user.username` (optional), `user.name.given` (optional), `user.name.family` (optional) | Yes | | Verification Code (DaVinci) | `verification_code_new` | Users will receive this message to verify their email address in DaVinci. DaVinci administrators can use the templates created in PingOne for DaVinci. | `Email` | `code.value` (required), `user.username` (optional), `user.name.given` (optional), `user.name.family` (optional) | Yes | A content defines one message text choice for a notification. Each content is always associated with one template and has one `deliveryMethod` and one `locale`. Each template comes with one predefined default content for each of its supported `deliveryMethods`. You cannot delete or update the default contents with this API. However, you can create custom contents for a template (up to 1000 custom contents per template). To create custom contents, refer to [Creating custom contents](#notifications-templates-creating-custom-contents). | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | **Trial License Environments:** If your environment has a trial license, you cannot use the built-in PingOne email service (@pingone.com) to send [custom email notifications](#notifications-templates-creating-custom-contents). You cannot create custom email notification contents unless you use a custom email domain or your own SMTP server. If you need to use the built-in PingOne email service, your email notifications must use the predefined default email content. | | | | | - | -------------------------------------------------------------------------------------------------------------------------- | | | You need the Environment Admin role to perform operations on notifications templates and notifications contents resources. | []() ## Notification templates assignment and initiation A notification template is defined for a specific process flow to convey information about the process flow to its user. Typically, a service provides a request that can assign a specific `variant`, `locale`, or both (for more information on variants and locales, refer to [Creating custom contents](#notifications-templates-creating-custom-contents)) for a notification used by its process flow. For example, [Create Credential Issuance Rule](../../credentials/credential-issuance-rules/create-credential-issuance-rule.html) has a `notification.template` object that can set the notification template variant and locale for notifications sent when a user credential is created, updated, or revoked through [Apply Credential Issuance Rule Staged Changes](../../credentials/credential-issuance-rules/apply-credential-issuance-rule.html) or its automated equivalent. In this table, the notification template in *Template name* is assigned a variant or locale in the request in *Defined by* and the supported process flow begins with the request in *Initiated by*. | Template name | Defined by | Initiated by | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `account_created` | [Create User](../users/users-1/create-user.html) | [Create User](../users/users-1/create-user.html) or the `VERIFICATION_REQUIRED` flow status when a user verifies their account. | | `credential_issued` | [Create Credential Issuance Rule](../../credentials/credential-issuance-rules/create-credential-issuance-rule.html) or [Update Credential Issuance Rule](../../credentials/credential-issuance-rules/update-credential-issuance-rule.html) | [Apply Credential Issuance Rule Staged Changes](../../credentials/credential-issuance-rules/apply-credential-issuance-rule.html) or its automated equivalent when the issuance rule's `automation.issue` is `PERIODIC`. | | `credential_issued` | [Create a User Credential](../../credentials/user-credentials/create-user-credential.html) | [Create a User Credential](../../credentials/user-credentials/create-user-credential.html) | | `credential_revoked` | [Create Credential Issuance Rule](../../credentials/credential-issuance-rules/create-credential-issuance-rule.html) or [Update Credential Issuance Rule](../../credentials/credential-issuance-rules/update-credential-issuance-rule.html) | [Apply Credential Issuance Rule Staged Changes](../../credentials/credential-issuance-rules/apply-credential-issuance-rule.html) or its automated equivalent when the issuance rule's `automation.revoke` is `PERIODIC`. | | `credential_updated` | [Create Credential Issuance Rule](../../credentials/credential-issuance-rules/create-credential-issuance-rule.html) or [Update Credential Issuance Rule](../../credentials/credential-issuance-rules/update-credential-issuance-rule.html) | [Apply Credential Issuance Rule Staged Changes](../../credentials/credential-issuance-rules/apply-credential-issuance-rule.html) or its automated equivalent when the issuance rule's `automation.update` is `PERIODIC`. | | `credential_updated` | [Update a User Credential](../../credentials/user-credentials/update-a-user-credential.html) | [Update a User Credential](../../credentials/user-credentials/update-a-user-credential.html) | | `credential_verification` | [Create Credential Verification Session (NATIVE - Push Notification)](../../credentials/credential-verifications/create-credential-verification-presentation-session-native-push-notification.html) | [Create Credential Verification Session (NATIVE - Push Notification)](../../credentials/credential-verifications/create-credential-verification-presentation-session-native-push-notification.html) | | `device_pairing` | Defined by the flow status. | Initiated by the `DEVICE_SELECTION_REQUIRED` flow status. | | `digital_wallet_pairing` | [Create Digital Wallet](../../credentials/digital-wallets/create-digital-wallet.html) | [Create Digital Wallet](../../credentials/digital-wallets/create-digital-wallet.html) | | `email_phone_verification` | [Create Verify Policy](../../verify/verify-policy/create-verify-policy.html) or [Update Verify Policy](../../verify/verify-policy/update-verify-policy.html), but cannot define a locale. | [Create Verify Transaction](../../verify/verify-transactions/create-verify-transaction.html) | | `email_verification_admin` | Defined by the flow status. | Initiated by the `VERIFICATION_REQUIRED` flow status. Refer to [Send Email Verification (Code)](../users/user-email-verification/send-email-verification-code.html). | | `email_verification_user` | Defined by the flow status. | Initiated by the `VERIFICATION_REQUIRED` flow status. Refer to [Send Email Verification (Code)](../users/user-email-verification/send-email-verification-code.html). | | `general` | Defined by the flow status. | Initiated by a flow status that sends a one-time passcode through email, SMS, or voice. | | `id_verification` | Cannot define a variant or locale | [Create Verify Transaction](../../verify/verify-transactions/create-verify-transaction.html) | | `new_device_paired` | Add the `notifications` property to the [Create MFA User Device](../../mfa/users/mfa-devices/create-mfa-user-device-email.html) request. | Refer to [MFA Devices](../../mfa/users/mfa-devices.html). | | `recovery_code_template` | Defined by the flow status. | Initiated by the `RECOVERY_CODE_REQUIRED` flow status. The user initiated a `password.forgot` flow action and a recovery code must be sent. | | `strong_authentication` | Defined by the flow status. | Initiated by an MFA flow status that sends a push notification on mobile apps or a one-time passcode through email, SMS, or voice. | | `transaction` | Defined by the `pi.template` property in an authorize request's `request` property JWT. | Initiated by the authorize request. Refer to [Authorize (Transaction Approval)](../../auth/openid-connect-oauth-2/authorize-transaction-approval-.html). | | `verification_code_template` | Defined by the flow status. | Initiated by the `VERIFICATION_REQUIRED` flow status. Refer to [Register User](../../auth/flows/registration-and-verification.html). | | `verification_code_new` | Defined by the flow status. | Initiated by the `VERIFICATION_REQUIRED` flow status. Refer to [Register User](../../auth/flows/registration-and-verification.html). | []() ## Runtime logic for content selection Each content, whether default or custom, is associated with one template, one `deliveryMethod`, one `locale`, and optionally, one `variant` (for more information on variants, refer to [Creating custom contents](#notifications-templates-creating-custom-contents)). When a request for content is executed at runtime, it includes a template, `deliveryMethod`, and optionally a `variant`. When determining the language to use for a notification, PingOne uses the following logic: * The preferred language is determined by: 1. Checking first if `locale` is specified in the API request, for example, in the `notification.template.locale` property for `POST {{apiPath}}/v1/environments/{{envID}}/users/{{userID}}/devices`. 2. If `locale` was not specified in the request, the preferred language that was set for the user in PingOne is used. 3. If there is no preferred language set for the user in PingOne, the Accept-Language header in the request is checked. 4. If the Accept-Language header does not indicate a language preference, the default language for the PingOne environment is used. * Once the language preference has been determined, PingOne checks if there is a notification content that matches. If there is not an exact match, PingOne uses the best match (based on the language, ignoring the region) if available. For example, `es-ES` falls back to `es`. * For voice notifications, PingOne uses the best matching language based on the supported languages of the provider (Twilio, Syniverse, or a custom provider). * The `locale` property supports the syntax defined for the Accept-Language header in [Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content](https://httpwg.org/specs/rfc7231.html#header.accept-language), including the use of quality values. ### Content language selection examples | | | | | | | | --------------------------- | ---------------------- | ----------------------- | --------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Content available languages | Voice provider support | User preferred language | Locale in the request | Resulting notification language | Description | | `fr-CA` `it`(default) | `fr-CA` `it` `en` | `fr-CA` | `fr-CA` | `fr-CA` | User's preference and locale in the request match an available language in the content templates | | `fr-CA` `it`(default) | `fr-CA` `it` `en` | `es` | `es` | `it` | Default content language used: neither user's preference nor locale in the request match an available content language | | `fr-CA` `it`(default) | `fr-CA` `it` `en` | `es` | | `it` | Default content language used: no locale in the request, and no match of user's preference with available content languages | | `fr-CA` `it`(default) | `fr-CA` `it` `en` | | `es` | `it` | Default content language used: no definition for user's preference, and no match of locale in the request with available content languages | | `fr-CA` `it`(default) | `fr-CA` `it` `en` | | | `it` | Default content language used: no definition for both user's preference locale in the request | | `fr-CA` `it`(default) | `fr-CA` `it` `en` | `es` | `fr-CA` | `fr-CA` | Locale in the request used: user's preference does not match an available language in the content templates, but the locale in the request does | | `fr` `it`(default) | `fr` `it` `en` | `es` | `fr-CA` | `fr` | User preferred language doesn't match any of the available contents' locales, but locale in the request has a close match to an available content's locale (`fr ~= fr-CA`). | | `fr-CA` `it` | `fr-CA` `it` `en` | `es` | `es` | `en` | Both user preferred language and locale in the request don't match an available content's locale and there's no available content for the environment's default language. Falling back to English. | | `fr` `it`(default) `es` | `fr` `it` `en` | `fr` | `es` | SMS,email,push:\`es\` Voice:\`fr\` | User preferred language matches an available content's locale (`es`). For notifications of type SMS, Email and Push, `es` will be used. Since `es` is not a supported voice language, for Voice notifications, `fr` will be used, since it matches the locale in the request and is also supported for text-to-speech. | []() ## Creating custom contents Add and update custom contents with `POST {{apiPath}}/v1/environments/{{envID}}/templates/{{templateName}}/contents` and `PUT {{apiPath}}/v1/environments/{{envID}}/templates/{{templateName}}/contents/{{contentID}}`. Each content is associated with one template and has one `deliveryMethod` and one ISO language code (`locale`). You can define multiple custom contents for each template + `deliveryMethod` + `locale` combination with the `variant` property. []() ### Variants If you have more than one custom content that uses the same template, `deliveryMethod`, and `locale`, these contents must have different values for the `variant` property. The `variant` property holds the unique user-defined name for each content variant that uses the same template + `deliveryMethod` + `locale` combination. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you attempt to create a custom content for an existing combination of template, `locale`, `deliveryMethod` and `variant`, you get an `INVALID_DATA`/`UNIQUENESS_VIOLATION` error.Custom notifications variants are not supported for the `recovery_code_template`. | `variant` values can be reused by contents across different template + `deliveryMethod` + `locale` combinations. They need to be unique within the same template + `deliveryMethod` + `locale` combination only. As a best practice, use the same `variant` value for contents with the same message text. For example, the `variant` value `variant_A` can be used by a content with the `strong_authentication` + `email` + `en` combination and also by a content with the `strong_authentication` + `push` + `en` combination. For two contents that both use the `strong_authentication` + `email` + `en` combination though, if one content uses the `variant` value of `variant_A`, the other content must use a `variant` value such as `variant_B`. Use `PATCH environments/{{envID}}/templates/{{templateName}}/contents?filter=variant eq {{variantName}}` to bulk update the `variant` value in contents with the same `variant` value. Use `DELETE environments/{{envID}}/templates/{{templateName}}/contents?filter=variant eq {{variantName}}` to bulk delete contents with the same `variant` value. | | | | - | ---------------------------------------------------------------- | | | `variant` is case insensitive and has a limit of 100 characters. | []() ### Variables Variables are placeholders for values that change depending on the context. For example: * The SMS content is `Hi ${user.username}! Your one time passcode is ${OTP}.` * The `${user.username}` variable has a value of `John`. * The `${OTP}` variable has a value of \`548263 \`. The resulting message is:\ `Hi John! Your one time passcode is 548263`, which includes the variable values `John` and `548263`. | | | | - | ----------------------------------------------------- | | | Notifications content variables are case insensitive. | []() #### Predefined variables If a template includes predefined variables, the template lists which `variables` can be optionally used in its contents and which variables are required in its contents. For example, `user.username` can be optionally used by `strong_authentication` contents, while `otp` is required for all `SMS`, `Voice` and `Email` contents. ```json "variables": { "user.username": { "required": false }, "otp": { "required": true, "requiredForDeliveryMethods": [ "SMS", "Voice", "Email" ] } } ``` | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Before you create or update a custom content, you should always do a [GET Read One Template](notifications-templates/read-one-template.html) on the notification template to determine its supported variables. | []() #### Dynamic variables In addition to predefined variables, most templates also allow dynamic variables. If a template has the property `allowDynamicVariables` set to `true`, its contents can contain any user-defined variable in the format `${variable_name}`. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | Before you create or update a custom content, you should always do a [GET Read One Template](notifications-templates/read-one-template.html) on the notification template to determine its supported variables. In addition, for the `otp` variable, you can configure its cooldown duration, failure count, and lifetime duration properties (refer to [Device Authentication Policies](../../mfa/device-authentication-policy.html)). Password recovery, account verification, and email verification codes use 8 alphanumeric characters. The default timeout for each varies (password recovery = 5 min, account verification = no expiration, email verification = 24 hours). These property values are not configurable. | []() ## Filtering result data You can filter `GET {{apiPath}}/v1/environments/{{envID}}/templates` and `GET {{apiPath}}/v1/environments/{{envID}}/templates/{{templateName}}/contents` results by applying a SCIM filtering expression to the request URL. For large collections, a filtering expression appended to the query returns a targeted, more useful data set. For example, the following URL-encoded SCIM filter returns templates created before 2018-07-30 and updated after 2018-08-30: ```none https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/templates?filter=(createdAt%20lt%20%222018-08-30%22)%20and%20(updatedAt%20gt%20%222018-07-30%22)%20 ``` SCIM operators can be applied to the following attributes: | Collection | Attribute | Supported | | ---------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------ | | Templates and contents collections | `createdAt` | \* eq (equals)\* ne (not equals)\* gt (greater than)\* ge (greater than or equals)\* lt (less than)\* le (less than or equals) | | Templates and contents collections | `updatedAt` | \* eq (equals)\* ne (not equals)\* gt (greater than)\* ge (greater than or equals)\* lt (less than)\* le (less than or equals) | | Contents collections | `default` | \* eq (equals) | | Contents collections | `locale` | \* eq (equals)\* sw (starts with) | | Contents collections | `deliveryMethod` | \* eq (equals) | | Contents collections | `variant` | \* eq (equals)\* sw (starts with) | Additionally, the logical `and` and `or` operators may be used for building compound expressions. []() ## Ordering result data You can order the collections returned by the GET collection endpoints according to the `createdAt` and `updatedAt` attribute. Ordering by any attribute returns the collection in a descending order. Using the attribute with the "\[.code]\`-\`" prefix returns the collection ordered in descending order. For example, the following URL returns all the templates ordered by ascending creation date: ```none https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/templates?order=-createdAt ``` | | | | - | ------------------------------------------------------------------------------------------------ | | | * Multiple columns ordering is not supported. * Default ordering is descending, by `UpdatedAt`. | For more information about SCIM syntax and operators, refer to [Paging and ordering collections](../reference/paging-ordering-collections.html). []() ## Properties []() ### Template Properties | Property | Type | Required? | Mutable? | Description | | ----------------------- | ------- | --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | String | Required | Immutable | The template id. | | `displayName` | String | Required | Mutable | The template's display name. | | `deliveryMethods` | Array | Required | Mutable | The delivery methods supported for this template. Valid values are `SMS`, `Voice`, `Email`, and `Push`. | | `createdAt` | Date | N/A | Read only | The time the resource was created. | | `updatedAt` | Date | N/A | Read only | The time the resource was last updated. | | `description` | String | Optional | Mutable | The description of the template. | | `variables` | Object | Required | Mutable | Lists the variables you can use in each template content. The `required` property indicates whether the variable is required in template content. If `required` is `true`, the `requiredForDeliveryMethods` property lists the `deliveryMethods` types that require the variable. Note that if `required` is `true`, but `requiredForDeliveryMethods` is not returned, all `deliveryMethods` types are required. For more information, refer to [Variables](#notifications-templates-variables). | | `allowDynamicVariables` | Boolean | Required | Mutable | Specifies whether dynamic variables can be used in the template's contents. For more information, refer to [Dynamic variables](#notifications-templates-dynamic-variables). | ### Content Properties | Property | Type | Required? | Mutable? | Description | | ----------------------------- | ------- | ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `body` | String | Required/Optional | Mutable | Only required when `deliveryMethod` is `Email` or `Push`. The email or push text (maximum 400 characters for push text). Email text cannot be larger than 100 kB. Email text can contain HTML. If supported, this can include variables. | | `charset` | String | Optional | Mutable | Relevant when `deliveryMethod` is `Email`. If not specified, `UTF-8` is the default value. | | `content` | String | Required/Optional | Mutable | Only required when `deliveryMethod` is `SMS` or `Voice`. The SMS or voice text.\* **SMS**: UC-2 encoding is used for text that contains non GSM-7 characters. UC-2 encoded text cannot exceed 67 characters. GSM-7 encoded text cannot exceed 153 characters. If supported, it can include variables.\* **Voice**: Limited to 1Kb characters. The following substitution place holders can be embedded in the message:\* ``: Pauses the message narration for 1 second. The pause interval `` cannot be modified. To pause the message narration for more than one second, repeat multiple `` occurrences in succession, according to the desired pause interval duration. For example, `` pauses the message narration for three seconds.\* ` .. `: Reads the character name of each character of the enclosed string separately.\* ` .. `: Narrates the enclosed text `` number of times.In the following message example, `${OTP}` is assigned the value `"123456"`, and `${email}` is assigned the value `"joe@bxz.com"`:\`Hello \ your authentication code is \${otp}\ \ I repeat your code is \${otp}\ \ \ Mail \${email}\ for help\`The narrated message on the voice call sounds like: `HELLO <1 second silence> YOUR AUTHENTICATION CODE IS ONE TWO THREE FOUR FIVE SIX I REPEAT YOUR CODE IS ONE TWO THREE FOUR FIVE SIX I REPEAT YOUR CODE IS ONE TWO THREE FOUR FIVE SIX <1 second silence> MAIL JAY OH EE AT BEE EX ZEE DOT SEE OH EM FOR HELP` | | `createdAt` | Date | N/A | Read only | The time the resource was created. | | `default` | Boolean | Optional | Mutable | Specifies whether the template is a predefined default template. | | `deliveryMethod` | String | Required | Immutable | The content's delivery method. Possible values are `Email`, `SMS`, `Voice`, `Push`, and `WhatsApp`. Cannot be changed after it is initially set in `POST {{apiPath}}/v1/environments/{{envID}}/templates/{{templateName}}/contents`. | | `emailContentType` | String | Optional | Mutable | Relevant when `deliveryMethod` is `Email`. If not specified, `text/html` is the default value. | | `from.address` | String | Optional | Mutable | Relevant when `deliveryMethod` is `Email`. The sender email address. If the environment uses the Ping Identity email sender, or if the address field is empty, the address "noreply\@pingidentity.com" is used. You can configure other email sender addresses per environment. Refer to [Note](#from-replyTo-note) for details. | | `from.name` | String | Optional | Mutable | Relevant when `deliveryMethod` is `Email`. The email's sender name. If the environment uses the Ping Identity email sender, the name "PingOne" is used. You can configure other email sender names per environment. Refer to [Note](#from-replyTo-note) for details. | | `id` | String | N/A | Read only | The template id. | | `locale` | String | Required | Immutable | A valid case-insensitive locale, complying with the ISO-639 language code and ISO-3166 country code standards:\* Two-character language code, for example, "en".\* Two-character language code followed by a two-character country code, separated by an underscore or dash, for example: "en\_GB", "en-GB".Cannot be changed after it is initially set in `POST {{apiPath}}/v1/environments/{{envID}}/templates/{{templateName}}/contents`. | | `pushCategory` | String | Optional | Mutable | For Push content, you can specify what type of banner should be displayed to the user. The available options are:\* BANNER\_BUTTONS - the banner contains both Approve and Deny buttons\* WITHOUT\_BANNER\_BUTTONS - when the user clicks the banner, they are taken to an application that contains the necessary approval controls.\* APPROVE\_AND\_OPEN\_APP - when the Approve button is clicked, authentication is completed and the user is taken to the relevant application.If this parameter is not provided, the default is BANNER\_BUTTONS. Note that to use the non-default push banners, you must implement them in your application code, using the PingOne SDK. For details, refer to the [README for iOS](https://github.com/pingidentity/pingone-mobile-sdk-ios/#171-push-notifications-categories) and the [README for Android](https://github.com/pingidentity/pingone-mobile-sdk-android). | | `replyTo.address` | String | Optional | Mutable | Relevant when `deliveryMethod` is `Email`. The "reply to" email address. If the environment uses the Ping Identity email sender, or if the address field is empty, the address "noreply\@pingidentity.com" is used. You can configure other email "reply to" addresses per environment. Refer to [Note](#from-replyTo-note) for details. | | `replyTo.name` | String | Optional | Mutable | Relevant when `deliveryMethod` is `Email`. The email's "reply to" name. If the environment uses the Ping Identity email sender, the name "PingOne" is used. You can configure other email "reply to" names per environment. Refer to [Note](#from-replyTo-note) for details. | | `sender` | String | Optional | Mutable | Relevant when `deliveryMethod` is `SMS`. The SMS sender ID. This property can contain only alphanumeric characters and spaces, and its length cannot exceed 11 characters. In some countries, it is impossible to send an SMS with an alphanumeric sender ID. For those countries, the sender ID must be empty. For SMS recipients in specific countries, refer to Twilio's documentation on [International support for Alphanumeric Sender ID](https://support.twilio.com/hc/en-us/articles/223133767-International-support-for-Alphanumeric-Sender-ID). | | `subject` | String | Optional | Mutable | Relevant when `deliveryMethod` is `Email`. The email's subject line. Cannot exceed 256 characters. If supported, can include variables. | | `template.id` | String | N/A | Read only | The ID of the template type, for example, `device_pairing` or `transaction`. | | `title` | String | Optional | Mutable | Relevant when `deliveryMethod` is `Push`. The push title (maximum 200 characters). If supported, this can include variables. | | `twilioVerifyTemplate.id` | String | Optional | Mutable | The Twilio ID of the Verify template to use. Can be included when using Twilio Verify. | | `twilioVerifyTemplate.locale` | String | Optional | Mutable | The locale of the Verify template to use. Required if you have specified a value for `twilioVerifyTemplate.id`. | | `updatedAt` | Date | N/A | Read only | The time the resource was last updated. | | `variant` | String | Optional | Mutable | Holds the unique user-defined name for each content variant that uses the same template + `deliveryMethod` + `locale` combination. This property is case insensitive and has a limit of 100 characters. For more information, refer to [Creating custom contents](#notifications-templates-creating-custom-contents). | | `voice` | String | Optional | Mutable | Relevant only if `deliveryMethod` is `Voice`. Options are `Alice`, `Man`, or `Woman`. Voice OTP supports vendor-specific voices.\* Supported Twilio voices:\
    \
  • Man, Woman Supported locales (default: en): en, en\_GB, es, fr, de\* Alice (Twilio only) Supported locales (default: en US): da\_DK, de\_DE, en\_AU, en\_CA, en\_GB, en\_US, ca\_ES, es\_ES, es\_MX, fi\_FI, fr\_CA, fr\_FR, it\_IT, ja\_JP, ko\_KR, nb\_NO, nl\_NL, pl\_PL, pt\_BR, pt\_PT, ru\_RU, sv\_SE, zh\_CN, zh\_HK, zh\_TW\* Amazon Polly cy\_GB, ro\_RO, is\_IS, hi\_IN tr\_TR\* Supported Syniverse voices:\* Man, Woman Supported locales: en\_US, en\_GB, es\_ES, es\_US, fr\_FR, de\_DE, it\_IT, en\_AU, da\_DK, is\_IS, nl\_NL, pl\_PL, pt\_BR, pt\_PT, ru\_RU, ja\_JP\* Woman only Supported locales: cmn\_CN, cy\_GB, en\_IN, fr\_CA, hi\_IN, nb\_NO, ro\_RO, sv\_SE, tr\_TR, ko\_KR, ar | | `whatsAppTemplate` | Object | Required | Mutable | Required when creating content for WhatsApp delivery. Contains the necessary information for identifying the WhatsApp template that should be used for the content. Use `{{apiPath}}/v1/environments/{{envID}}/notificationsSettings/instantMessagingDeliverySettings/whatsApp?expand=whatsAppTemplates` to get the details of all the available WhatsApp templates, as shown in the [Read WhatsApp Delivery Settings (including templates)](instant-messaging-delivery-settings/read_whatsapp_delivery_settings_including_templates.html) example. Note that the object returned for each template is identical in structure to the structure of the `whatsAppTemplate` object, so template details can be copied directly from that response. | | `whatsAppTemplate.category` | String | Optional | Mutable | If included, should be set to `AUTHENTICATION`. | | `whatsAppTemplate.id` | String | Required | Mutable | The WhatsApp-provided ID of the template. | | `whatsAppTemplate.language` | String | Required | Mutable | The language of the template. | | `whatsAppTemplate.name` | String | Required | Mutable | The name of the template. | []() | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | * If the environment is configured to use the Ping Identity email sender, only trusted email addresses can be used for `from.address` and `replyTo.address`. * If the environment is configured to use a custom email sender, any email addresses can be used for for `from.address` and `replyTo.address`. * If the `from` or `replyTo` settings are empty, PingOne uses the `from` or `replyTo` settings respectively, that are defined in `notificationsSettings`. * If the `from` or `replyTo` settings are not defined in the content or in `notificationsSettings`, PingOne uses the default `from.name` (`PingOne`) and `from.address` (`noreply@pingidentity.com`), and `replyTo.name` and `replyTo.address` are not populated. * When switching the configuration from a custom email sender to to use the Ping Identity email sender, any untrusted email address that is configured for existing contents is ignored and PingOne uses the trusted address that's defined in `notificationsSettings`. | ## Notifications Templates events generated Refer to [Audit Reporting Events](../reference/audit-reporting-events.html) for the events generated. []() ## Response codes | Code | Message | | ---- | ---------------------------------------- | | 200 | Successful operation. | | 201 | Successfully created. | | 204 | Successfully removed. No content. | | 400 | The request could not be completed. | | 401 | You do not have access to this resource. | | 404 | The requested resource was not found. |