Custom UI extensions (BETA)

📘
Custom UI extensions is currently in BETA. As this feature is still in development, it's subject to change. Please send your feedback to [email protected].
NB: Please ensure you test this feature on a draft app, not an approved/public one.

What are custom user interface extensions?

A custom user interface (UI) extension is an area in Pipedrive’s UI that extends an app’s functionality by loading any contextual web content within an embedded iframe. This allows apps to display their content directly inside different Pipedrive views.

We have three custom UI extension points:

Custom panel

A custom panel is an iframe embedded inside a sidebar panel in the detail view of deals, people, and organizations.

Custom modal

A custom modal is an iframe embedded in a modal that opens when triggered by the user from various menus and links inside Pipedrive.

Custom UI for app settings

Custom UI for app settings is an iframe embedded in a surface that gives users easy access to user settings for your app.

How can custom UI extensions be used?

An example of a custom panel displaying related information to a Pipedrive deal

Custom UI extensions can be used in a multitude of ways. You now have near-complete freedom to showcase any content you want, as you can load any contextual web content within the iframe solution for your Pipedrive use case.

Some examples include displaying related information to Pipedrive entities like documents/invoices/proposals, multimedia, email marketing data, text messages, data visualization, customer support cases, contact management, multi-step forms, etc.

Custom UI extensions could also extend Pipedrive’s functionality, such as calculating data based on Pipedrive information and detecting duplicate deals.

How do custom UI extensions work?

A custom UI extension is an embedded iframe within Pipedrive’s UI that showcases your app’s content in the form of a contextual, external webpage.

The webpage to be embedded has to be hosted externally on the app service’s side. It has to have its own publicly accessible URL along with frontend and backend capabilities. Any JS framework and language can be used to build the front end and back end of the custom UI extension.

1165 — Data flow for custom UI extensions

When a custom UI extension gets loaded or reloaded, an iframe request with query parameters will be sent. This should be validated in the app’s backend using the provided JWT. The webpage from the URL you provide in Developer Hub should render while the SDK initializes with id. Pipedrive will now load the iframe with your external webpage.

The iframe request will contain the following query parameters:

Parameter	Explanation/value(s)	Examples
`userId`		`userId=12345`
`companyId`		`companyId=54321`
`token`	JWT that identifies which user and which Pipedrive company is loading the iframe	`token=xxxxx.yyyyy.zzzzz`
`id`	Unique ID/runtime token for the iframe that has to be passed to the SDK	`id=56789`
`resource`	deal/person/organization	`resource=deal`
`view`	details	`view=details`
`selectedIds`	Entity ID that shows the ID of the selected entity	`selectedIds=3`

If the iframe takes more than 10 seconds to initialize via our SDK, the iframe won't be displayed to the user.

The JWT (token) has to be validated server-side. You will have to initialize the SDK with the provided id.

The JWT secret can be specified in Developer Hub when adding your custom UI extension. If no value is added in Developer Hub, we will use the client secret as the JWT secret value by default.

Note: The SDK will try to read the id from the URL itself. In most cases, the id will not have to be passed manually. It has to be manually passed only if you modify the iframe URL, e.g., with redirects.

SDK

📘
Want to see what the code for custom UI extensions looks like? Check out our example apps on GitHub and run them yourself.

To add a custom UI extension, it is mandatory to use the SDK to initialize the webpage and communicate with the main Pipedrive window.

SDK contents

Our SDK contains the following features, of which you’ll find the code examples in our Github SDK readme.

Verification
Our SDK verifies the iframe using the unique extension id.

Commands
Snackbar
A small “popup” in a snack bar displays a message and link (optional) to the user and disappears after some time.

Confirmation dialog
A popup dialog that enables the user to verify an item. All contents can be customized, with the result being passed back to the SDK.

Resize
The ability to adjust the height of the iframe for custom panels and the height and width of the custom modal iframe. The sizes can also be provided when initializing the SDK, so it is already displayed with your defined sizes.

Get signed token
A new JSON Web Token (JWT) that is valid for 5 minutes will be generated.

Open modal
Opens a JSON modal, custom modal or a new Pipedrive deal, organization, person or activity modal

JSON modal
A popup modal that allows a JSON modal action. At the moment, this cannot be prefilled.
Custom modal
A popup modal with an iframe embedded in it. You can open a custom modal with prefilled data, use the CLOSE_MODAL command to close the custom modal and subsequently receive an update with the CLOSE_CUSTOM_MODAL event. View our example app to see how this works.
New deal/organization/person/activity modal
A popup modal that enables the user to create a deal, organization, person or activity where fields, such as names, can be prefilled.

Close modal
Closes an active modal window (only applicable for custom modals)

Events
Visibility
Apps can subscribe to VISIBILITY changes triggered by the user or an SDK command.

Custom panel
Apps can subscribe to custom panel visibility events to discover when a user collapses or expands the custom panel.

Close custom modal
Apps can subscribe to CLOSE_CUSTOM_MODAL events to discover when the modal was closed and who triggered the action – the SDK’s CLOSE_MODAL command or the user.

What to consider when building custom UI extensions?

You have to host your own web content
The web content to be displayed within the iframe for all custom UI extensions has to be hosted externally on your side, along with all frontend and backend capabilities.

Design of your web content
Please consider the design of your web page and how it would look within the Pipedrive web app. Check out Pipedrive’s design assets and use any components from there.

Height and width
When defining the height and/or width of a custom UI extension, please consider the actual size of the page to be rendered in the iframe and avoid overflow: auto in CSS.

Custom panel name and icon

For custom panels, your custom panel’s name and icon will be displayed in the panel's header. As your app’s icon will be displayed next to the title of the custom panel and minimized, please consider how recognizable your icon is when it’s displayed in the custom panel.

The icon can be added via the General info tab in Developer Hub
The custom panel’s name can be added via the App extensions tab

Custom UI extensions in app approval process

What if my app has already been approved?
If you already have an app or an integration available in the Pipedrive Marketplace, please create a new test app to develop custom UI extensions to ensure they work properly.

Remember that any changes saved when updating a public app in Developer Hub will be immediately visible to your app users.