Links are app actions that reroute users from Pipedrive to an external page hosted by your app to complete an action. It allows users to use and send the data from their Pipedrive accounts to your app. In this way, the data will gain value as it is displayed in context with the functionality of your app.
Links can give users the option to, for example, add contacts to email lists, create documents/proposals, send messages, and more with just a click of a button.
See how Links can work for a proposals and contacts app. In this example, the app displays the name of the deal, the value of the deal, and the contact person's information in the app.
See how Links can work for a bots and messaging app. In this example, the app displays the contact person's name, info, and phone number.
App actions can be added to the actions menu shown in the upper right area of the Detail view and the List view. App actions in List view will appear when an item(s) is selected.
App actions are visible when the user clicks on the three-dot actions menu in the list and detail views.
Each app is allowed to have 3 app actions or custom modals per view. This means an app can have a total of 21 app extensions (app actions or custom modals) from menus (7 possible views x 3 extensions).
If the user hasn't selected any items in the List view, the app actions aren't available.
When a user selects an app action from the menu, a new browser tab will be opened. Next, in the same browser tab, the user will be redirected to an app's page if the user has an active app installation status. The redirection will be done to a URL that consists of the app's URL, which is supplied by the app owner in the Marketplace Manager, as well as parameters that Pipedrive adds relating to the selected item(s). The added parameters enable the app to make requests to Pipedrive's API and fetch data to allow the user to complete an app action.
Note that because the items selected by a user will directly relate back to the URL, you can run into a situation where several hundreds of items will be populated directly to the URL. In these scenarios, please be ready to encounter URL length limitation errors.
The new tab opened right after the user clicks the action has the following URL structure. The
:actionId parameter in the URL is the unique identifier of the app action that Pipedrive will replace with a value.
These are the parameters that are added to the URLs:
Explanation or value(s)
details or list
Entity IDs that show all the selected IDs in an array form
Entity IDs that show all the excluded IDs in an array form (only in the list view)
Stringified JSON object of filter type (filter or owner) and its ID (or "everyone") (only in the list view). In the Activity list view, the object will include Activity type and depending on user's choice Activity start date and end date.
Note that in the list view,
excludedIdswill appear empty when all items are selected with the select-all checkbox.
excludedIdswill also appear empty when just some items are manually selected.
Sample URL that is added to Marketplace Manager: https://www.randomawesomeapp.com/action/handle
In the List view...
The parameters that Pipedrive sends: ?resource=deal&view=list&userId=12345&companyId=12345&selectedIds=1%2C9&excludedIds=&filter=%7B%22everyone%22%3A1%7D
The whole List view URL:
In the Activities list view when the activity start and end date are selected:
In the Detail view...
The parameters that Pipedrive sends: ?resource=deal&view=details&userId=12345&companyId=12345&selectedIds=9
The whole Detail view URL:
Go to your app’s edit page in Marketplace Manager and scroll to the App extensions' section.
Click on “+ Action” under Actions and select “Link” as the Action type, the form will slightly change depending on which type of App action you'll choose.
Next, fill in the name of the Link app action and the rest of the fields.
Action name (required)
The name of the app action. Descriptive, max 30 characters.
The name will appear in the Features section of your Marketplace app listing.
To showcase the interactive features of your app, your action’s name and description will appear in the Features section of your Marketplace app listing.
Use the description field to let users know what they can do within this action.
Optional; max 150 characters.
URL that the user will be redirected to when they click on the Link
If left empty,
Location (one required)
Choose the view where the app action would be displayed:
Maximum 3 app extensions per location. Each app can have a total of 21 app actions or custom modals.
If you already have an app or an integration available in the Pipedrive Marketplace, please use your sandbox account (request one if you don't have a sandbox account) for testing the new app actions. Remember that any changes saved when updating a public app in the Marketplace Manager will all be immediately visible for your app users.
When app actions are submitted for review, we will thoroughly test them before approval and we strongly suggest testing your app actions on a test app prior to submitting for reviewal. Here are some things to consider while developing the actions:
- App actions must provide contextual information. This means that when an app action has been clicked by the user from inside the Pipedrive web app and they have been redirected to your app's page, related data from the user's Pipedrive account is displayed inside your app.
- Your app must be able to handle app actions performed both when a user has logged in to your app as well as when the user is not logged into your app:
- If the user is logged in to your app, the actions initiated by a user from Pipedrive must be fulfilled from your app's end.
- If the user isn't logged in to your app, the URL must redirect to your app's login or register an account page. After the user has logged in from the app's page, your app must be able to continue to fulfill the action initiated by the user in Pipedrive.
- If the app is uninstalled from the vendors' side, ensure that the app actions won't appear in Pipedrive UI anymore. For more information read about handling user's app uninstallation.
Updated about 2 months ago