MessageRule

A MessageRule specifies which locale and variant is preferred for a given message, along with the conditions for selecting the rule.

Attributes

role
Optional string; may be sender, recipient, staff, or other. When a role is provided, the rule matches only if the message is intended for a transfer participant with the specified role. When no role is provided, the rule always matches.
locale
Optional string. Specifies the preferred locale when the rule matches.
variant
Optional string; only ASCII letters, numbers, and dashes are allowed, and must not be longer than 50 characters. Specifies the preferred message variant to use when the rule matches.

How to Use MessageRules

WingCash provides a message templating system that allows apps to refine the email and SMS messages sent by WingCash. A set of templates is known as a Message Set and is assigned to a site. Within each message set, WingCash lets template authors create templates customized by locale and variant. (A locale is a short language identifier with optional script and region qualifiers; a variant is a short identifier defined by the template author or app developer.)

WingCash often doesn’t have enough context to know which locale and variant is preferred for a given message, so the API lets apps specify a list of rules for choosing the right locale and variant. When calling APIs that start a transfer, apps can add a parameter called message_rules, which is a list of up to 10 MessageRule JSON objects. WingCash examines the rules in order when choosing the locale and variant for a generated message. It selects the locale or variant from the first matching rule. If no rule matches, WingCash defaults to a locale of en and the default variant (an empty string).

For example, if the person sending money prefers the en locale, while the recipient prefers the pt_BR locale, and both prefer messages based on a variant called fx1, then an appropriate message_rules list would be:

[
    {"role": "sender", "locale": "en", "variant": "fx1"},
    {"role": "recipient", "locale": "pt_BR", "variant": "fx1"}
]

All MessageRule attributes are optional. If no role is specified, the rule always matches. The following rules would have a similar effect as the rules above, with the added benefit of setting the variant for any other transfer participants as well:

[
    {"role": "sender", "locale": "en"},
    {"role": "recipient", "locale": "pt_BR"},
    {"variant": "fx1"}
]

Tip

To find out which template WingCash used to generate an email, look for the X-Message-Template header. The header encodes the message set ID, the template name, the preferred variant name (if any), the channel (always email), and the preferred locale.