Customizing templates
This page explains how to design your template strategy, prepare customized email and SMS templates, and submit them to Weavr. For background on how brand and locale affect template selection, see the cascading template selection logic.
Designing your template strategy
Before configuring templates, decide how many template variants you need based on your business requirements. The system gives you complete flexibility: you can create a single set of templates for all users, or you can create multiple sets targeting specific combinations of brand and locale.
A template set is a complete collection of all email and SMS templates for a particular combination of brand and locale.
Option 1: single default set
The simplest approach is to provide one set of templates that serves all your users, regardless of their brand or locale settings. This is appropriate if you operate a single brand and your user base primarily uses one language.
| Template set | Brand | Locale | Serves |
|---|---|---|---|
| Default | Any | Any | All users |
With this setup, every user receives the same templates. Any brand or locale values you set on users have no effect on template selection since only one option exists.
Option 2: brand-specific sets with default fallback
If you operate multiple brands but your users predominantly use one language, you can create brand-specific template sets plus a default fallback. This ensures each brand has its own visual identity in communications.
| Template set | Brand | Locale | Serves |
|---|---|---|---|
| BrandA set | BrandA | Any | Users with brand BrandA |
| BrandB set | BrandB | Any | Users with brand BrandB |
| Default | Any | Any | Users without a brand, or with an unrecognized brand |
Option 3: locale-specific sets with default fallback
If you operate a single brand but serve users across multiple languages, you can create locale-specific template sets. This ensures users receive communications in their preferred language.
| Template set | Brand | Locale | Serves |
|---|---|---|---|
| English set | Any | en | English-speaking users |
| French set | Any | fr-FR | French-speaking users |
| German set | Any | de-DE | German-speaking users |
| Default | Any | Any | Users with an unsupported locale |
Users with a matching locale receive templates in their language. Users with locales you haven't specifically catered for (for example, Italian) fall back to the default set.
Option 4: full matrix of brand and locale
For maximum customization, you can create template sets for specific combinations of brand and locale, plus appropriate fallbacks.
| Template set | Brand | Locale | Serves |
|---|---|---|---|
| BrandA French | BrandA | fr-FR | French-speaking BrandA users |
| BrandA English | BrandA | en | English-speaking BrandA users |
| BrandA default | BrandA | Any | BrandA users with unsupported locale |
| BrandB German | BrandB | de-DE | German-speaking BrandB users |
| BrandB English | BrandB | en | English-speaking BrandB users |
| BrandB default | BrandB | Any | BrandB users with unsupported locale |
| Default | Any | Any | Users without a recognized brand |
This configuration provides the most tailored experience but requires maintaining more template sets.
Choosing your strategy
When deciding on your template strategy, consider:
- Number of brands: if you operate multiple distinct brands, users expect communications to reflect the brand they interact with. Brand-specific templates are essential for maintaining brand consistency.
- Language requirements: if your users span multiple languages, locale-specific templates improve user experience significantly. Consider which languages are most important based on your user distribution.
- Maintenance overhead: each template set must be maintained. When you update template content, you need to update all relevant template sets. Balance customization benefits against maintenance costs.
- Fallback coverage: always ensure you have appropriate fallback templates. Users should never fail to receive a message because no template matches their profile.
Email template naming convention
When preparing customized templates to submit to Weavr, follow this naming convention:
{template_name}.mustache.{locale}.{brand}
The locale component in template file names uses underscore format (for example, en_EN, fr_FR) rather than the hyphen format used in the API (for example, en-EN, fr-FR). The brand component is omitted if the template should apply to all brands.
Examples of valid template names:
| Template name | Description |
|---|---|
verify_email.mustache.en_EN.BrandA | English, BrandA |
verify_email.mustache.fr_FR.BrandA | French, BrandA |
verify_email.mustache.fr_FR | French, all brands (no brand specified) |
verify_email.mustache.en_EN | English, all brands (default fallback) |
SMS message customization
SMS messages follow the same cascading logic as email templates. When submitting customized SMS messages, you provide a file specifying the operation type, cardinality (for operations like payments that can be single or multiple), brand, locale, and the message text.
The following variables are available in SMS templates, depending on the message type:
| Variable | Description |
|---|---|
{PIN} | The one-time verification code |
{PROGRAMME_NAME} | Your program's display name |
{PIN_VALIDITY_MINUTES} | How long the PIN remains valid |
{TRANSACTION_CURRENCY} | Currency code for the transaction |
{TRANSACTION_AMOUNT} | Transaction amount |
{TRANSACTION_BENEFICIARY_NAME} | Name of the payment beneficiaryBeneficiary A trusted recipient for payments that includes both information about the business or individual as well as their bank account or instrument details. When using trusted beneficiaries, customers may be allowed to skip Strong Customer Authentication (SCA) when executing Outgoing Wire Transfer or Send transactions, reducing the number of approval steps required. |
{COUNT} | Number of transactions (for bulk operationsBulk Operations The capability of grouping multiple individual API-based actions into a batch. Bulk operations allow you to execute hundreds or thousands of operations by making only one or two API calls, increasing throughput, accomplishing actions in a secure session, and reducing complexity in your application.) |
{TRANSACTION_CURRENCY_AMOUNT_AGGREGATE} | Total amount across multiple transactions |
{DISTINCT_BENEFICIARIES_COUNT} | Number of unique beneficiaries |
Practical examples
The following scenarios illustrate how template selection works in practice.
Example 1: MultiMulti Weavr Multi is an embedded finance solution that allows you to integrate financial services into your own application, providing a seamless experience for your customers. It enables you to offer managed accounts, managed cards, and transactions without requiring financial expertise.-brand deployment
You operate two brands, "BrandA" and "BrandB." Your French users on BrandB should receive French communications, while all other users receive English.
Template configuration:
| Template name | Serves |
|---|---|
verify_email.mustache.en_EN.BrandA | English-speaking BrandA users |
verify_email.mustache.fr_FR.BrandB | French-speaking BrandB users |
verify_email.mustache.en_EN | Fallback for any user without a brand-specific match |
Scenario A: A user is created with locale: "fr-FR" and brand: "BrandB". The system finds an exact match and sends verify_email.mustache.fr_FR.BrandB.
Scenario B: A user is created with locale: "de-DE" and brand: "BrandA". There's no German BrandA template. The system cascades:
- Priority 1 (exact locale + exact brand): no
de_DE.BrandAtemplate exists. - Priority 2 (any locale + exact brand): found
en_EN.BrandA.
The user receives the English BrandA template, preserving the correct brand experience.
Scenario C: A user is created with locale: "es-ES" and brand: "BrandC" (a brand you haven't set up templates for). The system cascades:
- Priority 1: no
es_ES.BrandCtemplate. - Priority 2: no templates for BrandC brand.
- Priority 3: no
es_ESlocale-only template. - Priority 4: falls back to
verify_email.mustache.en_EN(your default).
Example 2: MultiMulti Weavr Multi is an embedded finance solution that allows you to integrate financial services into your own application, providing a seamless experience for your customers. It enables you to offer managed accounts, managed cards, and transactions without requiring financial expertise.-language without brands
If you don't use brands and simply want to support multiple languages, you only need to set the locale field for your users.
Template configuration:
| Template name | Language |
|---|---|
forgot_password.mustache.en_EN | English |
forgot_password.mustache.fr_FR | French |
forgot_password.mustache.sv_SE | Swedish |
Scenario A: A user with locale: "sv-SE" triggers a password reset. The system matches on forgot_password.mustache.sv_SE and sends the Swedish version.
Scenario B: A user with locale: "it-IT" (Italian, which you haven't set up) triggers a password reset. The system finds no Italian template, so it falls back to your default template (likely English).
Example 3: Gradual rollout
You might want to introduce branding and localization gradually without affecting existing users. Since both locale and brand are optional, existing users without these values continue to receive your current default templates unchanged.
New users can be created with locale and brand values, and they receive the new customized templates. You can then gradually update existing users' records as needed, perhaps through a bulk update process coordinated with your Weavr account representative.
Example 4: Comprehensive multiMulti Weavr Multi is an embedded finance solution that allows you to integrate financial services into your own application, providing a seamless experience for your customers. It enables you to offer managed accounts, managed cards, and transactions without requiring financial expertise.-brand, multiMulti Weavr Multi is an embedded finance solution that allows you to integrate financial services into your own application, providing a seamless experience for your customers. It enables you to offer managed accounts, managed cards, and transactions without requiring financial expertise.-locale setup
This example demonstrates a more complete setup where you operate two brands across three languages.
Template configuration:
| Template name | Brand | Locale | Purpose |
|---|---|---|---|
verify_email.mustache.en_EN.BrandA | BrandA | English | BrandA English users |
verify_email.mustache.fr_FR.BrandA | BrandA | French | BrandA French users |
verify_email.mustache.de_DE.BrandA | BrandA | German | BrandA German users |
verify_email.mustache.en_EN.BrandB | BrandB | English | BrandB English users |
verify_email.mustache.fr_FR.BrandB | BrandB | French | BrandB French users |
verify_email.mustache.en_EN | Any | English | Default for unbranded English users |
verify_email.mustache.fr_FR | Any | French | Default for unbranded French users |
Cascade behavior for different users:
| User brand | User locale | Template selected | Reason |
|---|---|---|---|
| BrandA | fr-FR | fr_FR.BrandA | Exact match |
| BrandA | it-IT | en_EN.BrandA | Brand match, locale fallback |
| BrandB | fr-FR | fr_FR.BrandB | Exact match |
| BrandB | de-DE | en_EN.BrandB | Brand match, no German BrandB template |
| BrandC | fr-FR | fr_FR | No BrandC templates, locale match |
| None | fr-FR | fr_FR | No brand, locale match |
| None | es-ES | en_EN | No brand, no Spanish template, default fallback |
Submitting templates
To submit your customized templates, contact your Weavr account representative. You'll need to provide:
- The complete set of email template files following the naming convention
- SMS message specifications including operation type, cardinality, brand, locale, and message text