Communication Templates

Overview

Communication templates in cidaas provide pre-structured frameworks for delivering consistent messages to users across email, SMS, IVR, and push notifications. Templates enable you to maintain brand voice and styling while automating user communications such as welcome messages, password resets, account verifications, and security alerts.

The template system includes group-specific settings for locale and language preferences, ensuring effective localized communication. You can configure communication providers within each template group to ensure seamless messaging delivery through appropriate platforms.

Key Benefits

• Efficiency: Pre-defined templates eliminate the need to create messages from scratch for each communication
• Brand Consistency: Ensures all communications align with your brand voice, tone, and style across teams and channels
• Clear Structure: Provides logical frameworks that make messages easier to read and understand
• Scalability: Useful for large teams to maintain alignment in messaging tone and content
• Customization: Templates support dynamic elements for audience-specific messaging while retaining consistent structure
• Multi-channel Support: Easily adapted for multiple communication channels including email, SMS, IVR, and push notifications

Template Architecture

cidaas organizes communication templates into template groups. Each template group contains multiple templates, and each template is classified by a template type. The following diagram illustrates this structure:

Built-in Template Groups

cidaas provides two built-in template groups:

• default: Contains pre-configured communication templates for common use cases
• developer: An empty template group for custom, non-cidaas-based communications

Developer templates

Use the developer template group for custom template types—messages that are not in cidaas’s fixed system template catalog. You identify each template by templateKey, locale, and communication method, same as other templates.

System templates vs developer templates

	cidaas system templates	Developer templates
Template keys	Fixed catalog (for example WELCOME_USER, VERIFY_USER)	Keys from your custom template types
Typical trigger	cidaas services (registration, verification, …)	Your application calls the API when you choose
Template group	Usually default or a group copied from it	Built-in group developer (groupId: developer)

Quick reference

Topic	What to use
Group	developer
Send API	Send Template-Based Notifications
Criteria (identify template)	templateKey, groupId (developer), commMethod, locale (as needed)
Payload (rendering)	Merge system, custom, and context attributes into subject/body placeholders

How content is built

Approach	What you do
Placeholders in the template	Define subject/body in Admin or API with double braces for normal substitution (for example {{given_name}}, {{orderId}}). At send time, pass attribute values in the request; they are merged and substituted.
Full HTML from the payload	Use triple braces so the value is inserted as raw HTML: for example {{{emailHtml}}}. Pass the entire HTML string as that attribute—useful when markup is generated outside the template.

Setup (summary):

• Create a custom template type, then templates under the developer group (Template > Template, filter by developer). Configure providers for that group like any other group.
• Step-by-step: How to Create Custom Template Types (including the developer group filter in Step 2).

Application-triggered notification flow

Your application calls the notification service directly (not via a cidaas domain service for lifecycle events). The service loads the template, renders it with your attributes, and delivers through the communication provider for that group and channel.

Customizing Communication Templates

The default template group can be customized to match your brand requirements in terms of appearance and content. You can also create custom template groups by copying the default group and customizing sender names, communication providers, layouts, and content.

Best Practices

1. Customize the default template group to follow your corporate style guidelines
2. Create separate template groups for brand-specific layouts and messaging requirements

Template Selection Criteria

The template selection process depends on several factors:

1. Available Communication Channels: Which channels are available for reaching the user (email address, phone number, or cidaas Authenticator App)?
2. Communication Purpose:
   • User verification requires secure communication channels (linked to verification procedures in cidaas)
   • Some notifications can be turned off in the Admin Portal when the template type is deactivatable; see Template activation defaults
   • Settings should be applied uniformly across all locales and template groups
3. Client Configuration: Template groups are assigned to applications, allowing different clients to use different communication templates

Language and locale selection

Selecting a template requires a match on templateKey, locale, communicationMethod, and the app's groupId (see Template Selection Criteria). How locale is determined depends on whether cidaas triggered the notification (system templates) or your application called Send Template-Based Notifications (developer templates or explicit API sends).

