User communications overview
We send emails and SMS messages to your end-users throughout their lifecycle—from identity verification to transaction alerts. You can customize these communications based on brand and locale dimensions, delivering a tailored experience whether you operate multiple brands or support multiple languages.
This section covers how to configure, customize, and manage the communications your users receive.
Key concepts
Locale
Locale determines the language of communications sent to your users. We use the BCP 47 standard for locale codes, such as en-GB for British English, fr-FR for French (France), or de-DE for German.
The locale value is optional when creating or updating users. If not specified, the user receives communications from your default templates.
Brand
Brand represents an arbitrary grouping that you define for branding purposes. This is useful when you operate multiple distinct brands within your program. For example, you might have a premium brand and a standard brand, or regional brands for different markets.
Brand values can be up to 25 characters with no spaces and are also optional.
Cascading template selection logic
When we send an email or SMS to a user, the system evaluates the user's locale and brand values to select the most appropriate template. This selection follows a cascading priority system that ensures users always receive a message, even if a perfect match isn't available.
How the cascade works
The system attempts to find the most specific template match first, then falls back to progressively more general templates.
When a user has both locale and brand defined:
| Priority | Locale match | Brand match | Description |
|---|---|---|---|
| 1 | Exact | Exact | Template matches both the user's locale and brand |
| 2 | Any | Exact | Template matches the user's brand (any locale) |
| 3 | Exact | Any | Template matches the user's locale (any brand) |
| 4 | Any | Any | Your program's default template |
| 5 | — | — | our global default template |
Brand takes precedence over locale in the fallback order. This design choice reflects the reality that users can generally understand an English message (the default language), but they would find it jarring to receive communications styled for a brand they don't recognize.
When a user has locale but no brand:
| Priority | Locale match | Description |
|---|---|---|
| 1 | Exact | Template matches the user's locale |
| 2 | Any | Your program's default template |
| 3 | — | our global default template |
When a user has brand but no locale:
| Priority | Brand match | Description |
|---|---|---|
| 1 | Exact | Template matches the user's brand |
| 2 | Any | Your program's default template |
| 3 | — | our global default template |
When a user has neither locale nor brand defined, the system uses your program's default template, falling back to our global default if you haven't provided custom templates.
Locale fallback behavior
The system also implements intelligent locale fallback. If you've set a user's locale to en-GB but you've only provided templates for en, the system first searches for an exact match on en-GB, and if none is found, falls back to en.
This allows you to provide a single English template (en) that serves all English-speaking users regardless of their specific regional locale.
Next steps
- Set up brand and locale on your users via the Weavr API
- Customize templates to match your brand and language requirements
- Review the communication reference to see what emails and SMS messages your users receive