Use Reserved Variables collected from chatbot conversations – Help Center

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.

In the lists below, we differentiate between two types of variables:

Meta Variables

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

Channel	Variables	Example values	Supported in WHB Requests*	Supported in WHB Response Mapper	Supported in Connections	Supported in Bot Messages
WebChat	{{web.host}}	support.certainly.io	Yes	Yes	Yes	No
WebChat	{{web.hostPageUrl}}	https://support.certainly.io/hc/en-us/articles/360017134659-Conversational-Web-SDK	Yes	Yes	Yes	No
Zendesk	{{zd.current_device_type}}	desktop	Yes	Yes	Yes	No
	{{zd.current_city}}	Copenhagen	Yes	Yes	Yes	No
	{{zd.current_tags}}	null	Yes	Yes	Yes	No
	{{zd.current_ip}}	123.45.67.890	Yes	Yes	Yes	No
	{{zd.page_title}}	Simulate Visitor on Zendesk Chat	Yes	Yes	Yes	No
	{{zd.external_id}}	null	Yes	Yes	Yes	No
	{{zd.current_country}}	Denmark	Yes	Yes	Yes	No
	{{zd.notes}}	null	Yes	Yes	Yes	No
	{{zd.current_user_agent}}	Mozilla/5.0...	Yes	Yes	Yes	No
	{{zd.page_url}}	https://www.zopim.com	Yes	Yes	Yes	No
	{{zd.visitor_id}}	1234567.abcdefghijlmn	Yes	Yes	Yes	No
	{{zd.current_region}}	Copenhagen	Yes	Yes	Yes	No
	{{zd.current_department}}	Bot_Department	Yes	Yes	Yes	No
	{{zd.current_platform}}	Linux	Yes	Yes	Yes	No
	{{zd.visitor_email}}	user@email.com	Yes	Yes	Yes	No
	{{zd.display_name}}	John Doe	Yes	Yes	Yes	No
Facebook	{{fb.first_name}}	John	Yes	Yes	Yes	No
	{{fb.last_name}}	Doe	Yes	Yes	Yes	No
	{{fb.gender}}	male	Yes	Yes	Yes	No
	{{fb.locale}}	en_US	Yes	Yes	Yes	No
	{{fb.profile_pic}}	https://platform-lookaside.fbsbx.com/	Yes	Yes	Yes	No
	{{fb.id}}	2034502059904829	Yes	Yes	Yes	No
Sunshine Conversations	{{ss.metadata}}	JSON Object	Yes	Yes	Yes	No
	{{ss.user.id}}	28a4e32b6cccb6132bf79902	Yes	Yes	Yes	No
	{{ss.appId}}	610c40fe3b505500d3cf8a71	Yes	Yes	Yes	No
	{{ss.userId}}	28a4e32b6cccb6132bf79901	Yes	Yes	Yes	No
	{{ss.avatarUrl}}	https://www.gravatar.com/avatar...	Yes	Yes	Yes	No
	{{ss.displayName}}	John Doe	Yes	Yes	Yes	No
	{{ss.integrationId}}	61116f45bcdb7300d4ead262	Yes	Yes	Yes	No
	{{ss.conversationId}}	0b7f0b63bd166dab2ce17162	Yes	Yes	Yes	No
	{{ss.currentMessageId}}	614b807521f91400d34babf3	Yes	Yes	Yes	No
Webhook	{{wh.status}}	200	Yes	Yes	Yes	No
	{{wh.name}}	Last Executed webhook Name	Yes	Yes	Yes	No
	{{wh.response}}	JSON Object or String	Yes	Yes	Yes	No

*WHB Data refers to all fields in a given Webhook that are above the Response Mapper function.

Conversational Variables

Conversational Variables are variables that are generated on conversation time and provided for all channels.

Variables	Information	Supported in WHB Requests	Supported in WHB Response Mapper	Supported in Connections	Supported in Bot Messages
{{certainly.lastName}}	Only available in the FB channel	Yes	Yes	Yes	No
{{certainly.replyData}}	Validated Response in a Collector Module	Yes	Yes	Yes	No
{{certainly.sessionId}}	Unique ID for the conversation	Yes	Yes	Yes	No
{{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.	Yes	Yes	Yes	No
{{certainly.reply}}	Raw user response	Yes	Yes	Yes	No
{{certainly.extractedData\|tojson}}	JSON with previously validated responses	Yes	Yes	Yes	No
{{certainly.botId}}	Bot UUID	Yes	Yes	Yes	No
{{certainly.botDeploymentId}}	Bot deployment UUID	Yes	Yes	Yes	No
{{certainly.firstName}}	Only available in FB channel	Yes	Yes	Yes	No
{{certainly.customVariables\|tojson}}	Previously generated Custom Variables	Yes	Yes	Yes	No
{{certainly.moduleId}}	Module ID where the WH is triggered	Yes	Yes	Yes	No
{{certainly.to}}	Channel ID	Yes	Yes	No	No
{{certainly.from}}	Bot User External ID	Yes	Yes	Yes	No
{{certainly.botTrainedModelId}}	The UUID string for the AI model key	Yes	Yes	Yes	No
{{certainly.attachedMedia}}	Empty value for now	Yes	Yes	Yes	No

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.

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:

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:

json
{{ variableName or "fallback" }}

json
{{ variableName1 or variableName2 or "fallback" }}

json
{{ 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"].