Use widgets to make your app interactive to Upsales users.

Widgets are available at a few hotspots as well as used to show details for
custom marketing events and app callback notifications.

Declaring widgets in your app Json

If your just using widgets for app callback notifications or custom marketing events, feel free to skip this part and scroll down to Widget object.

In your app Json, under uiElements, add the view you want to add as a key with the value being an object having the hotspot as a key and its value being an array containing each widget. A widget is an object looking like this {"name": "myWidget", "type": "widget"}

Yes we know, we know - that explanation might be a bit confusing, have a look at the example further down instead! 😅

Available Hotspots

Company view

Show a widget when viewing a company.

• accountCardTop 
• sidebarTop
• sidebar 

  "uiElements": {
     "account": {
        "accountCardTop": [],
        "sidebarTop": [],
        "sidebar": []
     }
  }

Contact view

Show a widget when viewing a contact.

• sidebar 

  "uiElements": {
     "contact": {
        "sidebar": []
     }
  }

Order and opportunity view

Show a widget when viewing an order or opportunity

• sidebar 

  "uiElements": {
     "editOrder": {
        "sidebar": []
     }
  }

Subscription view

Show a widget when viewing a subscription

• sidebar 

  "uiElements": {
     "editSubscription": {
        "sidebar": []
     }
  }

Edit appointment view

Show a widget when viewing an appointment

• sidebar 

  "uiElements": {
     "editAppointment": {
        "sidebar": []
     }
  }

Edit phone call view

Show a widget when viewing a phone call

• sidebar 

  "uiElements": {
     "editActivity": {
        "sidebar": []
     }
  }

Example:
Show a widget in the order and opportunity view by adding this to your app Json.

{
...
 "uiElements": {
    "editOrder": {
       "sidebar": [
          {
             "name": "myWidget",
             "type": "widget"
          }
       ]
    } 
 }
...
}

When a user opens the edit order view, a POST will be made to the apps /widget/<widgetName> endpoint, e.g,

https://myapp.com/widget/myWidget

Respond with a widget object (details further down).

Tip! If you only want a widget to show at the hotspot when certain criterias are fulfilled, simply respond with a 404 status code and the widget will be hidden.

Widget object

A widget object consists of the following properties

• icon

A text string or a (https) url to an image to use as logo for your widget. Leave out if you don't want any logo to show.

• rows

An array of widget rows (see widget row further down).

• click

An optional click action for the widget (see click further down). This will make the whole widget clickable, if you just want a button or a row to be clickable, use the click portperty in a widget row instead.
Example widget object

{
 "icon": "https://widget-icon.png",
 "rows": [
 "type": "text",
 "text": "This is a widget, yay!"
 ],
 "click": {
 "type": "widget",
 "name": "secondWidget"
 }
}

Widget row

Your widget can consist of one or many rows. This is what will build the content and actions of your widget.

Row types

• text

Displays a text string.

{ 
 "type": "text", 
 "text": "This is my text row"
}

markdown Experimental!

Use markdown to give text formatting to your row.

{ 
 "type": "markdown", 
 "markdown": "Some **markodwn** yay!"
}

iframe Experimental!

Show your html or web page inside an iframe.

{ 
 "type": "iframe", 
 "url": "https://www.example.com"
}

{ 
 "type": "iframe", 
 "html": "Some <b>html</b> yay!"
}

You can set some options for your iframe using the properties width, height and scrolling (true/false)

{ 
 "type": "iframe", 
 "html": "200x20px with<br><br>scroll", 
 "width": 200, 
 "height": 20, 
 "scrolling": true
}

image

Displays an image.

{ 
 "type": "image", 
 "url": "https://image.png", 
 "center": true 
}

buttons

Displays one or many buttons.

{ 
 "type": "buttons", 
 "options": [ 
 { 
 "text": "a button", 
 "fullWidth": false, 
 "click": { 
 "type": "widgetRow", 
 "name": "aNewRow" 
 }
 }
 ] 
}

dropdown

Show a dropdown with one or many options.

{ 
 "type": "dropdown", 
 "options": [ 
 { 
 "text": "a button", 
 "click": { 
 "type": "widgetRow", 
 "name": "aNewRow" 
 }
 }
 ] 
}

Click

Clicks make your widget interactive. You can link to external content as well as load new widgets and widget rows.

Clicks are available on the following objects

• The widget itself
• Widget row type text
• Widget row image
• Widget row type buttons options
• Widget row type dropdown options

Click types

• widget

Replace the widget with a new one. We'll do a request to https://your-app.com/widget/<newWidget> where <newWidget> is the value you enter in the "name" property for the click.

"click": { 
 "type": "widget", 
 "name": "myNewWidget" 
}

Your app must respond with a new widget object.

widgetRow

Replaces the widget row with a new one. We'll do a request to https://your-app.com/widgetRow/<newRow> where <newRow> is the "name" property for the click.

"click": { 
 "type": "widgetRow", 
 "name": "myWidgetRow" 
}

Your app must respond with a new widget row object.

window

Opens a new window with the url from the "url" property in the click.
Add "window":"self" to the click object if you want the url to open in the same window.

"click": { 
 "type": "window", 
 "url": "https://www.upsales.com"
}

modal

Opens a new widget in a modal. We'll do a request to https://your-app.com/widget/<newWidget> where <newWidget> is the value you enter in the "name" property for the click.

"click": { 
 "type": "modal", 
 "name": "myWidgetModal",
 "fullscreen": false
}

Your app must respond with a new widget object.

navigate Experimental!

Send the user to a view in Upsales you specify with the "go" property.

Available values

• config (your app config)
• account (company card with id from "id" property)
• contact (contact card with id from "id" property)

"click": {
 "type": "navigate",
 "to": "account",
 "id": 1234567
}

create Experimental!

Opens a create view for the user. Use the "entity" property to specify which type of object.

Available values

• activity
• appointment
• opportunity

Use the "options" property to add pre-defined values to the object.

"click": {
 "type": "create", 
 "entity": "activity", 
 "options": {
 "description": "My activity...",
 "date": "2018-12-01"
 }
}

reload

Reloads the widget. Great to use when developing!