Webhooks & Custom Integrations
      Back to home
      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

       

      Multi-language translation

      When the bot is configured to translate all its and users messages, the user_language Custom variable controls what language to translate the bot message to and from what language to translate the user message. Read more about Multi-language translation in this article.

      Variable Example value Description
      {{user_language}} da Two letters language code like da, es, fr, etc.

       

      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 from which the widget was run 
      {{web.hostPageUrl}} https://certainly.io/about Full address, including the page name of the website where the widget was run from

      Zendesk Chat (Legacy) 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 metadata is sent as part of the Sunshine webhook event. Note that the amount of information depends on the event type, type of widget (web, ios, Android), etc. F.e. "conversation:message" event contains message ID, but "conversation:create" and "switchboard:passControl" events do not have it as they happen without the user sending a message.

      For more information, refer to the Sunshine documentation

      In the table below, we list the most useful variables

      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.brandId}} "360003001111" Zendesk's brand ID. Useful to route (bot-to-bot transfer) the conversation to the correct bot in a multibrand environment
      {{sc.conversation.id}} 65733d483f8e3e50a57a42c0 The conversation ID was generated by Sunshine Conversations. 
      {{sc.conversation.metadata}} 
      {
        "isFirstTimeCustomer": true
      }
      		 The custom Sunshine Conversations metadata linked to the ongoing conversation.
      {{sc.conversation.user.displayName}} 
      "Web User 680f4f6d6b73a4d81fe346e1"

      Display Name of a user
      {{sc.conversation.last_message.id}} "680f4f716b73a4d81fe34f52"

      Sunshine's message ID. 
      Capture the ID of the first user's message and pass it when handing over to an agent to have a full chat transcript

      Here is an example of the content of the sc variable sent together with user's message ("conversation:message" event) :

      {
      "appId": "63ee01a83f8aa501194aaaaa",
      "conversation": {
          "id": "680f4f6d6b73a4d81fe3470d",
          "type": "personal",
          "user": {
              "id": "680f4f6d6b73a4d81fe346e1",
              "profile": {
                  "locale": "en-US",
                  "localeOrigin": "apiRequest"
              },
              "signedUpAt": "2025-04-28T09:50:37.198Z",
              "displayName": "Web User 680f4f6d6b73a4d81fe346e1",
              "authenticated": false
          },
          "brandId": "360003001111",
          "last_message": {
              "id": "680f4f716b73a4d81fe34f52",
              "source": {
                  "type": "web",
                  "device": {
                      "id": "680f4f6d6b73a4d81fe3aaaa",
                      "guid": "8e837dfb118c434a9e1120bdca3e1569",
                      "info": {
                          "URL": "static.zdassets.com",
                          "city": "Dublin",
                          "state": "Leinster",
                          "vendor": "zendesk",
                          "country": "Ireland",
                          "referrer": "https://demo.zendesk.com/",
                          "ipAddress": "3.3.3.3",
                          "stateCode": "L",
                          "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/135.0.0.0 Safari/537.36",
                          "currentUrl": "https://static.zdassets.com/admin/contributor/admin_center_framework_web_widget/2eb78401e7c389de5790eb4692182292dc82b9fe/383dc202de8dfef2f1117366f9172038.html#key=66dca387-9072-4c5a-8eab-8b8508fcd9a3&instructions=Save+your+changes+to+see+them+here.+They+may+take+a+moment+to+appear.&dir=ltr&locale=en-us&hasCustomLauncher=false&customLauncherOpen=Open+Web+Widget&title=Certainly",
                          "sdkVersion": "0.1",
                          "countryCode": "IE",
                          "currentTitle": "Certainly",
                          "browserLanguage": "en-US"
                      },
                      "type": "web",
                      "status": "active",
                      "clientId": "680f4f6d6b73a4d81fe3aaaa",
                      "lastSeen": "2025-04-28T09:50:41.083Z",
                      "integrationId": "6464101f0e984d5e7092aaaa"
                  },
                  "integrationId": "6464101f0e984d5e7092aaaa"
              },
              "content": {
                  "text": "Hello",
                  "type": "text",
                  "payload": "Hello"
              },
              "metadata": null
          }
      },
      "switchboardId": "680f37715b68d05ddd63aaaa",
      "switchboardIntegrationName": "certainly_dev",
      "switchboardIntegrationType": "certainly_dev"
      }

      Example of the content of the sc variable sent with the "conversation:create" event data. That event happens when a user opens the Zendesk Messaging widget. Note that it misses the last_message.content and last_message.id

      {
      "appId": "63ee01a83f8aa501194aaaaa",
      "conversation": {
          "id": "680f4f6d6b73a4d81fe3470d",
          "type": "personal",
          "user": {
              "id": "680f4f6d6b73a4d81fe346e1",
              "profile": {
                  "locale": "en-US",
                  "localeOrigin": "apiRequest"
              },
              "signedUpAt": "2025-04-28T09:50:37.198Z",
              "authenticated": false
          },
          "brandId": "360003001111",
          "last_message": {
              "source": {
                  "type": "web",
                  "device": {
                      "id": "680f4f6d6b73a4d81fe3aaaa",
                      "guid": "8e837dfb118c434a9e1120bdca3e1569",
                      "info": {
                          "URL": "static.zdassets.com",
                          "city": "Dublin",
                          "state": "Leinster",
                          "vendor": "zendesk",
                          "country": "Ireland",
                          "referrer": "https://demo.zendesk.com/",
                          "ipAddress": "3.3.3.3",
                          "stateCode": "L",
                          "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/135.0.0.0 Safari/537.36",
                          "currentUrl": "https://static.zdassets.com/admin/contributor/admin_center_framework_web_widget/2eb78401e7c389de5790eb4692182292dc82b9fe/383dc202de8dfef2f1117366f9172038.html#key=66dca387-9072-4c5a-8eab-8b8508fcd9a3&instructions=Save+your+changes+to+see+them+here.+They+may+take+a+moment+to+appear.&dir=ltr&locale=en-us&hasCustomLauncher=false&customLauncherOpen=Open+Web+Widget&title=Certainly",
                          "sdkVersion": "0.1",
                          "countryCode": "IE",
                          "currentTitle": "Certainly",
                          "browserLanguage": "en-US"
                      },
                      "type": "web",
                      "status": "active",
                      "clientId": "680f4f6d6b73a4d81fe3aaaa",
                      "lastSeen": "2025-04-28T09:50:37.205Z",
                      "integrationId": "6464101f0e984d5e7092aaaa"
                  },
                  "integrationId": "6464101f0e984d5e7092aaaa"
              }
          }
      },
      "switchboardId": "680f37715b68d05ddd63aaaa",
      "switchboardIntegrationName": "certainly_dev",
      "switchboardIntegrationType": "certainly_dev"
      }

       

      Previously, Sunshine Conversations metadata was accessible via the reserved variable {{ss}}. This is set to be deprecated soon. 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.

      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


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