Skip to content

Nudges

Nudges are small conversation starters: chat bubbles and UI elements that are triggered by conditions, like the visitor browsing to a certain web page.

Nudges are meant to convince the user to engage with the bot. As such, they only show when the chat widget is closed. Nudges only apply to the chat widget, they are not implemented on other channels.

Configuration

You can create a nudges.yml file which contain a list of nudges.

- title: again
  id: again
  expr: visitor.returning == true
  contents:
    message: "**Hi again!** Nice to see you again. Lets talk \U0001F449"
    bot_event:
      name: again
- title: welcome
  id: welcome
  expr: page.path == "/" && time_on_page > 3
  contents:
    message: "**Hi there!** We are here to help you, just click the button! \U0001F449"
    bot_event:
      name: welcome
- title: donation
  id: donate
  expr: page.fragment == "donate"
  contents:
    message: "**Please donate!** We rely on your donations! \U0001F449"
    bot_event:
      name: donate
- title: scroll
  id: scroll
  expr: page.scroll > 90
  contents:
    message: Seems you are eager to scroll all the way to the end
    bot_event:
      name: scroll

Nudge expressions

Each nudge can have an expression. While the visitor is viewing the page, this expression is evaluated continuously, and when the expression returns true, the corresponding nudge is pushed to the client and shown.

Only one nudge is shown at a time. While a nudge is being shown, the evaluation of nudge expressions is halted until the current nudge is either dismissed or engaged.

The order of nudges matter: the expressions are scanned from top to bottom of the file and the first matching nudge trigger is selected.

Available variables

The following variables can be used in nudge expressions:

Visitor variables:

visitor.inserted_at
visitor.returning
visitor.ip
visitor.timezone
visitor.locale
visitor.reverse_ip

visitor.geo_ip.city.name
visitor.geo_ip.city.geoname_id
visitor.geo_ip.country.geoname_id
visitor.geo_ip.country.is_in_european_union
visitor.geo_ip.country.iso_code
visitor.geo_ip.country.name
visitor.geo_ip.location.accuracy_radius
visitor.geo_ip.location.latitude
visitor.geo_ip.location.longitude
visitor.geo_ip.location.metro_code
visitor.geo_ip.location.time_zone

visitor.user_agent.raw
visitor.user_agent.device.brand
visitor.user_agent.device.family
visitor.user_agent.device.model
visitor.user_agent.device_os
visitor.user_agent.displayHeight
visitor.user_agent.displayWidth
visitor.user_agent.family
visitor.user_agent.id
visitor.user_agent.inputDevices
visitor.user_agent.is_crawler
visitor.user_agent.is_desktop
visitor.user_agent.is_tablet
visitor.user_agent.is_phone
visitor.user_agent.is_wireless_device
visitor.user_agent.model
visitor.user_agent.os.family
visitor.user_agent.os.version.major
visitor.user_agent.os.version.minor
visitor.user_agent.os.version.patch
visitor.user_agent.os.version.patch_minor
visitor.user_agent.parentId
visitor.user_agent.vendor
visitor.user_agent.version.major
visitor.user_agent.version.minor
visitor.user_agent.version.patch
visitor.user_agent.version.patch_minor

Page variables:

page.scroll (0-100)
page.title
page.url
page.fragment
page.host
page.path
page.scheme
page.query
page.params.*
page.referrer.url
page.referrer.fragment
page.referrer.host
page.referrer.path
page.referrer.scheme
page.referrer.query
page.referrer.params.*

Others:

time_on_page (in seconds)
ab (AB-testing percentage, 0 <= ab < 100)
within_office_hours (boolean, looks at the configured opening hours in the bot settings)

Example user agent dumps

iPhone:

%{
  "ajax_support_javascript" => true,
  "device" => %{"brand" => "Apple", "family" => "iPhone", "model" => "iPhone"},
  "device_os" => "iPhone OS",
  "displayHeight" => 480,
  "displayWidth" => 320,
  "family" => "Mobile Safari",
  "id" => "iPhone",
  "inputDevices" => "touchscreen",
  "is_crawler" => false,
  "is_desktop" => false,
  "is_phone" => true,
  "is_tablet" => false,
  "is_wireless_device" => true,
  "model" => "iPhone",
  "os" => %{
    "family" => "iOS",
    "version" => %{
      "major" => "11",
      "minor" => "4",
      "patch" => "1",
      "patch_minor" => nil
    }
  },
  "parentId" => "genericApple",
  "raw" => "Mozilla/5.0 (iPhone; CPU iPhone OS 11_4_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/11.0 Mobile/15E148 Safari/604.1",
  "vendor" => "Apple",
  "version" => %{
    "major" => "11",
    "minor" => "0",
    "patch" => nil,
    "patch_minor" => nil
  }
}

