Programming reference

The expression language

There is a small programming language inside every flow. It has values, operators, about seventy functions, and inline functions of your own. This page lists all of it, with an example you can paste and the value it gives back.

What this is

A flow on its own can send, wait, branch, and call an API. The expression language is what lets it compute. It is how a list that came back from your core system becomes a numbered menu, how the number a customer typed picks a row out of that list, and how the payload for the next call is assembled from three different steps.

It is deliberately small. There are no variables you declare, no loops you write by hand, and no way to reach anything outside the run you are in. Everything is an expression that reads from the run and produces a value. That is enough to talk to almost any API, and it is little enough that a flow cannot lock up or run away.

Writing an expression

There are three shapes, and they all start with an at sign.

  • A reference on its own. Hello @context.contact.name in a message becomes Hello and the person's name.
  • A function call in brackets. @(upper(context.contact.name)) is the reliable form, and the one to use whenever the expression is more than a single path.
  • A short field reference in braces. @{customer_number} reads a custom field on the contact, or a spreadsheet column on a broadcast. When both exist, the spreadsheet row wins.

Inside brackets the leading at sign on a path is optional, so @(upper(context.contact.name)) and @(upper(@context.contact.name)) do the same thing. Text inside an expression goes in quotes, single or double. Write two at signs when you want a real at sign in the text, as in an email address.

Escapes inside quoted text

Backslash n is a line break, backslash t is a tab, and backslash r is a carriage return. A line break is what you want as the separator when you join a list into a menu.

Where you can use them

Anywhere a flow takes a piece of text from you, it runs that text through the expression language first. That is a longer list than most people expect.

  • The body of a message, the caption on a file, and the values you fill into a WhatsApp template.
  • The value you write onto a contact field, a URN you add, and the name or language you set.
  • A webhook URL, every query parameter, every header value, the bearer token, the basic auth username and password, the API key value, and the request body.
  • A broadcast message, including one personalised per row of a spreadsheet.
  • The value you save under a result name, and anything you pass into a flow you are calling.

Because the URL and the headers are evaluated too, the same flow can talk to a different endpoint per customer, sign each call with a token it just fetched, and put a value the customer typed into the path rather than the body. Very little is out of reach.

Reading the run

Write @context, a dot, then where to look. These are the roots you can start from.

  • contact. The person in this run: name, first_name, language, status, urn, urns, and fields.anything for a custom field.
  • results. Anything a wait or a webhook saved, under the result name you chose. results.age.value is the reply, results.age.category is the rule it matched.
  • webhook. The most recent call, whether or not you named it: webhook.status, webhook.body, webhook.success.
  • run. This run: run.uuid, run.status, run.flow.name, run.flow.uuid.
  • parent. The flow that called this one, and parent.parent for the one above that.
  • child. The flow this one called, once it has finished, plus child.status.
  • node.uuid. The step running right now.

Walk into a response with dots. Read an item out of a list with a number in square brackets, counting from 0. A field name with a space or a leading digit goes in quotes inside the brackets. The number in the brackets can itself be an expression, which is how a menu choice picks a row.

@context.results.lookup.value.body.accounts[0].balance
@context.results.lookup.value.body["account name"]
@context.results.lookup.value.body.accounts[@context.results.choice.value - 1].id

Operators

The ampersand joins text. It is the one you will use most, because building a line of a menu is mostly gluing pieces together.

@(context.contact.first_name & ", your balance is " & context.results.lookup.value.body.balance)
  • & joins two values as text, whatever they were.
  • + adds numbers, and joins text when either side is not a number. - * / work on numbers, and ^ raises to a power.
  • = != > >= < <= compare. Numbers compare as numbers. Text compares as text and ignores case, so YES and yes are equal.

Mind the difference between + and &

With two numbers, + adds. If you want 1 and 2 to become the text 12 rather than 3, use the ampersand. In the menu example below, index + 1 is deliberate arithmetic, and everything after it is joined with an ampersand.

