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. Codemonkey 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 Codemonkey 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}} /hc/en-us/articles/5397951906708-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 Codemonkey 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:

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

Was this article helpful?

0 out of 0 found this helpful
Have more questions? Submit a request

Comments (0 comments)

Please sign in to leave a comment.