Widgets

Widgets help you extend your vertical application's functionality by embedding or integrating third-party applications. It enables you to pull real-time data from external resources to improve decision-making and streamline workflows within the applications. It enhances productivity by reducing the need to switch between different platforms. Their ability to connect with APIs allows you to integrate your application with a wide variety of applications.

For instance, you are building an Automotive Platform application for a dealership. Sales reps need to review customer financing details and open a live external valuation tool from the record detail page without leaving the deal context. You create a related list widget that loads an external valuation panel inside the customer or deal record, and a custom button widget that opens a document approval flow for the same record. You test the widget URLs, confirm the configured module mappings, and publish the application version. After publish, subscribers see the widget in the right place and can complete the workflow directly from the record without navigating away from the application. This reduces context switching and gives the team faster access to important third-party data.

Widgets are packagable components. When you publish your application, widget definitions created in the Developer Console are included in that version and become available to subscribers during signup or version upgrade, depending on the widget type and packaging behavior.

Check out Installing the CLI and Creating Your First Widget documents for step-by-step guidance on building a widget.

Javascript SDK

Refer to the Javascript SDK of the widgets that includes the API wrappers for accessing your application's inbuilt functions. This SDK will help the widget to access/manipulate the data of the subscriber's organization.

Where to access and configure widgets from the Developer Console

Log in to your Developer Console.
Go to Utilities > Connected Apps.
Create or edit the connected app that will host the widget content.
Open the widget configuration area for the required widget type, such as Telephony, Related Lists, Links & Buttons, Business Card, or Setup.
Enter the widget name, choose the module or placement, add the sandbox URL, and save the configuration.
Publish the application version so subscriber orgs receive the widget definition.

Types of Widgets

Following are a few types of widgets that can be created in the developer console and deployed in the subscriber's organization:

Once you have built the widget, configure it in the Connected Apps of Zoho Developer Console and establish it in relevant places as specified for each type in the following sections.

The Homepage, Create Records, Setup and Blueprint widgets are currently in Early Access and not yet publicly available. Contact our support team to enable these features for your account.

Telephony Widget

A telephony widget connects the vertical application with any third-party telephony service to help users make, receive, and log phone calls without switching tabs. It boosts productivity by providing a centralized space for managing client interactions, improving customer service, and optimizing sales operations.

Once installed, subscribers can initiate phone calls with a single click on the softphone icon or the phone number found within records.

Embed a Telephony Widget

After creating the widget in Connected Apps, navigate to Telephony in the left pane.
In the Telephony page, provide the following details:

Name for the widget in Call Center Name field.
A resource path in SandBox URL field.
This is the relative path to the main view of your telephony widget.

Click Save.

Widget in Web Tabs

A web tab is displayed like any other module in the subscriber's organization in which you can create modules with UI elements/features that cannot be added using prebuilt or custom modules. Widgets in web tabs make a significant impression than the regular web tabs as they can fetch data from external sources through APIs and display within the subscriber's organization for optimized workflows.

Below image is a sample widget web tab used for displaying a customer heat map.

Create a Web Tab

Once you have created the widget in Connected Apps, go to Modules in the left pane.
Shift to the Web Tabs section and click the Create Web Tab button.
Enter the following information:

Name for the widget in Tab Name field.
Select Type as Widget.
A resource path in SandBox URL field.
This is the relative path to the main view page of your web tab widget.

Click Save.

Widget in Related Lists

Widgets in related lists can be embedded within the related list view of a record in the records detail page. It elevates the functionality of the standard related lists by providing additional and real-time data from other modules or third-party applications.

For example, in the Deals module, a related list widget could pull in data from a third-party payment gateway to display real-time payment status for each deal record. This real-time visibility enhances subscriber workflows, reducing the need to switch between different applications to retrieve information.

Here is a sample Related List widget that shows the nearby leads' location to a salesperson.

Create a Related List Widget

After creating the widget in Connected Apps, go to Components in the left pane.
Select the Related Details tab and click the Add Widgets button.
Enter the following information:

Name for the related list in the Name field.
Select the name of the Module in which the related list has to be added.
A resource path in the SandBox URL field.
This is the relative path to the main view page of your related list widget.

Click Save.

Custom Button Widgets

