Skip to content

Object types

Visitor

A Visitor represents a person connected through the Upscope SDK who is available to co-browse with.

Attributes

Attribute name Type Description
added_at Datetime The first time the Visitor was seen.
api_key String Your public API key.
browser_name String The name of the browser used by the Visitor (e.g. Mobile Safari).
call_name String The call identification (used for the Agent's personal link).
device_name String The name or brand of the device (e.g. iPhone).
device_type String The category of device the Visitor is connecting from. It will be one of desktop, console, mobile, tablet, smarttv, wearable, embedded.
email String The Visitor's email.
history Pageview[] If the collectHistory option is set to true, it will return a collection of Pageviews.
identities String[] A list of strings used to identify the Visitor. If the Visitor was not identified, this will be null.
integration String The auto integration we have performed on this Visitor. This will be set to the live chat system you have installed on the page last visited by the Visitor.
ip_address String The IP address the Visitor last connected from.
is_in_session Boolean A boolean describing whether the Visitor is currently screen sharing with someone.
is_online Boolean A boolean describing whether the Visitor is currently connected to Upscope (and available for screensharing).
is_supported Boolean A boolean describing whether the Visitor's browser supports Upscope.
is_waiting_for_call Boolean A boolean describing if the Visitor is waiting for a call from the agent.
js_configuration Boolean A boolean describing whether the Visitor has has configured Upscope through the Javascript API in a way that could conflict with the account's general settings.
last_seen_at Datetime A timestamp of the last time the Visitor was seen on the website
last_url String The last url the Visitor has visited.
location_city String The city the Visitor is in (according to their IP address). If the city is not known, this will be null.
location_country_name String The country (name) the Visitor is in (according to their IP address). If the country is not known, this will be null.
location_country String The country (code) the Visitor is in (according to their IP address). If the country is not known, this will be null.
lookup_code String The code your agent can search for to quickly find the Visitor in the interface. If not set, it will be null.
name String It will return the first identity that looks like a name.
nickname String It will return the Visitor's name, the first part of the Visitor's email, or the Visitor's ID.
sessions Session[] A list of recent screen sharing sessions with this Visitor.
short_id String The Upscope ID of the Visitor.
tags String[] The value provided in the tags.
unique_id String The unique ID used to identify the Visitor. If this was not set, it will be null.
watch_link String A public URL used to start a session with the Visitor.

Pageview

A Pageview represents a page that the Visitor was at.

Attributes

Attribute name Type Description
events Event[] A collection of Events.
pageview_id String The Pageview identification in the UUID format.
screenshot Screenshot A Screenshot taken during the Pageview.
ts Datetime The datetime of when the Pageview was collected.
url String The URL the Visitor was at when the Pageview was collected.

Event

An Event represents an action taken by the Visitor during a Pageview.

Attributes

Attribute name Type Description
icon String A URL of an icon representing the Event.
title String The description of the Event (e.g. Live chat conversation started).
ts Datetime The datetime of the event.
uuid String The event identification in the UUID format.

Screenshot

A screenshot is a png image of the Pageview.

Attributes

The attributes of the screenshot are divided in small, medium and large.

{
  "small": {
    "url": "https://example.com/100x100.png",
    "height": 100,
    "width": 100
  },
  "medium": {
    "url": "https://example.com/200x200.png",
    "height": 200,
    "width": 200
  },
  "large": {
    "url": "https://example.com/400x400.png",
    "height": 400,
    "width": 400
  }
}

Attribute name Type Description
height Integer The height of the screenshot.
url String The URL of the screenshot.
width Integer The width of the screenshot.

Session

A Session is a co-browsing interaction between one or more Agents and a Visitor.

Call vs Session

Throughout the docs, you'll see the concept of Calls and Sessions.

Sessions can happen with or without Calls, which are the audio component of a Session.

Attributes

Attribute name Type Description
agents Agent[] The collection of agents that joined the Session.
call_length_seconds Integer The duration of the audio call in seconds.
call_name String The username of the Agent that initiated the Session through their personal link.
ended_at Datetime The datetime of when the Session ended.
features_used String[] The collection of features used (e.g ["remote_typing"]).
formatted_call_length String The duration of the audio call formatted (e.g "00:11").
formatted_length String The duration of the Session formatted (e.g "01:10").
id String The ID of the Session.
length_seconds Integer The duration of the Session in seconds.
on_premise Boolean A boolean describing whether the Session happened on an on-premise version of Upscope.
session_authorized Boolean A boolean describing whether the Session was authorized by the Visitor.
source String A number describing the source of the Session. One of: api, search, lookup code, personal link, agent request, integration
started_at Datetime The datetime of when the Session started.
team Team An object representing the team that participated of the Session with the following keys: id, domain, _type.
visitor_id String The ID of the Visitor.
went_live Boolean A boolean describing whether the Session actually started.

Agent

An Agent is someone who started or joined the Session as an observer.

Attributes

Attribute name Type Description
agent_nickname String The Agent's nickname.
email String The Agent's email.
external_id String If generated through the REST API, the ID provided by you.
id String The Agent's id.
name String The Agent's name.
on_premise Boolean A boolean describing whether the agent is on premise.