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.
public_video_url	String	A public URL for the recoding of the Session, if one is available, which requires the viewer to be authenticated into 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.
secret_video_url	String	A secret URL pointing directly to the video recording of the Session, if one is available.
team	Team	An object representing the team the Session belongs to, with the following keys: id, domain, _type.
video_status	String	The status of the Session's video recording. One of pending, recording, not_available, ready, expired, removed.
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.