cidaas system templates (Auth and requestId flows)

For notifications sent by cidaas services during login, registration, verification, and similar flows, locale is resolved in this order:

Priority	Source	Explanation
1	ui_locales	From the Authorization (Authz) request, stored with requestId and reused across the hosted-page flow for that login session. Reflects the user or client preferred languages (OIDC parameter; space-separated BCP 47 tags, for example de en). See ui_locales in the Authz API reference.
2	Accept-Language	HTTP header from the browser when ui_locales is not set.
3	Locale fallback within the template group	If no template exists for the exact tag (for example en-GB), cidaas tries the base language (en). If still no match, the template group defaultLocale is used (configured in the Admin Portal under Language and locale selection).

The requestId from Authz ties the language preference to the active authentication flow: downstream calls (hosted pages, field setup, account initiation) use the same requestId so the locale from Authz stays consistent for that session. See Authentication and hosted-page examples that pass requestId in query parameters.

A matching template must exist for the resolved locale and channel, be enabled, and be published. Disabled or draft templates are skipped (no message sent).

For a flow-specific example (VERIFY_ACCOUNT, processing types LINK/CODE), see Communication Medium Verification.

Application-triggered notifications (Send API and developer group)

When your application sends notifications (typically templates in the developer group), locale is set explicitly in the API request:

Field	Behavior
criteria.locale	Preferred locale for the template (for example de-DE)
criteria.defaultLocale	Fallback if no published template exists for locale

This path does not use ui_locales or requestId unless you pass equivalent values in context attributes yourself.

Admin configuration

Ensure templates exist for each locale and channel you need:

• Set Default Locale when creating a template group.
• Add or copy locales per group under Language and locale selection.
• Maintain separate template rows per templateKey, locale, and communication method (for example WELCOME_USER + en + email and WELCOME_USER + de + email).

Default Template Types

cidaas provides the following system template types. For the built-in default template group, English (en) and German (de) variants are pre-seeded for the channels listed below.

Template activation defaults

Two settings work together:

Setting	Level	Meaning
deactivatable	Template type	Whether you may turn off this notification in Communication Management. If No, cidaas treats the notification as required for core operations (for example password reset or account verification).
enabled	Template row (per templateKey, locale, and channel)	Whether that specific template is active. Pre-seeded defaults differ by template type.

When a cidaas service triggers a notification, a message is sent only if a matching template exists for the app's template group, locale, and channel, and that template is enabled and published. If the template is disabled or still a draft, no message is sent for that channel—there is no automatic fallback to another template.

For optional notifications (for example welcome or security alerts), you typically enable, customize, and publish the template in the Admin Portal before users receive it. Mandatory flows (for example RESET_PASSWORD, VERIFY_ACCOUNT) ship with templates enabled by default in the default group.

Enabled by default in the table below refers to email templates in the pre-seeded default group. Where the same template type is seeded with multiple channels, those channels follow the same default (disabled optional templates are off for email, SMS, IVR, and push where applicable).

System template catalog

