In this article, we describe the variables and values generated with every chat conversation and made available for use in Connections and Webhooks.
Every conversation in the Certainly Platform happens between an end user and a chatbot. Certainly tries to collect some metadata about these two actors (end user and bot) by 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, we'll cover:
- Conversational Variables
- Webhook Variables
- Channel-specific Variables
- Zendesk widget switch extension
- Other reserved variables
- Use cases
- Additional considerations
Conversational Variables
Conversational Variables are generated during conversation time and provided for all channels.
You cannot use them directly in the bot's messages; that is, [[certainly.reply]] will not work. However, you can assign them to another Custom Variable and use that 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's a message from a user to the bot, and "out" if it's a message from the bot to a 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 value | Description |
| {{wh.status}} | 200 | HTTP status. Numbers other than 200 indicate an error. |
| {{wh.name}} | Get Product List | Last executed Webhook's name |
| {{wh.response}} | {"status": "OK",....} | JSON object or string |
Channel-specific Variables
Channel-specific Variables are variables provided by each of the respective channels offered in the Certainly Platform.
Certainly Widget (WebChat) Variables
| 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 Variables
| Variable | Example value | Description |
| {{zd.current_device_type}} | desktop | |
| {{zd.current_city}} | Copenhagen | 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 | 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 Variables
| 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 Variables
| 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.
Explore many other examples of using the Jinja code.
Zendesk widget switch extension
This is mostly used for live chat. The extension allows you easily switch from the Certainly widget to Zendesk widget for live chat.
Learn more about handing conversations to Zendesk Chat by switching widgets.
|
Variable |
Example value |
Description |
|
{{visitor_name}} |
"John Doe" |
Name that will appear as a user name in Zendesk Chat |
|
{{visitor_email}} |
"john@email.com" |
Email address to match the user record in Zendesk |
| {{zendesk}} | "start_chat" | When assigned "start_chat" triggers switchover to the Zendesk widget |
| {{zendesk_department}} | "Support" | Zendesk department name to transfer the chat to |
| {{zendesk_tags}} | "order_status, on-hold" | Comma-separated list of tags that will be assigned to the corresponding Zendesk ticket |
Other reserved variables
| Variable | Example value | Description |
|
{{nlu}} |
{'intents': ['name': '1434-Hello', 'confidence': 0.38... } |
Stores detailed information about Intents, entities, and languages recognized. For bots using the new AI. |
|
{{current_popup}} |
"popup1_name" |
Pop-up ID of the clicked pop-up message |
Use cases
In this section, we'll address the following use cases:
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:
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.
Additional considerations
CVars override Reserved Variables of the same name
If there is a Webhook that generates a Custom Variable (CVar) with the same name as one of the Reserved Variables, it will override the default Reserved Variable. CVars will always take priority over the default conversational metadata elements.