Small inline functions

Three functions take a small function of your own: foreach, filter, and foreach_value. You write it as a name, an arrow, and an expression. The name is yours to choose and only exists inside that one expression.

(item) -> item.fullName
(item, index) -> index + 1 & ". " & item.fullName
  • The first name is the item. With foreach_value on an object it is the value of each field.
  • The second name is optional. With a list it is the position, counting from 0. With foreach_value it is the field name.
  • The expression can use everything else in the run, so you can mix an item with a contact field or an earlier result.
  • You cannot use a reserved word as your name: context, contact, run, input, webhook, results, node, fields, urns, parent, child, and the usual programming keywords are all refused.
  • A list is walked up to 500 items, and the expression itself is capped in length. Both are guard rails, not targets.

When something is missing

A path that does not exist gives an empty value, not a crash. A flow keeps running rather than stopping in front of the customer. That is usually what you want, but it does mean a silent blank is the symptom of a typo, so check the path in the simulator when a message comes out short.

Use default to fill a gap, and is_error to notice a step that actually failed rather than one that simply had nothing to say.

Hello @(default(context.contact.name, "there"))
@(if(is_error(context.results.lookup.value), "Please try again later", context.results.lookup.value.body.balance))

Text

Everything that reshapes a piece of text: what a customer typed, a field on the contact, or a value that came back from your own system.

upper(text)

Puts text into capitals. Handy for codes and references that your back office expects in one case.

Example

@(upper("kampala"))

Gives

KAMPALA

lower(text)

Puts text into small letters. Useful before comparing two values that people typed.

Example

@(lower("KAMPALA"))

Gives

kampala

title(text)

Capitalises the first letter of each word and lowers the rest, so a name typed in a hurry still reads properly in a message.

Example

@(title("jane amina doe"))

Gives

Jane Amina Doe

trim(text)

Removes spaces from both ends. Worth doing on anything a person typed before you store it or compare it.

Example

@(trim("   Jane   "))

Gives

Jane

trim_left(text)

Removes spaces from the start only.

Example

@(trim_left("   Jane   "))

Gives

"Jane   " (the trailing spaces stay)

trim_right(text)

Removes spaces from the end only.

Example

@(trim_right("   Jane   "))

Gives

"   Jane" (the leading spaces stay)

text_length(text)

How many characters. Use it to check a reference or an account number is the right size before you call your system.

Example

@(text_length("Kampala"))

Gives

7

text_slice(text, start, end)

Cuts out a piece. Counting starts at 0, and end is not included. A negative number counts back from the end, and end can be left out to run to the finish.

Example

@(text_slice("+256700123456", 0, 4))
@(text_slice("ORD-12345", -5))

Gives

+256
12345

split(text, separator)

Breaks text into a list wherever the separator appears. The partner of join.

Example

@(split("mango,apple,pear", ","))

Gives

a list of three items: mango, apple, pear

join(list, separator)

Glues a list back into one piece of text with the separator between items. This is the function that turns a list from your API into a menu the customer can read.

Example

@(join(array("Savings", "Current", "Loan"), "\n"))

Gives

the three words, one per line

replace(text, find, replaceWith)

Swaps every occurrence of one piece of text for another.

Example

@(replace("UGX 1,250,000", ",", ""))

Gives

UGX 1250000

repeat(text, times)

Repeats a piece of text. Most often used to mask a value before you show it back.

Example

@(repeat("*", 4) & text_slice(context.results.account.value, -4))

Gives

****3456

word(text, index)

Pulls out one word, counting from 0. A negative number counts from the end, so -1 is the last word.

Example

@(word("Jane Amina Doe", 1))
@(word("Jane Amina Doe", -1))

Gives

Amina
Doe

word_count(text)

How many words. A quick way to tell a one-word answer from a sentence.

Example

@(word_count("Jane Amina Doe"))

Gives

3

field(text, index, separator)

