> ## Documentation Index
> Fetch the complete documentation index at: https://docs.varmo.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# UI suggestions for cardholder messaging

> Use Varmo's ui_suggestion field to display locale-aware delivery messages and prompt cardholders to act at the right moment in their delivery journey.

The `ui_suggestion` object is a pre-built, localized messaging hint that Varmo generates alongside every delivery status response. It is designed so you can render cardholder-facing copy directly from the API without writing message logic yourself. Each suggestion is matched to the current delivery status, the predicted window, and the destination locale — giving cardholders accurate, appropriately worded information at every stage of the journey.

## Fields at a glance

```json theme={null}
"ui_suggestion": {
  "locale": "en-US",
  "recommended_message": "Your card is likely arriving in the next 1-2 days.",
  "recommended_action": "None"
}
```

| Field                 | Type   | Description                                                                                                                                                     |
| --------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `locale`              | string | A BCP 47 locale tag inferred from the destination country code (e.g. `en-US`, `fi-FI`). Use this for language routing in your UI even if you write custom copy. |
| `recommended_message` | string | A human-readable string you can display to the cardholder verbatim. Phrasing reflects the current status and confidence level.                                  |
| `recommended_action`  | string | An enum indicating what action, if any, the issuer should prompt the cardholder to take. Common values: `None`, `Activate`, `ContactSupport`.                   |

## Displaying the message

The following example shows how to render `recommended_message` in a React component. The component also uses `locale` to set the `lang` attribute for correct browser rendering.

```javascript theme={null}
function CardDeliveryBanner({ uiSuggestion }) {
  const { locale, recommended_message, recommended_action } = uiSuggestion;

  return (
    <div lang={locale} className="delivery-banner">
      <p>{recommended_message}</p>
      {recommended_action === "Activate" && (
        <button onClick={() => redirectToActivation()}>
          Activate your card
        </button>
      )}
      {recommended_action === "ContactSupport" && (
        <button onClick={() => openSupportChat()}>
          Contact support
        </button>
      )}
    </div>
  );
}
```

## Customizing messaging

`recommended_message` is a safe default that works for most issuers without any additional configuration. If you need to match a specific brand voice or write copy in a tone that differs from Varmo's defaults, build your message from the structured `prediction` fields instead — `delivery_window.min`, `delivery_window.max`, and `confidence_level` give you everything you need to construct accurate, bespoke copy.

Even when you write custom messages, retain `locale` for language routing. Varmo derives the locale from the destination `country_code`, so it reliably reflects the cardholder's expected language — handling this yourself from raw country codes is error-prone, especially for multilingual countries.

## Recommended actions

The `recommended_action` field tells you what, if anything, to ask the cardholder to do. Map each value to a corresponding UI state in your app.

| Value            | Trigger condition                                      | What to do                                                             |
| ---------------- | ------------------------------------------------------ | ---------------------------------------------------------------------- |
| `None`           | Card is in transit or no action is needed yet.         | Display `recommended_message` without any call to action.              |
| `Activate`       | Card has likely been delivered based on Varmo's model. | Prompt the cardholder to activate their card via your activation flow. |
| `ContactSupport` | A delivery exception has been detected.                | Prompt the cardholder to contact your support team for assistance.     |