Plugin Widgets Reference (V1)

Updated on October 4, 2021

Widgets offer a wide range of possibilities for developers and companies wanting to provide new features straight in the Crisp app.

A widget can be configured through Crisp Marketplace by creating a Private or Public plugin, and then declaring the Widget Schema.

This reference contains the schema description for widgets.

Root

Description: the root object of an iFrame Widget.
Properties:
- version: the version of the schema (required, current version is 1.0)
- url: the URL to display as the iFrame Widget (required)

{
  "version": "1.0",
  "url": ""
}

Root

Description: the root object of a Generic Widget.
Properties:
- version: the version of the schema (required, current version is 1.0)
- sections: (required)

{
  "version": "1.0",
  "sections": []
}

Section

Description: a group of items.
Properties:
- id: the identifier of the section (required)
- title: the title of the section (required)
- condition: a condition to whether show or hide the section (read about conditions here)
- items: the items of the section (required)

{
  "id": "",
  "title": "",
  "condition": "",
  "items": []
}

Link Button Item

Description: a button item that opens a link in a new tab.
Properties:
- id: the identifier of the item (required)
- type: the type of the item, button here (required)
- condition: a condition to whether show or hide the item (read about conditions here)
- value:
  - type: the sub-type of the button, link here (required)
  - label: the label of the button (required)
  - url: the link to open (required)
  - color: the color of the button (defaults to black)
    - Values
      - black
      - blue
      - green
      - orange
      - red
      - purple
  - data: the data to attach to the Button Event request, as query parameters (read about events here)

{
  "id": "",
  "type": "button",
  "condition": "",

  "value": {
    "type": "link",
    "label": "",
    "url": "",
    "color": "",
    "data": {}
  }
}

Description: a button item that opens a link in a modal.
Properties:
- id: the identifier of the item (required)
- type: the type of the item, button here (required)
- condition: a condition to whether show or hide the item (read about conditions here)
- value:
  - type: the sub-type of the button, modal here (required)
  - label: the label of the button (required)
  - url: the link to open (required)
  - color: the color of the button (defaults to black)
    - Values
      - black
      - blue
      - green
      - orange
      - red
      - purple
  - size: the size of the modal (defaults to normal)
    - Values
      - normal
      - medium
      - large
      - wide
  - controls: states which controls ("Open in new tab", "Close", "Minimize" and "Move" buttons) are shown bellow the modal (boolean or array, defaults to true). When the "Close" control is hidden, the modal closure can be triggered via the widget JS SDK.
    - Boolean value: whether to show all controls or to show none
    - Array value: the list of buttons to show
      - Values
        
        open
        
        close
        
        minimize (the move button will be automatically added when the modal is minimized)
  - data: the data to attach to the Button Event request, as query parameters (read about events here)

{
  "id": "",
  "type": "button",
  "condition": "",

  "value": {
    "type": "modal",
    "label": "",
    "url": "",
    "color": "",
    "size": "",
    "controls": true,
    "data": {}
  }
}

Hook Button Item

For this item, the plugin must have a configured action URL (Marketplace dashboard, Plugin area, Settings tab).

Description: a button item that sends a request to the plugin's action URL.
Properties:
- id: the identifier of the item (required)
- type: the type of the item, button here (required)
- condition: a condition to whether show or hide the item (read about conditions here)
- value:
  - type: the sub-type of the button, hook here (required)
  - label: the label of the button (required)
  - color: the color of the button (defaults to black)
    - Values
      - black
      - blue
      - green
      - orange
      - red
      - purple
  - data: the data to attach to the Action Event request, as body payload (read about events here)

{
  "id": "",
  "type": "button",
  "condition": "",

  "value": {
    "type": "hook",
    "label": "",
    "color": "",
    "data": {}
  }
}

Submit Button Item

For this item, the plugin must have a configured action URL (Marketplace dashboard, Plugin area, Settings tab).

Description: a button item that sends a request to the plugin's action URL, with all the values of the data items having the same group identifier.
Properties:
- id: the identifier of the item (required)
- type: the type of the item, button here (required)
- condition: a condition to whether show or hide the item (read about conditions here)
- value:
  - type: the sub-type of the button, submit here (required)
  - label: the label of the button (required)
  - color: the color of the button (defaults to black)
    - Values
      - black
      - blue
      - green
      - orange
      - red
      - purple
  - group: the group identifier (required)
  - data: the data to attach to the Action Event request, as body payload (read about events here)

{
  "id": "",
  "type": "button",
  "condition": "",

  "value": {
    "type": "submit",
    "label": "",
    "color": "",
    "group": "",
    "data": {}
  }
}

Data Item

For this item, the plugin must have a configured action URL (Marketplace dashboard, Plugin area, Settings tab).

Description: an item that displays data from internal source (ie. Crisp app) or external source (ie. backend, internal CRM, API).
Properties:
- id: the identifier of the item (required)
- type: the type of the item, data here (required)
- condition: a condition to whether show or hide the item (read about conditions here)
- value:
  - label: the label of the data (required)
  - value: the data value (can be omitted, empty, static or dynamic)
    - If value is omitted (ie. no value), then the item will display the placeholder. If the user enters some data, it will be forwarded to the plugin, via an Action Event request to the action URL (read about events here)
    - If value is empty (ie. an empty string "value": ""), the data will be fetched by sending an Action Event request to your plugin's action URL (read about events here)
    - If value is static (eg. a literal string "value": "abcde"), it will be displayed as is
    - If value is dynamic (eg. a data binding "value": "{conversation.meta.data.order_id}"), it will be bound to Crisp data (read about data binding here)
  - placeholder: the placeholder of the data. In case of a static or dynamic value, placeholder will be ignored.
  - editable: whether to allow data edition or not (defaults to true). In case of a static or dynamic value, editing will not be possible.
  - immediate: whether to immediately fetch the data or not (ie. on conversation's load) (defaults to true)
  - group: the group identifier of the data (see Submit Button Item)
  - data: the data to attach to the Action Event request, as body payload (read about events here)
  - icon: the icon of the data (defaults to info)
    - Values
      - account_box
      - add_circle
      - add
      - align_center
      - align_justify
      - align_left
      - align_right
      - archive
      - arrow_drop_down
      - arrow_drop_up
      - attach_file
      - audio_unmute
      - audio
      - block
      - book
      - bug_report
      - business
      - call_end
      - cancel
      - chat_bubble
      - chat
      - check_circle
      - check
      - chevron_left
      - chevron_right
      - close
      - cloud_done
      - cloud_download
      - cloud_off
      - cloud_upload
      - clock
      - cloud
      - code
      - computer
      - credit_card
      - delete_forever
      - delete
      - devices
      - done_all
      - edit
      - email
      - error
      - extend_enter
      - extend_exit
      - file_copy
      - flag
      - help
      - home
      - info
      - insert_chart
      - insert_photo
      - keyboard_arrow_left
      - keyboard_arrow_right
      - keyboard
      - language
      - link
      - map
      - message
      - mouse
      - movie
      - notifications
      - open_in_browser
      - open_in_new
      - palette
      - pause_circle
      - people
      - person
      - phone
      - pin_drop
      - play_circle
      - refresh
      - repeat
      - restore
      - robot
      - school
      - search
      - send
      - settings
      - star
      - unblock
      - unfold_more
      - video_unmute
      - video
      - visibility
      - warning
      - web_asset
      - wifi_tethering
      - work

{
  "id": "",
  "type": "data",
  "condition": "",

  "value": {
    "label": "",
    "value": "",
    "placeholder": "",
    "editable": true,
    "immediate": true,
    "group": "",
    "icon": ""
  }
}