Template Key	Description	Deactivatable	Enabled by default (email)	Communication Methods
AFTER_ACTIVATE_USER	Informs users after their account has been activated	Yes	No	email, sms
AFTER_CHANGE_PASSWORD	Notifies users after their password has been changed	Yes	No	email, sms, ivr
AFTER_RESET_PASSWORD	Informs users after they have successfully reset their password	Yes	No	email, sms
AFTER_DE_ACTIVATE_USER	Informs users after their account has been deactivated	Yes	No	email, sms, ivr, push
INVITE_USER	Invites users to complete the sign-up process	No	Yes	email, sms
NEW_DEVICE	Alerts users when a new device is detected during login or other actions	Yes	No	email, sms, ivr, push
NEW_LOCATION	Alerts users when a new location is detected during login or other actions	Yes	No	email, sms, ivr, push
NEW_NETWORK	Alerts users when a new network is detected during login or other actions	Yes	—	email, sms, ivr, push
NOTIFY_COMMUNICATION_CHANGE	Notifies users when they change their communication medium (phone number or email)	Yes	No	email, sms, ivr, push
OPTIN_REMINDER	Reminds users to opt in to the system	Yes	Yes	email, sms
PASSWORD_RESET_BY_ADMIN	Informs users that their password has been reset by an administrator	Yes	No	email, sms, ivr, push
RESET_PASSWORD	Prompts users to proceed with their requested password reset	No	Yes	email, sms, ivr
UN_REGISTER_USER_ALERT	Sends an alert when a user unregisters	Yes	No	email, sms
USER_CREATED	Notifies relevant parties when a user account has been created	Yes	No	email, sms
USER_CREATED_VERIFY	Requests newly created users to verify their email address	Yes	Yes	email, sms
USER_MERGE_IDENTITY_ALERT	Alerts users when their account has been merged with another account	Yes	No	email, sms, push
USER_MERGE_VERIFY_IDENTITY	Requests users to verify and confirm account merge requests	Yes	Yes	email, sms, push
VERIFY_ACCOUNT	Prompts users to verify their account	No	Yes	email, sms, ivr
VERIFY_COMMUNICATION_CHANGE	Notifies users when they initiate a change of phone number or email	No	Yes	email, sms
VERIFY_USER	Initiates user verification processes	No	Yes	email, sms, ivr, push
WEBHOOK_FAILED	Notifies administrators about failed webhooks	Yes	—	email, sms
WELCOME_USER	Welcomes users after successful sign-up and provides next steps	Yes	No	email, sms

info

Note

• Enabled by default — No: Pre-seeded templates in the default group start disabled for all seeded channels until you enable and publish them in Communication Management.
• Enabled by default — Yes: Required for core cidaas flows; templates are pre-seeded enabled (you must still publish after editing content).
• Enabled by default — —: Template type is available, but no pre-built rows are shipped in the default group; create or copy templates in your template group as needed.

Flow-specific guides (for example Welcome user email) describe when each template is triggered.

How to Create Custom Template Types

You can create custom communication template types tailored to your specific requirements.

Step 1: Create Template Type

1. Log in to the cidaas Admin Dashboard
2. Navigate to Template > Template Types
3. Click Create Custom Types
4. Enter the following information:
   • Template Type: Descriptive name for filtering and search operations
   • Description: Supporting description for the template type
   • Communication Methods: Select applicable communication channels (email, SMS, IVR, push)
   • Custom Attributes: Define allowed and required attributes for your template
5. Click Create

The new template type appears in the custom template section. You can update system and custom templates by clicking on them.

Note

You can add custom fields in the registration field section to support your template attributes.

Step 2: Create and Publish Custom Template

1. Log in to the cidaas Admin Dashboard

2. Navigate to Template > Template

3. Select developer from the group type dropdown filter

4. Click the More option in the filtered list

   

5. Click Create Template

6. Search for your template type and enter required details

   

7. Click the template to edit according to your requirements

8. Click Publish

Additional Configuration Options

Locale Settings: Update the locale for the template group to support multiple languages.

Communication Provider: Configure the communication provider for the template group.

In the Admin Portal, use the Template Keys, Communication Method, and Locale filters to locate specific templates quickly. For integrations and custom UIs, use the Get Template Filters by Group API described below.

Template filters API

The Get Template Filters by Group API returns the distinct filter values that exist for templates in a given template group. It is a lightweight discovery endpoint: use it to populate dropdowns, validate criteria before a send, or build admin tooling without loading every template document.

Endpoint

Method	GET
Path	/notifications-srv/templategroups/{id}/templatefilters
Path parameter	id — template group ID (for example default or developer)
Scope	cidaas:templates_read
Reference	Get Template Filters by Group

Response (data object)

