Environment Variables

Environment variables are a way to configure your application for different instances.

For example, imagine you have built one USSD application for churches. The flow is the same for every church, but each church has a different API endpoint. Instead of hardcoding the API endpoint on every step, you can create an environment variable called api.

Then in your hook URL, you can use:

@api/check-balance

If the value of api is https://church-a.example.com, USSDK will call:

https://church-a.example.com/check-balance

This allows you to build the application once and configure each instance differently.

Creating variables

To create environment variables:

1. Open your app in the editor.
2. Make sure no step is selected.
3. In the Step tab, go to Env variables.
4. Add a name and a default value.

Variable names should be simple. Use names like api, base-url, church_name, or school-api.

The default value is used while building and testing the app. When you create an instance, you can override the value for that instance.

Using variables in hooks

Environment variables are used in hook URLs with the format:

@variable-name/path

For example, if you create a variable named base-url with the value:

https://api.example.com

You can set a step's hook to:

@base-url/customer/profile

When the session runs, USSDK resolves the hook URL before calling your API:

https://api.example.com/customer/profile

This is especially useful when the same app is deployed for different clients, branches, schools, churches, events, or environments.

Instance overrides

When creating an instance, USSDK shows the environment variables defined on the app. You can then override some or all of them for that instance.

Let's say your app has this variable:

You can create two instances with different values:

Both instances will use the same USSD flow. The only difference is the value that replaces @api when a hook is called.

What happens if a variable is not overridden?

If an instance does not provide a value for a variable, USSDK uses the default value from the app.

This means you don't have to override every variable for every instance. Only change the values that are different.

Where variables work

Environment variables currently work in hook URLs. They are not the same as handlebars values in messages or menus.

Use environment variables for hook endpoints:

@api/account-balance

Use handlebars for values returned from hooks:

Your balance is GHS{{balance}}

Use {{key:name}} for values collected from previous steps:

Hello {{key:name}}

Each one solves a different problem.

Summary

In summary:

1. Create environment variables from the editor when no step is selected.
2. Use them in hook URLs with the format @variable-name/path.
3. Set default values while building the app.
4. Override values when creating or updating an instance.

Environment variables help you keep one USSD application reusable across many deployments.