Custom button widgets are specialized buttons that can execute specific actions, whenever triggered. These buttons are typically placed within list view pages or records detail view pages of modules. It allows the subscribers to automate tasks or access third-party services from the application's' interface.

For example, you can embed a Send SMS button in the Contacts module and integrate it with any messaging service to send SMS to a contact. This button can be placed either on the list view page or on the records detail page based on business requirements.

Create a Custom Button Widget

Once you have created the widget from Connected Apps, navigate to the Components located in the left pane.
In the Components page, select the Links & Buttons tab.
Click the Create New Button button.
Enter the following information:

Select the name of the Module in which the button has to be displayed.
Name for the button.
Click the Add Description link and specify the functionality of your custom button.
Choose the location to place the custom button.
Select Invoke a Widget as the action to be executed by the custom button.
A resource path in the SandBox URL field.
This is the relative path to the main view page, which will be displayed when your custom button widget is clicked.

Click Save.

Business Card Widget

Data in the records detail view page can be presented in a variety of modes. Business card widgets help you embed UI components and graphical data representations within the specific record. It helps you display data in new formats and derive diverse information that is not supported in the usual framework of the application.

Following are a few use cases of Business Card Widgets:

Display the degree of completion for details in any module record
Display related product suggestions
Display infographics or statistical data related to the record
Indicate progress of a process or steps covered in a process

Create a Business Card Widget

Once you have created the widget in Connected Apps, go to the Components in the left pane.
Select the Business Card Widget tab and click Create Widget.
Provide the following details:

Enter a name for the widget in the Widget Name field.
Select the Module to view the business card widget in.
Enter a resource path in the SandBox URL field.
This is the relative path to the main view page of your business card widget.

Click Save.

Packaged Business Widgets

A packaged Business Widget is a one that is created in the console by a developer and deployed to the subscriber orgs during signup or through upgrade. The following content explains how these widgets behave in subscriber orgs.

To know more about packaging, please refer to our guide on Components Packaging in Vertical Studio Platform.

Property	Upgrade Type	Modify Access
Name	Upgradable	Developer Editable
Sandbox URL	Upgradable	Developer Editable
Production URL *To be done from Connected Apps	Upgradable	Developer Editable

Changes and Impacts

When a packaged Business card Widget is added/modified, published, and deployed as an upgrade to the subscribers' accounts, it will have the following impact on the subscribers' accounts.

Create Widget: The new Widget will be available in the Subscriber orgs.
Delete Widget: If a packaged Business card Widget is deleted from the Developer Console, upon upgrading, it will be deleted from the subscriber orgs. Perform this action with caution as this is a destructive action.

Getting Started Widget

A Getting Started widget in an application will help in guiding the subscribers through essential steps and procedures to aid them in becoming familiar with it swiftly and efficiently. It can also simplify the onboarding by highlighting the essential actions, features, and procedures.

For example, you can design a widget for an onboarding Sales Manager to help them set up the environment to track leads, manage deals, and collaborate with sales teams.

Create a Getting Started Widget

Once you have created the widget in Connected Apps, navigate to Startup Actions > Getting Started Widget on the left menu.
Provide the following details:

Enter a name for the widget in the Widget Name field.
Choose the connected application with which you want to create a settings widget.
Enter a resource path in the SandBox URL field.
This is the relative path to the main view page of your business card widget.
Specify the Dimension of the widget either in terms of Pixel or Percentage.
Use the Active check box to manage the visibility of the widget in your organization.

Click Save.

The Homepage, Create Records, Blueprint, and Setup widget types that we are about to discuss are currently in the Early Access stage. Contact our support team at support@zohodeveloper.com to enable these types for your account.

Homepage Widget

The Homepage dashboard widgets help you monitor and manage essential business data at a glance. The data may relate to tracking performance metrics, visualizing trends, and keeping up with other key activities that require immediate attention. It reduces the time spent on navigating through different modules, their reports, and other third-party applications, thereby enhancing productivity.

Following are a few use case scenarios where the Homepage widget can be useful:

You can display the most recent blogs by the CEO on your dashboard to stay updated on the market.
For a Customer Support team, their dashboard widget can display the number of tickets closed by each teammate to inject enthusiasm and increase productivity.

