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:

• Basic variables

• Session variable extraction

• Timestamps

• All channels

• HTTP/formatted variables

• Display list patterns

• Media file sharing (inbound)

• File encoding on HTTP Node (POST)

• Location sharing

• Ads that click to WhatsApp

• Chat 2 Pay auto-generated order number

• WhatsApp Contact Sharing - Contact Receiving

• WhatsApp Commerce Messages

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.

Function	Command	Output Format
Get MSISDN (mobile number)	[[session:msisdn]]	[phone]
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.

Function	Command	Output 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

Function	Command	Output 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

Command	Description	Notes
[[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
[[subset:<value>:<delimiter>:<position1>:<position2>]]	Retrieve a subset of a string returned by an API based on delimiter. Example: [[subset:100 Edward Road, Bo Oakdale, Cape Town, 7530, South Africa:, :1:3]]→ {"Bo Oakdale, Cape Town, 7530"}	position2 is optional. Providing only position1 returns the string at that specific index. Providing position1 and position2 gives you strings within that range inclusive of the strings at position1 and position2 indexes. Both positions allow negative numbers to indicate working backwards from the end of the input value.

Display list patterns

Command	Description
[[APIname:ListName:#item]]

Media file sharing (inbound)

Command	Description
[[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)

Command	Description
[[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": "[phone]",
        "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.

Command	Description
[[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.

Command	Description
[[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

Command	Description
[[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.

Command	Description
[[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:

Command	Description
[[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.