Use Reserved Variables collected from chatbot conversations

This article describes the list of variables and values that are generated with every chat conversation and made available for use in Connections and Webhooks.

Every conversation in the platform happens between an end user and a chatbot. Certainly tries to collect some metadata about these two actors (end user and bot) adding variables in a list that also has other conversational details. These variables are very helpful when used for driving the conversation to a different path based on the values returned.

Below, are detailed descriptions of different types of variables:

Conversational Variables

Conversational Variables are variables that are generated during conversation time and provided for all channels. You can not use them directly in the bot's messages ([[certainly.reply]] will not work), but you can assign them to the other Custom Variable and then use it in the bot's messages.

Variable

Description

{{certainly.lastName}}

Only available in the FB channel

{{certainly.replyData}}

Validated Response in a Collector Module

{{certainly.sessionId}}

Unique ID for the conversation

{{certainly.direction}}

Always "in" for now; "in" if it is a message from the end user to the bot, and "out" if it is a message from the bot to the end user.

{{certainly.reply}}

Raw user response

{{certainly.extractedData|tojson}}

JSON with previously validated responses

{{certainly.botId}}

Bot UUID

{{certainly.botDeploymentId}}

Bot deployment UUID

{{certainly.firstName}}

Only available in FB channel

{{certainly.customVariables|tojson}}

Previously generated Custom Variables

{{certainly.moduleId}}

Module ID where the WH is triggered

{{certainly.to}}

Channel ID

{{certainly.from}}

Bot User External ID

{{certainly.botTrainedModelId}}

The UUID string for the AI model key

{{certainly.attachedMedia}}

Empty value for now

Webhook variables

Webhook variables are available in the bot right after the execution of any webhook.

Variable

Example values

Description

{{wh.status}}

200

HTTP status. Numbers other than 200 mean that there was some error

{{wh.name}}

Get Product List

Last Executed webhook's name

{{wh.response}}

{"status": "OK",....}

JSON object or string

Channel Variables

Channel Variables are variables provided by each of the respective channels offered in the Certainly Platform.

Certainly Widget (WebChat)

Variable

Example value

Description

{{web.host}}

certainly.io

The domain part of the website address where the widget was run from 

{{web.hostPageUrl}}

https://certainly.io/about

Full address, including page name of the website where the widget was run from

Zendesk channel

Variable

Example value

Description

{{zd.current_device_type}}

desktop

 

{{zd.current_city}}

Copenhagen

A user's city

{{zd.current_tags}}

null

 

{{zd.current_ip}}

123.45.67.89

 

{{zd.page_title}}

Simulate Visitor on Zendesk Chat

 

{{zd.external_id}}

null

 

{{zd.current_country}}

Denmark

A user's country

{{zd.notes}}

null

 

{{zd.current_user_agent}}

Mozilla/5.0...

Browser's id

{{zd.page_url}}

https://www.zopim.com

 

{{zd.visitor_id}}

1234567.abcdefghijlmn

 

{{zd.current_region}}

Copenhagen

 

{{zd.current_department}}

Bot_Department

 

{{zd.current_platform}}

Linux

 

{{zd.visitor_email}}

user@email.com

 

{{zd.display_name}}

John Doe

 

Sunshine Conversations channel

Variable

Example value

Description

{{ss.metadata}}

JSON Object

 

{{ss.user.id}}

28a4e32b6cccb6132bf79902

 

{{ss.appId}}

610c40fe3b505500d3cf8a71

 

{{ss.userId}}

28a4e32b6cccb6132bf79901

 

{{ss.avatarUrl}}

https://www.gravatar.com/avatar...

 

{{ss.displayName}}

John Doe

 

{{ss.integrationId}}

61116f45bcdb7300d4ead262

 

{{ss.conversationId}}

0b7f0b63bd166dab2ce17162

 

{{ss.currentMessageId}}

614b807521f91400d34babf3

 

Facebook channel

Variable

Example value

Description

{{fb.first_name}}

John

FB user's first name

{{fb.last_name}}

Doe

FB user's last name

{{fb.gender}}

male

FB user's gender

{{fb.locale}}

en_US

FB user's language preference

{{fb.profile_pic}}

https://platform-lookaside.fbsbx.com/

FB user's photo

{{fb.id}}

2034502059904829

FB user's ID

The best way to benefit from including these values in your Webhooks is to use Jinja2 templating code. We intend to support Jinja2 in all areas of the Certainly Platform, so you might find it useful to get a headstart on using this powerful resource in your Webhooks. 

You can find many useful examples of the Jinja code in the article Using Jinja2

Use Case 1: Search filtering params (in URL)

If you want your bot to be able to retrieve a certain product list based on search criteria passed in a product_query variable, you can easily include the end user response in the query params of your Webhook URL, as displayed in the image below:

mceclip0.png
If you save this configuration as part of Webhook X, then you can use it later in a flow like the following:
Bot: "What product or products are you interested in?"

End User: "red shoes"
Webhook X executed: https://.... &product_query=red%20shoes
Custom Variables may be created based on the third-party response to Webhook X.

Bot: "These are the products we have based on your criteria..."
 

Use Case 2: Form submission

If your bot needs to fetch information from the end user instead of a form submission, the POST body of that form submission may have some empty values for which you may define some fallback values. In cases such as these, we advise you to refer to the syntax used below. 

Fallbacks

In scenarios where you need to insert a fallback value, you have several options available:

{{ variableName or "fallback" }}

or

{{ variableName1 or variableName2 or "fallback" }}

or

{{ variableName |default('fallback') }}

Jinja2 is exceptionally flexible, so please refer to the Jinja2 documentation if you want to explore the different kinds of possibilities it offers.

Things to keep in mind

If there is a Webhook that generates a Custom Variable with the same name as one of the reserved variables, it will override the default reserved variable. Custom Variables will always have priority over the default conversational metadata elements.

It is important to mention that the Jinja2 code will be the one used for both reserved variables and the CVARs, meaning that {{certainly.reply}} will render as the user reply to the module where the Webhook is used, and {{ticketID}} will render as the value of [customVariable key="ticketID"].