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
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].idOperators
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 &
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
KAMPALAlower(text)
Puts text into small letters. Useful before comparing two values that people typed.
Example
@(lower("KAMPALA"))Gives
kampalatitle(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 Doetrim(text)
Removes spaces from both ends. Worth doing on anything a person typed before you store it or compare it.
Example
@(trim(" Jane "))Gives
Janetrim_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
7text_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
12345split(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, pearjoin(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 linereplace(text, find, replaceWith)
Swaps every occurrence of one piece of text for another.
Example
@(replace("UGX 1,250,000", ",", ""))Gives
UGX 1250000repeat(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
****3456word(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
Doeword_count(text)
How many words. A quick way to tell a one-word answer from a sentence.
Example
@(word_count("Jane Amina Doe"))Gives
3field(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
4821remove_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
0700123456clean(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 removedurl_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%20Coregex_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 falsechar(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
Acode(text)
The character code of the first character. The reverse of char.
Example
@(code("A"))Gives
65text(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 numberNumbers
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
1250round(number, places)
Rounds to the nearest value. Leave places out for a whole number.
Example
@(round(1234.567, 2))Gives
1234.57round_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.4round_down(number, places)
Always rounds towards zero.
Example
@(round_down(12.39, 1))Gives
12.3min(a, b, ...)
The smallest value. Pass the numbers one after another, or pass a single list.
Example
@(min(3, 9, 1))Gives
1max(a, b, ...)
The largest value. Also accepts a single list.
Example
@(max(array(12, 45, 7)))Gives
45mean(a, b, ...)
The average. Values that are not numbers are ignored rather than counted as zero.
Example
@(mean(2, 4, 9))Gives
5sum(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 responsemod(a, b)
The remainder after dividing. Used for things like every third message, or splitting people into groups.
Example
@(mod(7, 2))Gives
1number(value)
Turns text into a number so you can do arithmetic on a reply.
Example
@(number("1200") * 2)Gives
2400percent(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.89rand_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 numberReferences 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-2f7c31d8ab64transaction_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-7QB4ZRDates 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-24now()
The date and the time right now. Use it to stamp a record you are sending out.
Example
@(now())Gives
2026-09-24T14:32:05date(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-24datetime(value)
Reads a date and a time out of text.
Example
@(datetime("2026-09-24 14:30:00"))Gives
2026-09-24T14:30format_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 2026format_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:32datetime_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 2026datetime_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 yearsepoch(value)
The moment as a count of seconds, which is what many APIs want. With nothing passed it is now.
Example
@(epoch())Gives
1790259125datetime_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:32Lists
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 itemscount(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
4contains(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 falsesort(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, 45unique(list)
Drops repeats and keeps the original order.
Example
@(unique(array("EN", "FR", "EN")))Gives
EN, FRconcat(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, Creverse(value)
Turns a list back to front. Given text, it reverses the characters.
Example
@(reverse(array(1, 2, 3)))Gives
3, 2, 1filter(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 themforeach(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 fieldkeys(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 responseextract(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 namesextract_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 droppedforeach_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 minorand(a, b, ...)
True only when everything passed is true.
Example
@(and(context.results.age.value >= 18, context.results.consent.value = "yes"))Gives
true or falseor(a, b, ...)
True when at least one is true.
Example
@(or(context.results.lang.value = "EN", context.results.lang.value = "en"))Gives
true or falsedefault(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 nameboolean(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 falseis_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 failedJSON
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 JSONActing 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].fullNameFrom 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
Everything here runs inside a IBridgeIt flow. To see where these expressions are typed, go back to Flows in the user guide.