Android:

OnePlus A9

%{
  "ajax_support_javascript" => true,
  "device" => %{
    "brand" => "OnePlus",
    "family" => "OnePlus ONEPLUS A5000",
    "model" => "ONEPLUS A5000"
  },
  "device_os" => "-",
  "displayHeight" => 480,
  "displayWidth" => 320,
  "family" => "Chrome Mobile WebView",
  "id" => "genericTouchPhone",
  "inputDevices" => "touchscreen",
  "is_crawler" => false,
  "is_desktop" => false,
  "is_phone" => true,
  "is_tablet" => false,
  "is_wireless_device" => true,
  "model" => "touch phone",
  "os" => %{
    "family" => "Android",
    "version" => %{
      "major" => nil,
      "minor" => nil,
      "patch" => nil,
      "patch_minor" => nil
    }
  },
  "parentId" => "generic-",
  "raw" => "Mozilla/5.0 (Linux; Android 9; ONEPLUS A5000 Build/PKQ1.180716.001; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/68.0.3440.91 Mobile Safari/537.36",
  "vendor" => "generic",
  "version" => %{
    "major" => "68",
    "minor" => "0",
    "patch" => "3440",
    "patch_minor" => "91"
  }
}

Google bot:

Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; Googlebot/2.1; +http://www.google.com/bot.html) Safari/537.36

%{
  "ajax_support_javascript" => true,
  "device" => %{"brand" => "Spider", "family" => "Spider", "model" => "Desktop"},
  "device_os" => "-",
  "displayHeight" => 900,
  "displayWidth" => 1600,
  "family" => "Googlebot",
  "id" => "desktopCrawler",
  "inputDevices" => "-",
  "is_crawler" => true,
  "is_desktop" => false,
  "is_phone" => false,
  "is_tablet" => false,
  "is_wireless_device" => false,
  "model" => "browser",
  "os" => %{"family" => nil, "version" => nil},
  "parentId" => "desktopDevice",
  "raw" => "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; Googlebot/2.1; +http://www.google.com/bot.html) Safari/537.36",
  "vendor" => "desktop",
  "version" => %{
    "major" => "2",
    "minor" => "1",
    "patch" => nil,
    "patch_minor" => nil
  }
}

The visitor variable in Bubblescript

When a bot user has also a visitor entry (e.g. when chatting through the web chat widget), a visitor variable is exposed inside the bot's script. It has an example value like the following:

[main] %{
  "geo_ip" => %{
    "city" => %{"geoname_id" => 2759821, "name" => "Amersfoort"},
    "country" => %{
      "geoname_id" => 2750405,
      "is_in_european_union" => true,
      "iso_code" => "NL",
      "name" => "Netherlands"
    },
    "location" => %{
      "accuracy_radius" => 50,
      "latitude" => 52.1657,
      "longitude" => 5.41,
      "metro_code" => nil,
      "time_zone" => "Europe/Amsterdam"
    }
  },
  "ip" => "2001:980:eb16:1:a97e:ab57:d3f2:8bb7",
  "last_page_view" => %{
    "fragment" => nil,
    "host" => "example.com",
    "path" => "/bot/23e47809-ad11-4d6f-8d24-fb1df176d9de/widget",
    "port" => 4000,
    "query" => "locale=en",
    "referrer" => nil,
    "scheme" => "http",
    "title" => "Widget preview",
    "url" => "http://example.com/bot/23e47809-ad11-4d6f-8d24-fb1df176d9de/widget?locale=en"
  },
  "locale" => "en",
  "reverse_ip" => nil,
  "timezone" => "Europe/Amsterdam",
  "user_agent" => %{
    "ajax_support_javascript" => true,
    "device" => %{
      "brand" => "Spider",
      "family" => "Spider",
      "model" => "Desktop"
    },
    "device_os" => "-",
    "displayHeight" => 900,
    "displayWidth" => 1600,
    "family" => "Chrome",
    "id" => "desktopDevice",
    "inputDevices" => "-",
    "is_crawler" => false,
    "is_desktop" => true,
    "is_tablet" => false,
    "is_wireless_device" => false,
    "model" => "browser",
    "os" => %{
      "family" => "Linux",
      "version" => %{
        "major" => nil,
        "minor" => nil,
        "patch" => nil,
        "patch_minor" => nil
      }
    },
    "parentId" => "generic-",
    "raw" => "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.77 Safari/537.36 (@botsquad/sdk; 0.13.0)",
    "vendor" => "desktop",
    "version" => %{
      "major" => "91",
      "minor" => "0",
      "patch" => "4472",
      "patch_minor" => "77"
    }
  },
  "visitor_id" => "d5x88wchtrspdrvixm02ia"
}