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 |
{{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 | |
{{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:

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" }}
or
json
{{ variableName1 or variableName2 or "fallback" }}
or
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.
Comments
0 comments
Please sign in to leave a comment.