Using system variables

In this section, we cover ways to use variables within your workflows. These variables can be sourced from the session, HTTP calls, or from user input.

Find information about the following:

For more information about referring to these variables in your workflow, see here.

Basic Variables

When requesting input from your users or asking them to select from a list of options presented to them, you can store these inputs for the duration of the session. Each of these inputs can be used, modified, or remapped within a flow, or passed to an external system.

Command: [[variablename]]

Use cases:

  1. Using a Request Input node to request information from a customer.

  2. Using a Multiple Choice Input node for the customer to select from a list of options.

In the case of a multiple-choice menu, to display the actual value of the variable the customer has selected, use the following command: [[variablename:value]].

Session variable extraction

In a session, Chat Flow stores certain parameters that can be extracted/used in flows or HTTP calls. These are called session variables. Examples of the available session variables are shown in the tables below.

FunctionCommandOutput Format

Get MSISDN (mobile number)

[[session:msisdn]]

+27123456789

Get IMSI (USSD only)

[[session:imsi]]

  • Mobile Country Code (MCC). The first 2 or 3 digits of the IMSI identifies which country the user operates in.

  • Mobile Network code (MNC). The next 1 to 3 digits identifies which MNO the user is associated with (essentially someone’s SIM provider)

  • Mobile Subscription Identification Number. The last 9 or 10 digits of the IMSI is a unique combination of digits to identify the SIM card user.

Get session parameter (USSD only)

[[session:param:1]]

Get parameters entered as part of the USSD string (e.g. *123*01*123456789#)

Convert given string to lower case

[[lower:<value>]]

[[lower:ABCD]] → abcd

Convert given string to upper case

[[upper:<value>]]

[[upper:xyz]] → XYZ

To get n number of left most characters of a string

[[left:<number-of-chars>:<value>]]

[[left:4:ABCDEFGH]] → ABCD

To get n number of right most characters of a string

[[right:<number-of-chars>:<value>]]

[[right:3:tvwxyz]] → xyz

Substring of a given string

[[substr:<start-index>:<end-index>:<value>]]

[[substr:2:6:abcdABCD]] → cdAB

Null check

[[isnull:<value>]]

[[isnull:tvwxyz]] → false

[[isnull:null]] → true

Equals evaluation

[[equals:<var1>:<var2>]]

[[equals:55:66]]→ false

[[equals:hi:hi]] → true

Hash value

[[hash:algorithm:inputEncoding:outputEncoding:<inputValue>]]

[[hash:md5:base64:hex:aGVsbG8gd29ybGQ=]]→ 5eb63bbbe01eeed093cb22bb8f5acdc3

Create a JSON map

[[mapOf:<key1>:<value1>:<key2>:<value2>]]

[[mapOf:name:Max:age:22]]→ {"name": "Max", "age": "22"}

Decoding a JWT token

[jwt:decode:<token>:<claim>]]

[jwt:decode:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c:name]]→ "John Doe"s

Send Template node (variables produced)

[[session: <name>]]

Additional data set on the button's postback data.

Timestamps

Note that the [[system:date]] command returns a GMT timestamp. GMT+2 is not supported.

FunctionCommandOutput Format

Get timestamp

[[system:date|<Date_Format>]]

Example:

[[system:date|ddMMyyyyhhmmss]] → 12012017133422

Get timestamp and timezone

[[system:date|<Date_Format>|<Time_Zone>]]

[[system:date|ddMMyyyyhhmmss|Africa/Lagos]] → 12012017133422

Current time in milliseconds

[[system:currentTimeMillis]]

[[system:currentTimeMillis]] → 1532773619342

All Channels

FunctionCommandOutput Format

Get network

[[session:network]]

Note: For WhatsApp, if this command is used it will do an MNP lookup and store it in Redis. Need to make use of MNP-lookup service.

Get source ID

[[session:source:id]]

Alphanumeric value

Get session ID

[[session:id]]

Alphanumeric value

Get channel Name

[[session:channel:name]]

USSD, WhatsApp, SMS

Get channel ID

[[session:channel:id]]

Alphanumeric value

Get route ID

[[session:channel:routeId]]

The route that was used to start the session - configured in the routing section

Get first message (SMS)

[[start:message]]

Allows you to extract the first message sent by a user in a session. This is retrieved as text.

Get WhatsApp profile name

[[session:channelProfileName]]

Allows you to extract your user's WhatsApp profile name as saved on their WhatsApp account.

HTTP/formatted variables

CommandDescription

[[stepName:result]]

Utilizing this variable allows you to reference information retrieved from a prior HTTP call in your flow to display back to the customer

Display list patterns

CommandDescription

