App panels allow Pipedrive users to see and use the data from your app directly inside Pipedrive in the form of a panel.
Visibility in the UI
App panel can be found inside the details view of Deals, People, and Organizations - as a panel in the left sidebar. The app panel will appear at the top of the left sidebar and its location can be changed, hidden, and reordered with other sections in the sidebar.
Each app is allocated only 1 app panel per detail view. Taking into consideration the 3 detail views (Deal, Person, and Organization), each app can have altogether 3 different app panels.
Structure of an app panel
The app panel can display a maximum of 5 objects. Each object contains a header (optional), object property(s) (max 10) and field data. The structure of the app panel objects is defined by the JSON Schema that is added in the app listing's edit page in Marketplace Manager.
The app panel also has an actions menu that contains a link to app settings, the possibility to remove the panel, and app-specific app actions. App-specific app actions are app actions that belong only to your app.
App panel and the contents of the action menu
In the footer of the app panel, there is an external link to the app where a user can find additional info that didn't fit in the app panel. This means that when a deal has 8 documents connected to it, 5 (the maximum quantity of objects) can be displayed in multi-object app panel and if the user wants to see all 8 documents they can click the 'See more' link. Both the 'See more' link in the footer of the app panel and the app settings link should be added as external links.
How does an app panel work?
When the panel is activated by a user or if a user clicks the reload button, we will renew the information in the panel by requesting the information from the API endpoint (which is provided in your app listing's edit page in Marketplace Manager). You will receive HTTP request to your API with Basic Authentication header (defined in Marketplace Manager as HTTP Auth username and password) and query parameters (described in the table below). If it takes more than 10 seconds for the response to be received, the app panel will display an "Oops something went wrong!" error message.
These are the parameters that are added to the API endpoint's URL:
resource
deal/person/organization
resource=deal
view
details
view=details
userId
userId=12345
companyId
companyId=12345
selectedIds
Entity ID that shows the ID of the selected entity
selectedIds=3
isShared
true or false
isShared=true- User sees app panel and its data but did not install the app.isShared=false- User has installed the app and sees the app panel.
isShared=true
You can add the app panels to Pipedrive UI either when registering the app or updating the existing app. For that, you need to fill in the following fields in Marketplace Manager in Pipedrive's UI:
Panel name (required)
Descriptive, max 30 characters
API endpoint (required)
The URL of the endpoint which we'll use to fetch the data of the object properties
HTTP Auth username and password (required)
Our service will send the HTTP request with these credentials as the Basic Authentication header to protect your data. To protect your data, we strongly recommend using authenticated HTTPS requests. Note that we do not support self-signed certificates.
JSON data structure (required)
A JSON file that describes the structure of your app panel seen in the Pipedrive UI
Panel location
Choose where the panel would be displayed:
- Deals details view
- People details view
- Organizations details view
JSON data structure
To create the app panel displayed in Pipedrive's UI, you need to add it as a JSON file to Marketplace Manager with a JSON schema defining the app panel's structure.
The app panel consists of a maximum of 5 objects which are titled by headers and contain a maximum of 10 object properties (excluding the header property), all of which should be defined in the JSON Schema. You can also use one object app panel template or multiple object app panel template for defining your JSON schema.
Object properties
In the JSON Schema, you can specify the object properties that your app panel will contain. These object properties should be added to JSON Schema as properties. We support the following types of object properties definitions:
Keep in mind that if the data received from your API endpoint does not match the required data types, the whole app panel's data will not be displayed and the user will see an error message stating "Oops! We are unable to fetch/refresh this app data right now.".
Text
$ref: "#/definitions/text"
Can contain links and emails.
Truncated after 255 characters.
Numerical
$ref: "#/definitions/numerical"
12.00
12,00
Date
$ref: "#/definitions/date"
YYYY-MM-DD
2018-11-23
Time
$ref: "#/definitions/time"
hh:mm:ssZ
20:20:39+02:00
DateTime
$ref: "#/definitions/date-time"
YYYY-MM-DDThh:mm:ssZ
2018-11-13T20:20:39+02:00
Phone number
$ref: "#/definitions/phone"
+3725000001
Address
$ref: "#/definitions/address"
460 Park Ave South, New York, NY 10016, USA
Currency
$ref: "#/definitions/currency"
USD 200,99
Label
$ref: "#/definitions/label"
See how label should be defined in your API response.
Available colors for the label:
- Green (#08A742)
- Red (#F94839)
- Blue (#317AE2)
- Yellow (#FFCC00)
- Purple (#721EA9)
- Grey (#B9BABB)
Label's text is truncated after 40 characters
Label's text should be in sentence case e.g Potential client
In our JSON Schema the additionalProperties keyword is set to false by default, so you can only send values to those properties that are defined. If you send data that isn't defined properly under properties, the panel won't be rendered correctly and the user will see an error. For more information regarding how we'll display the property's data see understanding JSON Schema and additional properties.
The ordering of properties
The set of properties will be rendered to the list of object properties in the app panel according to the way they are defined in the JSON Schema. The only exception is the header property, which will be excluded from the array and moved to the header of the app panel's object. For example, if in properties the object properties are defined in order of id, header, name and email, then the order visible in the UI's app panel would start out with the app panel's object header and have name and email as object properties.
Currency in API response
currency object property should be defined as an object in the API response and values for code and value properties should be given. code is the ISO-4217 format currency code for non-custom currencies (custom currencies cannot be added or removed via the API, only admin users of the account can configure them from the Pipedrive web app). Overall code is matched to the codes defined in Pipedrive and if the currency is already defined with a symbol, the symbol is shown instead of the currency code in the app panel.
"currency": {
"code": "USD",
"value": 100.33333
}
Visual of label object property
label object property should be defined as an object in the API response and values for color and label properties should be given. label's colors can be green, red, blue, yellow, purple, grey. Label's text of the label object property can be 40 characters long before truncated.
"label": {
"color": "green",
"label": "Status"
}Header property
header is a separate optional property that defines the header of the app panel e.g. "Visit on 28th February". header property is required when you have multiple objects in a panel. You can define the header property the same way you have defined all other object properties:
{
"type": "array",
"items": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"$ref": "#/definitions/numerical"
},
"header": {
"$ref": "#/definitions/header"
}
}
}
}
Example of multiple object panel
To have an app panel containing multiple objects, you can refer the objects in the form of an array, where the object properties of the app panel are defined in properties. All labels of objects properties should be in sentence case. You can also use this template for defining your JSON schema for multiple object app panel.
{
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"email"
],
"properties": {
"id": {
"$ref": "#/definitions/numerical"
},
"header": {
"$ref": "#/definitions/header"
},
"name": {
"$ref": "#/definitions/text"
},
"email": {
"label": "Email",
"$ref": "#/definitions/email"
},
"date": {
"label": "Created",
"$ref": "#/definitions/date-time"
}
}
}
}The URL you add to the Marketplace Manager should respond with the data, which is received from the API and is structured as in the following example. If there's no data or the value null sent back in the response for one property, this property's data will be displayed as empty.
{
data: [
{ id: 1, header: "User #1", name: "John", email: "[email protected]", date: '2019-10-01T19:20:11+02:00' },
{ id: 2, header: "User #2", name: "Jane", email: "[email protected]", date: null },
{ id: 3, header: "User #3", name: "Tim", email: "[email protected]", date: '2019-10-01T19:20:11+02:00' }
]
}The response should be empty when the app panel doesn’t have an entity tied to it on the app’s side. For example, when there’s no connection between a deal and a document on the app’s end, we'll only display an error message stating "No data connected to this deal".
{
data: [
]
}
Example of one object app panel
The app panel can also consist of only one object (see the code below). You can use this template for defining your JSON schema for one object app panel.
{
"type": "object",
"required": [
"id",
"name",
"email"
],
"properties": {
"id": {
"$ref": "#/definitions/numerical"
},
"name": {
"$ref": "#/definitions/text"
},
"email": {
"$ref": "#/definitions/email"
},
"date": {
"label": "Created",
"$ref": "#/definitions/date-time"
}
}
}Example response:
{
data:
{ id: 1, name: "John", email: "[email protected]", date: '2019-10-01T19:20:11+02:00' }
}Also, note that the response should be empty when the app panel doesn’t have an entity tied to it on the app’s side. For example, when there’s no connection between a deal and a document on the app’s end, we'll only display an error message stating "No data connected to this deal".
{
data: {
}
}External links in the app panels
You can add two types of external links to an app panel - a link to app settings and a 'See more' link in the footer of the app panel.
An external link to app settings is displayed under the actions menu on the top right-hand corner of the app panel.
External link to app's settings
To add a link for app settings, you'd need to extend the API response by adding a settings object next to the data as seen in the example code below. The settings object should contain the URL property of the link.
{
data: [ ],
settings: {
url: 'https://google.com'
}
}An external link in the footer of the app panel can be used to have an entrance link to your app right inside the app panel. You can add one external_link per app panel.
Link to see more additional information in your app
To add an external link for your app to the app panel's footer, you will need to extend the API response by adding an external_link object next to the data as seen in the example code below. The url should follow the link definition. The label property should be descriptive text in sentence case that explains to the user what happens when the link is clicked. The label property will be fully visible in the length of 40 characters, after that it'll be truncated.
{
data: [ ],
external_link: {
url: 'https://google.com',
label: 'See more data'
}
}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 for development of the app panels and to make sure they work properly.
Remember that any changes saved when updating a public app in the Marketplace Manager will all be immediately visible for your app users.
What to consider when submitting app panels?
In the header of the app panel are your app's icon and the name of the app panel. Both the icon and the app panel's name can be added to your app's listing in the Marketplace Manager. Since your app's icon will be displayed next to the title of the app panel and it'll be minimized, please consider how recognizable your icon is when it's displayed in the app panel.
Updated 8 days ago
Further reading
| App actions |
| App extensions |