1. Help Center
  2. Other Integrations
  3. Webhooks & Custom Integrations

Use Reserved Variables collected from chatbot conversations

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 Metadata

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
{{nlu}}

Stores detailed information about Intents, entities, and languages recognized:

{'intents': ['name': '1434-Hello', 'confidence': 0.38... }

 

Webhook Execution Metadata

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 Metadata

Channel-specific metadata consists of variables provided by each of the respective channels offered in the Certainly Platform.

Certainly Widget (WebChat) Metadata

Only available when the conversation is taking place on the Certainly Widget.

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 Chat Metadata

Only available when the conversation is taking place via the Zendesk Chat (Legacy) Web Widget.

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 and Zendesk Messaging

Certainly exposes metadata related to the ongoing Sunshine Conversations session via object {{sc}}. This conversation may take place on any of the channels supported by Sunshine Conversations, or Zendesk Messaging.

Variable Example value Description
{{sc.appId}} 5f324eb1acf330000c177713 The Sunshine Conversations appId associated with the ongoing conversation.
{{sc.switchboardId}} 4235dsf4tre55 The Sunshine Conversations switchboardId associated with the ongoing conversation.
{{sc.conversation}}
{
  "sc": {
    "appId": "5f324eb1acf330000c177713",
    "switchboardId": "4235dsf4tre55",
    "conversation": {
      "id": "65733d483f8e3e50a57a42c0",
      "type": "personal",
      "metadata": {
        "isFirstTimeCustomer": true
      },
      "user": {
         ...
      },
      "last_message": {
         ...
      }
    }
  }
}

 

A nested object which features the id of the conversation, metadata about the conversation, the user associated with the ongoing conversation, and the object of the last message  sent by the user.
{{sc.conversation.id}} 65733d483f8e3e50a57a42c0 The conversation id generated by Sunshine Conversations. Refer to the official Sunshine Conversations REST API Documentation for more details.
{{sc.conversation.metadata}}
{
"isFirstTimeCustomer": true
}

 

The custom Sunshine Conversations metadata linked to the ongoing conversation.
{{sc.conversation.user}}
{
  "id": "65733d483f8e3e50a57a42a3",
"externalId": "your-own-id",
  "profile": {
    "email": "updated@email.com",
    "locale": "en",
    "surname": "Name",
    "avatarUrl": "https://pictureurl.com/avatar_icon.png",
    "givenName": "Updated",
    "localeOrigin": "apiRequest"
  },
  "metadata": {
    "justGotUpdated": true
  },
  "identities": [],
  "signedUpAt": "2023-12-08T15:59:04.697Z"
}

 

The Sunshine Conversations object for the user linked to the ongoing conversation, including user-specific metadata.

Refer to the official Sunshine Conversations REST API Documentation for more details.

{{sc.conversation.last_message}}
{
  "id": "43srtw45345345",
  "source": {
    "type": "web",
    "device": {
        "id": "65733d483f8e3e50a57a42a6",
        "guid": "a64488a9fde44ca9ba91dc31660d0527",
        "info": {
          "URL": "sunshine.localhost",
          "vendor": "smooch",
          "referrer": "",
          "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
          "currentUrl": "http://sunshine.localhost/",
          "sdkVersion": "5.5.8",
          "currentTitle": "",
          "browserLanguage": "en"
        },
        "type": "web",
        "status": "active",
        "clientId": "65733d483f8e3e50a57a42a4",
        "lastSeen": "2023-12-08T16:03:26.248Z",
        "integrationId": "5f5a0e538d7d62000c3f4c4c"
    },
    "integrationId": "5f5a0e538d7d62000c3f4c4c"
  }
 }

 

The Sunshine Conversations object for the last message sent by the user in the ongoing conversation, including message-specific metadata.

Refer to the official Sunshine Conversations REST API Documentation for more details.

 

Previously, Sunshine Conversations metadata was accessible via reserved variable {{ss}}. This is set to be deprecated in Q2, 2024. The table below is for reference only, please refer to the {{sc}} object above for your implementations.

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 Metadata

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.

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


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:

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

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.

Jinja2 code used for Reserved Variables and CVars

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