Like word, but you choose what the pieces are separated by. Leave the separator out and it splits on spaces.

Example

@(field("ORD/2026/4821", 2, "/"))

Gives

4821

remove_first_word(text)

Drops the first word and gives you the rest. This is how you read the argument out of a keyword message: the keyword goes, what follows stays.

Example

@(remove_first_word("BAL 0700123456"))

Gives

0700123456

clean(text)

Strips out characters that are not ordinary printable text, then trims the ends. Worth running over anything pasted from a spreadsheet or copied out of another system.

Example

@(clean(context.results.full_name.value))

Gives

the same name with hidden and control characters removed

url_encode(text)

Makes text safe to drop into a web address. Always use it around a value you are putting into a query parameter.

Example

@(url_encode("Jane Doe & Co"))

Gives

Jane%20Doe%20%26%20Co

regex_match(text, pattern)

True when the pattern is found anywhere in the text. For when the built-in reply rules are not specific enough.

Example

@(regex_match(context.results.ref.value, "^UG-[0-9]{4}$"))

Gives

true or false

char(number)

Gives the character for a character code. char(10) is a line break, which is another way to space out a menu.

Example

@(char(65))

Gives

A

code(text)

The character code of the first character. The reverse of char.

Example

@(code("A"))

Gives

65

text(value)

Forces any value to text. Use it when a number has to go into JSON as a string, for example an account number with a leading zero.

Example

@(text(4821))

Gives

"4821" as text rather than a number

Numbers

Arithmetic on values you collected or received. Numbers that come back whole are shown without a decimal point, so 12.0 reads as 12.

abs(number)

The value without its sign.

Example

@(abs(-1250))

Gives

1250

round(number, places)

Rounds to the nearest value. Leave places out for a whole number.

Example

@(round(1234.567, 2))

Gives

1234.57

round_up(number, places)

Always rounds away from zero. This is the one to use for a fee or a charge you never want to under-state.

Example

@(round_up(12.31, 1))

Gives

12.4

round_down(number, places)

Always rounds towards zero.

Example

@(round_down(12.39, 1))

Gives

12.3

min(a, b, ...)

The smallest value. Pass the numbers one after another, or pass a single list.

Example

@(min(3, 9, 1))

Gives

1

max(a, b, ...)

The largest value. Also accepts a single list.

Example

@(max(array(12, 45, 7)))

Gives

45

mean(a, b, ...)

The average. Values that are not numbers are ignored rather than counted as zero.

Example

@(mean(2, 4, 9))

Gives

5

sum(a, b, ...)

Adds everything up. The usual way to total a list of amounts that came back from your system.

Example

@(sum(extract(context.results.lookup.value.body.accounts, "balance")))

Gives

the total of every balance in the response

mod(a, b)

The remainder after dividing. Used for things like every third message, or splitting people into groups.

Example

@(mod(7, 2))

Gives

1

number(value)

Turns text into a number so you can do arithmetic on a reply.

Example

@(number("1200") * 2)

Gives

2400

percent(value, total)

A percentage, rounded to a whole number and written with the sign. With one argument it treats the value as a fraction.

Example

@(percent(45, 60))
@(percent(0.25))

Gives

75%
25%

format_number(value, places, thousands, decimal)

Formats a number for a customer to read. Places defaults to 2, the thousands mark to a comma, and the decimal mark to a full stop.

Example

@(format_number(1234567.891, 2))

Gives

1,234,567.89

rand_between(low, high)

A random whole number in the range, both ends included.

Example

@(rand_between(1000, 9999))

Gives

4821, or any other four-digit number

References and identifiers

Values you need to be unique. Both generate a new value every time they run, so read them once into a result if you need the same value twice.

uuid()

A fresh random identifier. Send it as an idempotency key on a webhook so a retry is not treated as a second request.

Example

@(uuid())

Gives

9f1c7b2a-4d55-4a1e-9b0e-2f7c31d8ab64

