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
• Webhook Execution Metadata
• Multi-language translation
• Channel-specific Metadata
  • Certainly Widget
  • Zendesk Chat
  • Sunshine Conversations & Zendesk Messaging
  • Facebook 
• Zendesk widget switch extension
• Use cases
• Additional considerations

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.

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

Webhook Execution Metadata

Webhook Variables are available in the bot right after the execution of any webhook.

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.

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.

Zendesk Chat Metadata

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

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.

{
  "sc": {
    "appId": "5f324eb1acf330000c177713",
    "switchboardId": "4235dsf4tre55",
    "conversation": {
      "id": "65733d483f8e3e50a57a42c0",
      "type": "personal",
      "metadata": {
        "isFirstTimeCustomer": true
      },
      "user": {
         ...
      },
      "last_message": {
         ...
      }
    }
  }
}

{
  "isFirstTimeCustomer": true
}

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

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

Here is an example of the content of the sc variable:

{
"appId": "63ee01a83f8aa50119111111",
"conversation": {
    "id": "66bc8ecea4581c4a3d111111",
    "type": "personal",
    "user": {
        "id": "66bc8ecea4581c4a3d111111",
        "metadata": null,
        "externalId": "",
        "displayName": "Web User 66bc8ecea4581c4a3111111"
    },
    "metadata": null,
    "last_message": {
        "id": "66bc8ed1ada7d93980a111111",
        "source": {
            "type": "web",
            "device": {
                "id": "66bc8ecea4581c4a3d8111111",
                "guid": "fab40f51cb2341b4b27ecc2a47111111",
                "info": {
                    "URL": "static.zdassets.com",
                    "city": "Dublin",
                    "state": "Leinster",
                    "vendor": "zendesk",
                    "country": "Ireland",
                    "referrer": "https://mydomain.zendesk.com/",
                    "ipAddress": "3.255.27.111",
                    "stateCode": "L",
                    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36",
                    "currentUrl": "https://static.zdassets.com/admin/contributor/admin_center_framework_web_widget/d56339864e1f97f3b0ab72e9cbeda34911111/e7d54baed37b06d7a525edcca61111f.html#key=66dca387-9072-4c5a-8eab-8b8511111&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": "66bc8ecea4581c4a3d1111",
                "lastSeen": "2024-08-14T11:02:41.412Z",
                "integrationId": "6464101f0e984d5e111111"
            },
            "integrationId": "6464101f0e984d5e7011111"
        }
    }
},
"switchboardId": "66bc57a5717ed013e59111111"
}

Facebook Metadata

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. 

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.

Use cases

In this section, we'll address the following use cases:

• Search filtering params (in URL)
• Form submission

Search filtering params (in URL)

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