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 continously, 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"
}