transaction_ref(prefix)

A short reference a customer can read out on the phone. The prefix is put into capitals and anything that is not a letter or a digit is dropped. Leave it out and the reference starts with TX.

Example

@(transaction_ref("PAY"))

Gives

PAY-M8F2K1-7QB4ZR

Dates and time

Units for adding and for measuring a gap are Y for years, M for months, D for days, H for hours, MI for minutes, and S for seconds. Dates typed by a person are read as ISO, dd/MM/yyyy, MM/dd/yyyy, dd-MM-yyyy, or yyyy/MM/dd.

today()

Today's date with no time on it.

Example

@(today())

Gives

2026-09-24

now()

The date and the time right now. Use it to stamp a record you are sending out.

Example

@(now())

Gives

2026-09-24T14:32:05

date(value)

Reads a date out of text so you can work with it. With nothing passed it is the same as today().

Example

@(date("24/09/2026"))

Gives

2026-09-24

datetime(value)

Reads a date and a time out of text.

Example

@(datetime("2026-09-24 14:30:00"))

Gives

2026-09-24T14:30

format_date(value, pattern)

Writes a date the way a customer reads it. Without a pattern you get yyyy-MM-dd.

Example

@(format_date(today(), "dd MMM yyyy"))

Gives

24 Sep 2026

format_datetime(value, pattern)

The same for a date and a time. Without a pattern you get yyyy-MM-dd HH:mm:ss.

Example

@(format_datetime(now(), "HH:mm"))

Gives

14:32

datetime_add(value, amount, unit)

Moves a date forward, or backward with a negative amount. This is how you work out a due date or an expiry.

Example

@(format_date(datetime_add(now(), 7, "D"), "dd MMM yyyy"))

Gives

01 Oct 2026

datetime_diff(from, to, unit)

The gap between two moments, counted in the unit you name. The classic use is turning a date of birth into an age.

Example

@(datetime_diff(context.results.dob.value, today(), "Y"))

Gives

the age in whole years

epoch(value)

The moment as a count of seconds, which is what many APIs want. With nothing passed it is now.

Example

@(epoch())

Gives

1790259125

datetime_from_epoch(seconds)

Turns a count of seconds from an API back into a date and time you can format.

Example

@(format_datetime(datetime_from_epoch(1790259125), "dd MMM yyyy HH:mm"))

Gives

24 Sep 2026 14:32

Lists

A response from your own system is usually a list, and these are the functions that turn it into something a customer can read or something another API will accept. foreach and filter stop at 500 items, which is plenty for a menu and not enough to be a data export.

array(a, b, ...)

Builds a list out of the values you pass.

Example

@(array("Savings", "Current", "Loan"))

Gives

a list of three items

count(value)

How many items in a list, or how many fields on an object. Anything else counts as 1.

Example

@(count(context.results.lookup.value.body.students))

Gives

4

contains(collection, item)

True when a list holds the item, a piece of text holds the text, or an object has that field name.

Example

@(contains(context.results.lookup.value.body.roles, "ADMIN"))

Gives

true or false

sort(list)

Sorts a list. Numbers sort as numbers, anything else sorts as text and ignores case.

Example

@(sort(array(12, 3, 45)))

Gives

3, 12, 45

unique(list)

Drops repeats and keeps the original order.

Example

@(unique(array("EN", "FR", "EN")))

Gives

EN, FR

concat(a, b, ...)

Joins lists into one list. A plain value is added as a single item.

Example

@(concat(array("A", "B"), array("C")))

Gives

A, B, C

reverse(value)

Turns a list back to front. Given text, it reverses the characters.

Example

@(reverse(array(1, 2, 3)))

Gives

3, 2, 1

filter(list, (item, index) -> test)

Keeps only the items where the test is true. Run it before foreach so you only build a menu out of the rows that matter.

Example

@(filter(context.results.lookup.value.body.accounts, (a) -> a.balance > 0))

Gives