Here is a sample home page widget with an external calendar.

Create a Homepage Widget

Once you have created the widget in Connected Apps, go to Homepage Widget on the left menu.
Click Create Widget and provide the following details:

Enter a name for the widget in the Widget Name field.
Choose the connected application with which you want to create a settings widget.
Enter a resource path in the SandBox URL field.
This is the relative path to the main view page of your setup widget.

Click Save.

Create Records Widget

The Create Records widget allows you to create custom interfaces for creating your records. Unlike the default create page, you can modify the layout, incorporate additional logic, and customize workflows for your specific business requirements. It provides greater flexibility and control over the data-entry process.

For example, you can create customized create pages for different roles for the Accounts Module, such as a quick form for Sales Reps and a detailed form for analysts.

Configure a Create Records Widget

After creating the widget in Connected Apps, navigate to Build > Modules on the left menu.
Shift to the Widgets tab and provide the following details:

Enter a name for the widget in the Widget Name field.
Choose the module in which you want to customize the create page with widget.
Pick where you want to display the widget in the Show in field.
Choose the connected application with which you want to create a settings widget.
Enter a resource path in the SandBox URL field.
This is the relative path to the main view page of your business card widget.

Click Save.

Widget in Blueprint

Blueprints help you define and enforce structured processes for your records by mapping out every step in a process and specifying conditions for transitions.

A widget in this area could assist and aid subscribers through each stage with relevant information and actions. This results in maintaining elevated consistency and efficiency for complex sales and support processes.

For example, consider a loan approval process that requires checking the previous loan history of the client. You can deploy a widget in between the blueprint transitions to check the loan history and move forward with the approval process.

Note:

You can create a maximum of four blueprint widgets for an application. \

Create a Widget in Blueprint

Once you have created the widget in Connected Apps, go to the Blueprint Widget on the left menu.
Click Create Widget and provide the following details:

Enter a name for the widget in the Widget Name field.
Choose the connected application with which you want to create a settings widget.
Enter a resource path in the SandBox URL field.
This is the relative path to the main view page of your setup widget.

Click Save.

Widget in Setup Page

This helps in adding new menu items or customized options in the Setup page. You can create a more intuitive and efficient setup experience to enhance productivity. With this, you can bring in various custom settings that are non-native to the application at one place, provide product/feature walkthroughs or directly connect with third-party applications based on your requirements.

For example, you can add Developer Help Documents to the menu and embed tutorial videos of the application using this widget.

Note:

You can create a maximum of four setup page widgets for an application.

Create a Widget in Setup page

Once you have created the widget in Connected Apps, navigate to the Setup Widget on the left menu.
Click Create Widget and provide the following details:

Enter a name for the widget in the Widget Name field.
Choose the connected application with which you want to create a settings widget.
Enter a resource path in the SandBox URL field.
This is the relative path to the main view page of your setup widget.

Click Save.

Widget in Help Center

You can embed help resources directly into your application using a custom widget. This widget allows users to connect with the support team through various channels, such as raising a ticket, using a chat assistant, submitting a voice recording, making a call, or initiating a video chat. Additionally, you can also use the widget to embed resources like a knowledge base, community forums, social media links, and other helpful content to provide a comprehensive support within your application.

Here is a sample of the quick access icon in a subscriber's organization.

The support you configure under Help Access will also be available under the profiles tab.

Create a Widget in Help Center

Once you have created the widget in Connected Apps, navigate to Package > Branding > Help Center on the left menu.
Toggle the Help Access field.
In the pop-up, choose the Access Type as In-app Widget and provide the following details:

Select the Connected App from the drop-down field.
In the Index Page, enter the resource path of your widget index file.
Specify the Dimension of the widget either in terms of Pixel or Percentage.
Enter the Pricing Plans that should have access to this support feature for the application.
Select the View Place box and choose the icon that suits your requirement.
Provide a display name for the icon in the Label.

Click Save.

Packaging behavior

The following table describes packaging behavior for widget configuration.

Property	Upgrade Type	Subscriber Modify Access
Widget name	Upgradable	No
Widget sandbox URL	Upgradable	No
Widget placement or module mapping	Upgradable	No
Widget type selection	Upgradable	No