[[APIname:ListName:#item]]

Media file sharing (inbound)

CommandDescription

[[StepName:reference]]

This variable allows you to pass the file received from your customers into a subsequent HTTP call to pass the files to your system storage/database.

File Encoding on HTTP Node (POST)

CommandDescription

[[fileEncoding:<ENCODING>:<REFERENCE>]]

  • ENCODING can be:

    • plain

    • hex

    • base64

    • base64url

  • The "reference" is the incoming media files' reference

If you want to do the base64 encoding of the incoming media file and then want to pass the encoded content of the file in the HTTP POST, it can be achieved by using the following command on the HTTP node body:

Command: [[fileEncoding:base64:<REFERENCE>]]

Example:

{
    "actionName": "Clickatell_Integration_Create",
    "integrationName": "Clickatell_Integration",
    "payload": {
        "cellnumber": "+27761234567",
        "name": "JohnDoe",
        "storenumber": "ERE3434",
        "pop": "[[fileEncoding:base64:[[file_reference]]]]"
    },
    "sourceId": "Clickatell"
}

Location Sharing

The following commands can be used in a workflow to extract certain information relating to a location shared by your customers.

CommandDescription

[[StepName:locationAddress]]

This provides the address location of your customer for the shared location. The address can be extracted and used in a subsequent API call into your services. E.g, you can retrieve: 123 Example Road, Sample City, 1234.

[[StepName:locationName]]

If this location has a designated name, that will be available for extraction.

[[StepName:locationLatitude]]

This provides the latitude coordinates of the shared location.

[[StepName:locationLongitude]]

This provides the longitude coordinates of the shared location.

Ads That Click To WhatsApp

The following commands can be used in a workflow to extract certain information relating to ads that click to WhatsApp used by your customers.

CommandDescription

[[session:whatsapp:referralInfo:sourceUrl]]

The Meta URL that leads to the ad or post clicked by the customer (i.e., the source URL of the ad/post on Facebook).

[[session:whatsapp:referralInfo:sourceId]]

The Meta ID for the ad or post that was clicked by the customer.

[[session:whatsapp:referralInfo:sourceType]]

The source type will be either an ad or a post.

[[session:whatsapp:referralInfo:headline]]

The headline of the ad/post that was clicked by the customer.

[[session:whatsapp:referralInfo:content]]

The content of the ad/post that was clicked by the customer.

Chat 2 Pay Auto-Generated Order Number

CommandDescription

[[NODE_NAME:ordernumber]]

Use this to refer to the order number that the system automatically generates on the Chat 2 Pay node (if selected to be auto-generated).

WhatsApp Contact Sharing - Contact Receiving node

Command: [[<CONTACT>:<contact>:<field type>|:<number>|:<attribute>]]

  • CONTACT is the variable name inside the node itself.

  • Contact is the node type and is always contact in plain text.

  • Field type is the type of field you are sourcing (eg. name).

  • Number denotes the field when there is more than one of the same kind of variable (address (1) and address (2)).

  • An attribute is the value of the field itself.

CommandDescription

[[ContactReceiveNode1:contact:name:firstName]]

The first name

[[ContactReceiveNode1:contact:name:lastName]]

The last name

[[ContactReceiveNode1:contact:name:formattedName]]

The formatted name (or nickname)

[[ContactReceiveNode1:contact:birthday]]

The birthday in DD-MM-YYYY

[[ContactReceiveNode1:contact:org:company]]

The name of the company

[[ContactReceiveNode1:contact:org:title]]

The title this individual has in the company

[[ContactReceiveNode1:contact:org:department]]

The department that this individual is affiliated with

[[ContactReceiveNode1:contact:emails:size]]

This would give us the total number of emails associated with this individual

[[ContactReceiveNode1:contact:emails:1:email]]

The first email value itself

[[ContactReceiveNode1:contact:emails:1:type]]

The first type of email or description of an email type associated with this individual

[[ContactReceiveNode1:contact:emails:2:email]]

The second email value itself

[[ContactReceiveNode1:contact:emails:2:type]]

The second type of email or description of an email type associated with this individual

[[ContactReceiveNode1:contact:urls:size]]

This is the total number of URLs received

[[ContactReceiveNode1:contact:urls:1:url]]

The first URL associated with this individual

[[ContactReceiveNode1:contact:urls:1:type]]

The first URL type

[[ContactReceiveNode1:contact:urls:2:url]]

The second URL associated with this individual

[[ContactReceiveNode1:contact:urls:2:url]]

The second URL type

[[ContactReceiveNode1:contact:addresses:size]]

The total number of emails associated with this individual

[[ContactReceiveNode1:contact:addresses:1:type]]

The first address type associated with this individual

[[ContactReceiveNode1:contact:addresses:1:street]]

The first street name associated with this individual

[[ContactReceiveNode1:contact:addresses:1:zip]]

The first street zip code associated with this individual

[[ContactReceiveNode1:contact:addresses:1:city]]

The first city name associated with this individual

[[ContactReceiveNode1:contact:addresses:1:country]]

The first country name associated with this individual

[[ContactReceiveNode1:contact:addresses:1:state]]

The first state associated with this individual

[[ContactReceiveNode1:contact:addresses:2:street]]

The second street name associated with this individual

[[ContactReceiveNode1:contact:addresses:2:zip]]

The second street zip code associated with this individual

[[ContactReceiveNode1:contact:addresses:2:city]]

The second city name associated with this individual

[[ContactReceiveNode1:contact:addresses:2:country]]

The second country name associated with this individual

[[ContactReceiveNode1:contact:addresses:2:state]]

The second state associated with this individual

[[ContactReceiveNode1:contact:phones:size]]

The total number of phones associated with this individual

[[ContactReceiveNode1:contact:phones:1:phone]]

The first phone number of the associated individual

[[ContactReceiveNode1:contact:phones:1:type]]

The first phone number type of the associated individual

[[ContactReceiveNode1:contact:phones:2:phone]]

The second phone number of the associated individual

[[ContactReceiveNode1:contact:phones:2:type]]

The second phone number type of the associated individual

WhatsApp Commerce Messages

Once an order has been placed, Chat Flow processes the checkout event and stores the appropriate variables as follows:

CommandDescription

[[whatsapp:checkout:total]]

This refers to the order total.

(All checkout event details below)

[[whatsapp:checkout:checkoutType]]

This refers to the checkout type.

[[whatsapp:checkout:text]]

This refers to the text message sent along with the order.

[[whatsapp:checkout:catalogId]]

This refers to the catalogue ID.

[[whatsapp:checkout:selectedItems:#:productId]]

This refers to the SKU or product ID.

[[whatsapp:checkout:selectedItems:#:quantity]]

This refers to the number of items.

[[whatsapp:checkout:selectedItems:#:itemPrice]]

This refers to the price of the item.

[[whatsapp:checkout:selectedItems:#:currency]]

This refers to the price currency.