# Variables (/docs/products/ussd-flows/developers/variables)

Write `$(scope.key)` in a label or another supported field, and Monime fills in the value when the page is shown:

```json
{
  "type": "display",
  "label": "Thanks $(page.enter_name.value). We sent SLE $(page.enter_amount.value) to Fatmata Kamara."
}
```

`$(...)` can also hold an expression, such as a comparison or a function call. See [Expressions](/docs/products/ussd-flows/developers/expressions).

## Scopes

| Scope             | Syntax                                 | Holds                                                       |
| ----------------- | -------------------------------------- | ----------------------------------------------------------- |
| Page              | `$(page.ID.value)`, `$(page.ID.label)` | The subscriber's answer on an earlier page                  |
| Session           | `$(session.KEY)`                       | Details of the current USSD session                         |
| Data              | `$(data.KEY)`                          | Data your server sent with this page                        |
| Session context   | `$(sc.KEY)`                            | A value you saved earlier in this session                   |
| Recurring context | `$(rc.KEY)`                            | A value you saved for this subscriber in an earlier session |

Every value arrives as text, including numbers and `true` or `false`.

## Page

`$(page.ID.value)` is what the subscriber entered or chose on the page with that ID. For a menu, it is the chosen item's `value`.

`$(page.ID.label)` is the page's label. For a menu, it is the chosen item's `label`.

```json
{
  "id": "select_district",
  "component": {
    "type": "menu",
    "label": "Select your district",
    "items": [
      { "label": "Bo", "value": "bo" },
      { "label": "Kenema", "value": "kenema" }
    ]
  }
}
```

If the subscriber picks Kenema, `$(page.select_district.value)` is `kenema` and `$(page.select_district.label)` is `Kenema`.

A page's answer only exists once the subscriber has been through that page. Pages passed over by `next_page` or `options.skip` have no answer. See [Missing Values](#missing-values).

## Session

| Key                     | Value                                           | Example          |
| ----------------------- | ----------------------------------------------- | ---------------- |
| `id`                    | The session's ID                                |                  |
| `network_name`          | The mobile network                              | `"Africell"`     |
| `network_provider_name` | The network's mobile money service              | `"Afrimoney"`    |
| `subscriber_msisdn`     | The subscriber's phone number                   | `"+23276123456"` |
| `subscriber_id`         | Same value as `subscriber_msisdn` inside a flow | `"+23276123456"` |

Your exchange endpoint receives a hashed subscriber ID and a masked phone number instead. If you save the subscriber's number or send it in `dataExport`, it is masked unless it came from a [`get_subscriber_msisdn`](/docs/products/ussd-flows/developers/templates/get-subscriber-msisdn) page. See [Subscriber Identification](/docs/products/ussd-flows/developers/exchange-api/subscriber-identification).

## Data

`data` holds what your server sent in `pageData` when it chose this page through an exchange or a dynamic page. Some templates also set data; each template's page lists what it sets.

```json
{
  "id": "show_balance",
  "component": {
    "type": "display",
    "label": "Your balance is $(data.currency) $(data.balance)."
  }
}
```

If your server replied with `"pageData": { "currency": "SLE", "balance": "1250" }`, the subscriber sees `Your balance is SLE 1250.`

Data belongs to the page your server sent the subscriber to. Later pages can't read it. To keep a value, save it with a mutation on that page:

```json
{
  "on_done": {
    "action": "next",
    "session_context": { "mutations": { "balance": "$(data.balance)" } }
  }
}
```

A menu can take its whole list of items from data: `"items": "$(data.accounts)"`, where `accounts` is a list of `{ "label": "…", "value": "…" }`.

## Session Context and Recurring Context

`$(sc.KEY)` reads a value saved with `on_done.session_context.mutations` earlier in the same session. `$(rc.KEY)` reads a value saved with `on_done.recurring_context.mutations`, in this session or an earlier one.

```json
{
  "id": "welcome_back",
  "component": {
    "type": "display",
    "label": "Welcome back, $(rc.display_name)."
  }
}
```

How long each store keeps values, and its limits, are in [Context Stores](/docs/products/ussd-flows/developers/context-stores).

## Missing Values

| Reference                                                                        | In a label                   | Inside an expression         |
| -------------------------------------------------------------------------------- | ---------------------------- | ---------------------------- |
| `rc.KEY` or `sc.KEY` that was never saved, or was cleared                        | Empty text                   | `null`                       |
| `page.ID.value` or `page.ID.label` for a page the subscriber hasn't been through | The flow stops with an error | Empty text                   |
| `data.KEY` that your server didn't send for this page                            | The flow stops with an error | The flow stops with an error |
| `session.KEY` that doesn't exist                                                 | The flow stops with an error | The flow stops with an error |

When a label refers to a page ID that doesn't exist, or to an unknown session key, the error shows up as soon as a session starts, before the first page.

Give unset context values a default with `??`: `$(rc.display_name ?? 'friend')`. A `??` default does not apply to empty text, so it doesn't help with a page the subscriber skipped.

## Where $(...) Works

| Field                                                                      | What you can write                                                                |
| -------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `label` on any page                                                        | Text mixed with any number of `$(...)`                                            |
| `options.terminal_message`                                                 | Text mixed with any number of `$(...)`                                            |
| Menu item `label` and `value`                                              | Text mixed with any number of `$(...)`                                            |
| Menu item `hide`                                                           | `true`, `false`, or one `$(...)`. The item is hidden when it gives `true`.        |
| Menu `items`                                                               | One `$(data.KEY)` that holds the whole list                                       |
| `options.skip`, `options.terminal`                                         | `true`, `false`, or one `$(...)`. Takes effect when it gives `true`.              |
| `on_done.next_page`                                                        | A page ID, or one `$(...)` that gives a page ID                                   |
| `on_done.session_context.mutations`, `on_done.recurring_context.mutations` | A plain value, or a `$(...)`. The result is saved.                                |
| `on_done.dataExport`                                                       | A plain value, or a `$(...)`. The result is sent as text.                         |
| `collect_payment` `amount` and `multiplier`                                | A number, or one plain reference to `page`, `data`, `rc` or `sc`. No expressions. |
| `collect_payment` `reference`, `receipt_name` and `metadata` values        | Text mixed with any number of `$(...)`                                            |
| `on_done.url`, dynamic page `url`                                          | Not supported. Use a fixed URL.                                                   |

For other template fields, see each [template's page](/docs/products/ussd-flows/developers/templates/overview). The `collect_payment` label also takes the `{{amount}}` placeholder; see [collect\_payment](/docs/products/ussd-flows/developers/templates/collect-payment).

## Editor Autocomplete

In the flow editor, type `$(` to get suggestions: the scopes, then your page IDs, session keys, and the `sc` and `rc` keys your mutations save. New pages and keys show up as soon as you add them.