only the accounts that have money in them

foreach(list, (item, index) -> value)

Builds a new list by running the same small expression over every item. index counts from 0 and can be left out. This is the workhorse of menu building.

Example

@(foreach(context.results.lookup.value.body.students, (s, i) -> i + 1 & ". " & s.fullName))

Gives

a list like "1. Jane Doe", "2. Amina Okello"

Objects

An object is a set of named fields: what a JSON response is made of, and what an API you are calling expects back.

object(key, value, key, value, ...)

Builds an object from pairs. Keys go in quotes, and values can be anything, including another object or a list.

Example

@(object("name", context.contact.name, "age", context.results.age.value))

Gives

an object with a name field and an age field

keys(object)

The field names on an object, as a list. Useful when the API returns a map keyed by something you do not know in advance.

Example

@(keys(context.results.lookup.value.body))

Gives

a list of the field names in the response

extract(list, field)

Pulls one field out of every object in a list, giving you a plain list of those values.

Example

@(extract(context.results.lookup.value.body.students, "fullName"))

Gives

a list of just the names

extract_object(list, field, field, ...)

Keeps only the fields you name on every object in a list. The quickest way to cut a large response down before you pass it on to another system.

Example

@(extract_object(context.results.lookup.value.body.accounts, "id", "balance"))

Gives

the same rows with every other field dropped

foreach_value(object, (value, key) -> value)

Walks an object rather than a list. The first name is each value, and the second, if you give one, is the field name.

Example

@(foreach_value(context.results.lookup.value.body.totals, (v, k) -> k & ": " & v))

Gives

a list like "airtime: 12000", "data: 4500"

Choices and checks

Anything empty, zero, the word false, an empty list, or a missing value counts as false. Everything else counts as true.

if(test, whenTrue, whenFalse)

Picks one of two values. Leave the last one out and a false test gives nothing at all.

Example

@(if(context.results.age.value >= 18, "adult", "minor"))

Gives

adult or minor

and(a, b, ...)

True only when everything passed is true.

Example

@(and(context.results.age.value >= 18, context.results.consent.value = "yes"))

Gives

true or false

or(a, b, ...)

True when at least one is true.

Example

@(or(context.results.lang.value = "EN", context.results.lang.value = "en"))

Gives

true or false

default(value, fallback)

Uses the fallback when the first value is missing or empty. This is how you keep a message readable when a field was never filled in.

Example

@(default(context.contact.name, "there"))

Gives

the contact name, or there when they have no name

boolean(value)

Turns anything into true or false using the rule above.

Example

@(boolean(context.results.optin.value))

Gives

true unless the reply was empty, 0, or false

is_error(value)

True when a step left an error behind instead of a value. Check it after a webhook so you can say something sensible rather than show the customer a broken message.

Example

@(if(is_error(context.results.lookup.value), "We could not reach the system, please try again later", context.results.lookup.value.body.balance))

Gives

the balance, or the apology when the call failed

JSON

How you build a request body properly, and how you read one back. Never paste a JSON document and drop a value into a string: a name with a quote mark in it breaks the whole payload.

json(value)

Turns a value into JSON text. Quotes, line breaks, and anything else awkward inside a value are escaped for you.

Example

@(json(object("name", context.contact.name, "at", now())))

Gives

{"name":"Jane Doe","at":"2026-09-24T14:32:05"}

parse_json(text)

The reverse. Reads JSON out of a piece of text so you can walk into its fields, which is what you need when an earlier step left you a JSON string rather than an object.

Example

@(extract(parse_json(context.results.note.value), "balance"))

Gives

the balance field out of the stored JSON

A menu from an API

This is the example that shows what the language is for. A webhook named parent_lookup has returned a list of students. You have no idea in advance how many there are or what they are called, and you need a numbered list the parent can reply to.

@(join(foreach(@context.results.parent_lookup.value.body.students,
  (item, index) -> index + 1 & "). " & item.fullName & " " & item.className & " - " & item.school.name),
  "\n"))