Values are derived from templates stored for the group (aggregation over existing rows). They reflect what is configured, not the full theoretical catalog from template types.

Field	Description
groupId	The template group ID from the path
templateKeys	Distinct templateKey values (for example WELCOME_USER, VERIFY_USER)
communicationMethods	Distinct channels present: email, sms, ivr, push, chat
locales	Distinct locale codes (for example en, de)
processingTypes	Distinct processing types where set: GENERAL, LINK, CODE
usageTypes	Distinct usage types where set (mainly VERIFY_USER): MULTIFACTOR_AUTHENTICATION, PASSWORDLESS_AUTHENTICATION, VERIFICATION_CONFIGURATION

info

Note

• The API does not return enabled, isDraft, or template body content. Use Find Templates Using Filters when you need full template records.
• Templates owned by core are excluded from the aggregation; only tenant/client template rows for the group are considered.
• If the group has no matching templates, the response is HTTP 404 with success: true and data: null.
• The OpenAPI schema may list a numbers array; it is reserved and not populated by the current implementation.

Compared to Find Templates by Filter

	Get Template Filters by Group	Find Templates by Filter
HTTP	GET	POST
Purpose	List allowed filter values for a group	Return matching template documents
Input	Group ID in path	Graph filter in body (templateKey, locale, communicationMethod, …)
Typical use	Build filter UI, pre-validate criteria	Read, export, or update specific templates

Example

Request:

GET /notifications-srv/templategroups/default/templatefilters HTTP/1.1
Host: your-tenant.cidaas.de
Authorization: Bearer <access_token>

Response (excerpt):

{
  "success": true,
  "status": 200,
  "data": {
    "groupId": "default",
    "templateKeys": [
      "WELCOME_USER",
      "VERIFY_USER",
      "RESET_PASSWORD",
      "AFTER_ACTIVATE_USER"
    ],
    "communicationMethods": ["email", "sms", "ivr", "push"],
    "locales": ["en", "de"],
    "processingTypes": ["LINK", "CODE", "GENERAL"],
    "usageTypes": [
      "MULTIFACTOR_AUTHENTICATION",
      "PASSWORDLESS_AUTHENTICATION",
      "VERIFICATION_CONFIGURATION"
    ]
  }
}

After you know which templateKey, locale, and communicationMethod combinations exist, call Find Templates by Filter with those criteria to load subjects, content, and enabled / isDraft flags. See Template activation defaults for which system templates are enabled by default.

How to Create Custom Template Groups

1. Log in to the cidaas Admin Dashboard
2. Navigate to Template > Template
3. Click Create Group Types
4. Enter the following information:
   • Template Group Name: Descriptive name for the group
   • Description: Supporting description for the group
   • Copy from Group: Select the template group to copy from (defaults to default)
   • Language: Choose supported languages for the template group
   • Default Locale: Select the default locale
5. Click Create

Developer Reference

The following APIs enable programmatic management of communication templates:

API	Description	Reference
Manage Template Groups by ID	Get, update, or delete template groups using their ID	View API
Create Template Groups	Create new template groups	View API
Find Template Groups Using Filters	Retrieve template groups using filter criteria	View API
Find Templates Using Filters	Retrieve templates using filter criteria	View API
Manage Templates	Create, update, or delete templates	View API
Manage Templates by ID	Get, update, or delete templates using their ID	View API
Manage Template Types Using Filters	Manage template types in a graph-based structure	View API
Send Template-Based Notifications	Send notifications based on templates	View API
Create Template Types	Create new template types with custom attributes	View API
Get Notification Status	Retrieve service setup and status information for notification vendors	View API
Manage Template Type Attributes	Create or update attributes for a communication template type	View API
Get Template Filters by Group	Distinct templateKey, locale, channel, and processing/usage values for a template group (discovery for UIs and integrations)	View API

::::::warning Support

Need Help?

For any further assistance, feel free to visit our Support Portal.