Troubleshooting widget issues

Use this checklist when a widget fails to load, appears in the wrong place, or behaves incorrectly in a subscriber org.

Widget does not load or returns a blank area

Check the following before investigating the external application:

The connected app is configured correctly and the widget URL is valid.
The sandbox URL matches the intended widget view and is not pointing to a stale or missing page.
The widget is assigned to the correct module and the correct UI location, such as a record page, related list, or custom button placement.
The subscriber org has the required access and the app version was republished after the last change.

This matters for module-specific widgets such as related list, business card, and custom button widgets. If a widget is configured for the wrong module or wrong view, it can appear blank or not render even when the URL is valid.

Widget data is missing or not refreshed

If a widget loads but shows stale or empty data, confirm the following:

The widget is calling the correct API or data source.
The connected app has valid credentials and the required permissions.
The widget is not referencing stale record context or a deleted record.
The page or action that opens the widget still has the expected record context.
This pattern is common when a widget is configured with the correct display location but the data source or runtime context no longer matches the current record state.

Widget fails because of URL, iframe, or payload formatting

If the widget is blocked by malformed URL values, a missing whitelist, or a payload mismatch, confirm the following:

The sandbox URL is properly formed and does not include unsupported characters or malformed query strings.
The iframe behavior matches the allowed embed and content policy for the target page.
The widget payload matches the expected parameter names and data structure.
Any required configuration such as environment detection or API key retrieval is complete before the widget loads.

This issue is usually caused by a runtime configuration mismatch rather than a packaging failure.

Widget is missing after publish or upgrade

If a widget is not visible in subscriber orgs after publish, check the following:

The widget was included in the published application version.
The widget is assigned to the correct module, record context, or app-level placement.
The target pricing plan includes the related component or feature where the widget is expected to appear.
The subscriber org completed the upgrade or sign-up flow on the latest package version.

This is often a visibility, placement, or pricing-plan issue rather than a widget runtime failure. In many cases, the widget is mapped to the wrong module or location in the application rather than failing because of the code itself.

JavaScript SDK is undefined or initialization does not resolve

If the widget loads but returns SDK is undefined or the initialization promise never resolves, review the following checks:

The JavaScript SDK script is loaded before the widget calls any SDK functions.
The widget is pointing to the correct environment and connected app configuration.
The page does not load duplicate or stale script references that override the expected SDK object.
The browser console does not show a blocked script, invalid CSP rule, or missing dependency.
The app was republished after the SDK or connected app configuration last changed.

This is a common runtime issue when the widget code is valid but the page loads the wrong environment, an outdated script, or a missing dependency during startup.

Widget placement appears on the wrong pages or in the wrong UI area

Use this checklist when a widget is visible in the wrong area or appears on pages where it should not be displayed:

The widget is assigned to the correct module, page, and placement context.
The placement setting is not set to a broader default when the widget should be module-specific.
Any profile, visibility, or access rule still allows the widget in the wrong pages.
The latest app version was republished after the placement or module mapping change.

This is a common issue when a widget is mapped to a broad placement or a stale page configuration.

Widget upload fails with a generic error

If a widget or connected app asset fails to upload with a generic error, confirm the following:

The upload payload is not corrupted or incomplete.
The package name, file type, and app version are valid for the target environment.
The connected app or widget is not already associated with a conflicting configuration.
The browser session is valid and the latest app version has been saved before retrying the upload.

This is usually a packaging or environment-state issue rather than a problem with the widget runtime itself.

Changes and impacts

Delete widget

When a packaged widget is deleted from the Developer Console, the change will affect subscriber orgs during the next package upgrade. Remove a widget only after confirming that no subscriber workflows depend on it and that the replacement path is documented.

Update widget URL or placement

Changing the widget URL, module assignment, or placement can have a direct impact on the subscriber experience. If the page still loads but the content is not where users expect it, the issue is usually caused by a stale configuration, wrong module mapping, or a mismatch between the page context and widget target.

Caution

Widget deletion and URL replacement can break subscriber workflows if the external content is still expected in the application. Validate the widget in a test org before publishing, and communicate any UI or data-flow change to the subscribers who depend on it.

Widgets in Zoho Vertical Studio | Vertical Studio Help Guide