Read it from the inside out.

  1. 1@context.results.parent_lookup.value.body.students is the list from the response. parent_lookup is the result name you gave the webhook step, value.body is the parsed response, students is the array inside it.
  2. 2foreach walks that list. For each student it is handed the student as item and the position as index.
  3. 3index + 1 turns the position into a number a person counts from, so the first row is 1 and not 0. Everything after it is glued on with ampersands: the bracket and the full stop, the name, the class, then a dash and the school.
  4. 4foreach hands back a list of finished lines.
  5. 5join sticks those lines together with a line break between them, and you are left with one piece of text ready to send.

What the customer sees:

1). Jane Doe P5 - Kampala Primary School
2). Amina Okello P3 - Kampala Primary School
3). Peter Mwangi S2 - Nakawa Secondary School

Nothing about that is fixed to three students. Add a fourth in your system and the menu grows. The flow does not change.

Trim the list before you number it

Wrap the list in filter when some rows should not be offered, and the numbering still comes out right, because foreach counts what it is actually given rather than the original list.
@(join(foreach(filter(@context.results.parent_lookup.value.body.students, (s) -> s.active),
  (item, index) -> index + 1 & "). " & item.fullName),
  "\n"))

Acting on the choice

Send that menu with a Send a message step, then a Wait for a response step saving as choice with a rule for has a number. The reply is a position in the list, so subtract one and read the row straight out of the response you already have. There is no second call to your system.

@context.results.parent_lookup.value.body.students[@context.results.choice.value - 1].fullName

From there you can confirm the pick, store the student id on the contact, or send it on to the next API.

You picked @(context.results.parent_lookup.value.body.students[context.results.choice.value - 1].fullName). Is that right?

A payload for another API

The same response, now on its way out to a second system. object builds the shape and json turns it into text, so a name with an apostrophe in it cannot break the request.

@(json(object(
  "reference", transaction_ref("FEE"),
  "idempotency_key", uuid(),
  "parent", object(
    "phone", context.contact.urn,
    "name", context.contact.name
  ),
  "student", context.results.parent_lookup.value.body.students[context.results.choice.value - 1],
  "amount", number(context.results.amount.value),
  "submitted_at", format_datetime(now(), "yyyy-MM-dd'T'HH:mm:ss")
)))

The URL, the headers, and the query parameters of that same call are expressions too, so the endpoint and the credentials can come from the run as easily as the body does.

https://api.example.com/schools/@(context.results.parent_lookup.value.body.schoolId)/invoices?msisdn=@(url_encode(context.contact.urn))

Across nested flows

A flow that builds a menu is worth writing once and calling from everywhere. Put the lookup and the menu in a child flow, and the parent passes context down while the child passes answers back up.

  • From inside the child, read what the caller already knows: @context.parent.results.parent_lookup.value.body.students. The child does not have to call the API again.
  • From inside the child, know who called it: @context.parent.flow.name and @context.parent.run.uuid.
  • Further up the chain: @context.parent.parent.results.anything, as deep as the nesting goes.
  • Back in the parent, after the child finishes: @context.child.results.choice.value and @context.child.status.

So the menu builder above works unchanged inside a child flow. Only the root changes.

@(join(foreach(@context.parent.results.parent_lookup.value.body.students,
  (item, index) -> index + 1 & "). " & item.fullName),
  "\n"))

And the parent assembles its payload from what the child collected, mixed with what it collected itself.

@(json(object(
  "student_id", context.child.results.student_id.value,
  "term", context.results.term.value,
  "paid_by", context.contact.urn
)))

Results never leak sideways

A child does not inherit the parent's results into its own. It reads them through parent, and the parent reads the child through child. The two sets of answers stay separate, which is exactly why the same child flow behaves the same whoever calls it.

Everything here runs inside a IBridgeIt flow. To see where these expressions are typed, go back to Flows in the user guide.