Copy page

Basics

Template Variables Reference

Template Variables

Template variables enable dynamic content in your USSD applications. Use double curly braces {{...}} to insert values from session data, API responses, configuration, and secrets.

Variable Scopes

Scope	Syntax	Description
Session	{{session.*}}	Current session data and user input
Response	{{response.*}}	Data from the most recent API call
Environment	{{env.*}}	Application environment variables
Options	{{options.*}}	Application configuration options
Secrets	{{secrets.*}}	Tenant-scoped secrets (requires secrets engine)
Organization	{{org.*}}	Current tenant/organization info
Application	{{app.*}}	Application metadata

Session Variables

Session variables contain data about the current USSD session and user interactions.

Built-in Session Variables

Variable	Description	Example
{{session.msisdn}}	User's phone number	+231886123456
{{session.id}}	Unique session identifier	sess_abc123xyz
{{session.shortcode}}	USSD shortcode dialed	*123#
{{session.input}}	User's most recent input	1
{{session.networkid}}	Mobile network identifier	orange-lr
{{session.provider}}	Network provider name	Orange

Custom Session Data

Actions can store data in the session using target or response_map:

Code
# Store API response data
action "GetBalance" {
  type = "http_call"
  url  = "/api/balance/{{session.msisdn}}"
  
  response_map = {
    balance = "$.accountBalance"
    currency = "$.currency"
  }
  
  on_success = "ShowBalance"
}

# Access stored data
menu "ShowBalance" {
  text = "Your balance: {{session.data.currency}} {{session.data.balance}}"
}

Nested Data Access

Access nested objects using dot notation:

Code
# If response stored: { "user": { "profile": { "name": "John" } } }
text = "Welcome, {{session.data.user.profile.name}}!"

Response Variables

Response variables provide access to the most recent API call's response body.

Code
action "FetchUser" {
  type   = "http_call"
  url    = "/api/users/{{session.msisdn}}"
  target = "user_data"
  
  on_success = "DisplayUser"
}

menu "DisplayUser" {
  # Access via response scope (immediate)
  text = "Name: {{response.name}}\nEmail: {{response.email}}"
}

JSONPath Response Mapping

Map specific response fields to session variables:

Code
action "GetAccount" {
  type = "http_call"
  url  = "/api/accounts"
  
  response_map = {
    account_id = "$.data.id"
    balance    = "$.data.balance"
    status     = "$.data.status"
  }
}

Environment Variables

Define application-specific configuration in the env block:

Code
app "MyApp" {
  shortcode = "*123#"
  version   = "1.0.0"
  start     = "Main"

  env = {
    API_TIMEOUT    = "30"
    MAX_RETRIES    = "3"
    SUPPORT_NUMBER = "+231886000000"
    DEBUG_MODE     = "false"
  }
}

menu "Support" {
  text = "Call us at {{env.SUPPORT_NUMBER}} for help."
}

Referencing Secrets in Environment

Combine with secrets for secure configuration:

Code
env = {
  API_KEY = "{{secrets.production_api_key}}"
  DB_PASS = "{{secrets.database_password}}"
}

Options Variables

Access global application options:

Code
app "MyApp" {
  options {
    http_base_url = "https://api.example.com/v2"
  }
}

# Reference in actions
action "LogRequest" {
  type = "set"
  target = "api_base"
  value = "{{options.http_base_url}}"
}

Variable	Description
{{options.http_base_url}}	Global HTTP base URL

Secrets Variables

Access tenant-scoped secrets securely. Requires a configured secrets engine.

Code
app "SecureApp" {
  shortcode = "*123#"
  version   = "1.0.0"
  start     = "Main"

  options {
    secrets_engine = {
      provider = "tenant_vault"
      path     = "tenants/{{org.id}}/apps/{{app.name}}"
    }
  }

  auth {
    type          = "oauth2_client_credentials"
    token_url     = "https://auth.example.com/oauth/token"
    client_id     = "{{secrets.oauth_client_id}}"
    client_secret = "{{secrets.oauth_client_secret}}"
  }
}

Organization Variables

Access information about the current tenant:

Variable	Description	Example
{{org.id}}	Tenant/organization ID	org_abc123

Application Variables

Access metadata about the current application:

Variable	Description	Example
{{app.name}}	Application name	MyBankingApp
{{app.version}}	Application version	1.0.0
{{app.shortcode}}	Application shortcode	*123#

Template Syntax

Basic Substitution

Code
text = "Hello, {{session.msisdn}}!"
# Output: Hello, +231886123456!

Nested Object Access

Code
text = "Account: {{session.data.account.number}}"
# Output: Account: 1234567890

In URLs and Headers

Code
action "GetProfile" {
  type    = "http_call"
  url     = "/users/{{session.msisdn}}/profile"
  headers = {
    "X-Request-ID" = "{{session.id}}"
    "X-Org-ID"     = "{{org.id}}"
  }
}

In Request Bodies

Code
action "CreateTransaction" {
  type = "http_call"
  url  = "/transactions"
  body = {
    "from"   = "{{session.msisdn}}"
    "to"     = "{{session.data.recipient}}"
    "amount" = "{{session.data.amount}}"
  }
}

Variable Resolution Order

When a variable name doesn't include a scope prefix, it's resolved in this order:

1. session.data.* (custom session data)
2. session.* (built-in session variables)
3. response.* (most recent API response)

Code
# These are equivalent:
text = "Amount: {{amount}}"
text = "Amount: {{session.data.amount}}"

Default Values

Currently, templates do not support inline default values. Use conditional actions or the env action with fallback for defaults:

Code
# Use env action with fallback
{
  type     = "env"
  key      = "CURRENCY"
  fallback = "USD"
  target   = "currency"
}

Best Practices

1. Use explicit scopes - Prefer {{session.data.amount}} over {{amount}} for clarity.

2. Validate before using - Ensure variables exist before referencing them in critical paths.

3. Secure sensitive data - Always use {{secrets.*}} for credentials, never {{env.*}} with hardcoded values.

4. Document custom variables - Comment your DSL to indicate where custom session variables are set.

Code
# balance is set by GetBalance action
menu "ShowBalance" {
  text = "Your balance: {{session.data.balance}}"
}

5. Handle missing data gracefully - Use error_target in action chains to catch API failures.