Video calling app extension
This is a BETA feature!
For more info, help, and feedback, please feel free to contact us at [email protected].
Video calling access point inside Pipedrive
The video calling app extension gives app users the option to create, manage, and join video calls and meetings directly in Pipedrive’s activities.
Users can add/generate links for video calls by using video calling apps
Once the user has added a video call to an activity, additional information can be displayed with the video call link e.g. the duration and/or invitation information of the video call.
The fields Pipedrive fetches from video calling endpoints mapped in the manifest
Afterward, the information connected to the video call will then be displayed together with the activity throughout Pipedrive, e.g., in the contacts list, calendar view, deal detail view.
When an activity has been saved with the video calling app extension, a button will appear in the deal details view to join the call. Once clicked, the button redirects to the video call URL.
Development process
To extend your app’s capabilities to the activities modal, we’ve built the logic of reverse APIs, where Pipedrive will request information from a third-party video calling service’s API. These requests will be made to the endpoints that are defined in a manifest uploaded to the Developer Hub by the app creator.
- To begin, you’ll need access to the Developer Hub, where your app is maintained
- In Developer Hub, click on your app’s name and go to the OAuth & access scopes tab
- Select the video calls integration scope**
- Make sure that your app is connected to Pipedrive or a third-party service (if the app acts as an intermediary) and has finalized the connection. When a user has installed your app, the app will call the
POST /userProviderLinkendpoint and send the user information to Pipedrive. - Following this, get acquainted with what should be added to the manifest, create the manifest for your app, and add it to your app’s listing in Developer Hub
- Finish up your app and submit it for the app approval process
Connecting the app
Connecting your app to Pipedrive
The application is installed by clicking “install” within the Pipedrive Marketplace. Once the user has agreed to the scopes, the browser gets redirected to the app's registered callback URL (step 3 of OAuth authorization). At this moment, the app needs to fetch and permanently store the OAuth tokens it receives from Pipedrive (step 4 of the OAuth authorization). For video calling apps, we require generating a unique identifier string (e.g., a UUID) for each connection/link, which Pipedrive will use for all API calls executed against the app.
Finalizing the connection
After the unique identifier has been generated and the OAuth tokens stored, the app must register itself as a data provider by calling the POST /userProviderLink endpoint. To finalize everything, the app should redirect the user to the redirectUrl that was received as the response for the registration call against the Pipedrive API. On that page, the user will see if both the installation and connecting process succeeded and can then configure their preferences.
POST /userProviderLink
A video calling provider must call this endpoint after a user has installed the video calling app so that the new user's information is sent.
URL
https://{COMPANYDOMAIN}.pipedrive.com/api/v1/meetings/userProviderLink
A sample request structure made by the video calling app:
{
user_provider_id: 'string',
user_id: 001,
company_id: 007,
marketplace_client_id: 'string',
}
| Name | Type | Required/optional | Description |
|---|---|---|---|
user_provider_id | string, UUID | Required | A unique user_provider_id that has to be in UUID format |
user_id | number | Required | Pipedrive user ID of the user that installed the integration |
company_id | number | Required | Pipedrive company ID of the user that installed the integration |
marketplace_client_id | string | Required | Pipedrive Marketplace client ID of the installed app |
Sample of response structure:
Status: 200
{
success: true,
data: {
message: 'The user was added successfully'
}
}
Manifest for video calling app extension
A manifest describes, in a special contract format, the endpoints to which Pipedrive’s API will request. Based on the responses of those requests, the data received will be displayed inside Pipedrive UI in a pre-defined format. For the video calling app extension, the data received from the endpoints will be displayed in the activity modal.
The manifest for your app will need the appropriate URLs of a video calling service’s API endpoints. Once the manifest for your video calling app is submitted to Developer Hub, it will be validated against a pre-defined schema.
Template for video calling manifest
The file below defines the JSON schema of the manifest for an app that wants to display its contents inside the Pipedrive activities modal.
For your app’s manifest, just add your own value for clientID and corresponding URLs of a video calling service’s API requests to endpoints.
{
"version": "v202049",
"clientId": "dummyclientid123",
"endpoints": {
"postMeeting": "https://example.com/api/:linkId/",
"deleteMeeting": "https://example.com/api/:linkId/meetings/:meetingId",
"patchUpdateMeeting": "https://example.com/:linkId/meetings/:meetingId"
}
}
Manifest URL format
:linkId must be included in all endpoints' URLs. :linkId will be replaced with the unique identifier that the vendor registers the connection with. The unique identifier represents the connection between the app and the user.
:meetingId must be included in deleteMeeting and patchUpdateMeeting endpoint’s URLs. The :meetingId will be replaced with a unique meeting ID provided by the postMeeting endpoint by the provider.
Explanation of the manifest
| Object | Explanation | Required/optional |
|---|---|---|
”version” | Defines the version of the manifest. Currently, the only supported version is "v202049". | required |
"clientId" | Your app's client ID. You can get it from the OAuth & access scopes tab in Developer Hub. | required |
"endpoints" | Defines a set of video calling service’s endpoints' URLs to where Pipedrive will make requests to | required |
"postMeeting" | See postMeeting | required |
"deleteMeeting" | See deleteMeeting | required |
"patchUpdateMeeting" | See patchUpdateMeeting | required |
Video calling endpoints
Authentication
All requests from Pipedrive to the app will be supplemented with an authentication header using the same client ID and client secret as the OAuth token exchange in OAuth authorization.
E.g. Authorization: Basic <base64(client_id:client_secret)>
POST "postMeeting" endpoint
required
The postMeeting endpoint is used to create a video call meeting. It is called when the user starts adding a video call in the activity modal and can be done either in deal detail view or contacts view.
The body of the request made to the postMeetings endpoint:
{
topic: 'string',
start_time: 'YYYY-MM-DD HH:mm',
duration: 60
}
| Name | Type | Required/Optional | Description |
|---|---|---|---|
topic | string | Required | The name of the activity |
start_time | string | Required | Start time of the meeting in UTC format 'YYYY-MM-DD HH:mm' |
duration | number | Required | A positive number showing the length of the meeting in minutes |
The expected response from the postMeeting endpoint:
Status: 201
{
success: true,
data: {
meeting_id: 'string',
join_url: 'string',
password: 'string',
invitation: 'string',
}
}
| Name | Type | Required/Optional | Description |
|---|---|---|---|
meeting_id | string | Required | A unique meeting ID. meeting_id will be used for deleting and updating the information about the video call |
join_url | string | Required | A URL to join the video call |
password | string | Optional | Password for the video call |
invitation | string | Required | Invitation and/or information about the video call meeting |
PATCH "patchUpdateMeeting" endpoint
Required
The patchUpdateMeeting endpoint will be called when the name or time of the activity is updated.
The body of the request made to the patchUpdateMeeting endpoint:
{
topic: 'string',
start_time: 'YYYY-MM-DD HH:mm',
duration: 60
}
| Name | Type | Required/optional | Description |
|---|---|---|---|
topic | string | Required | The name of the activity |
start_time | string | Required | Start time of the video call in UTC format 'YYYY-MM-DD HH:mm' |
duration | number | Required | A positive number showing the length of the video call in minutes |
The expected response from the patchUpdateMeeting endpoint:
Status: 204
{
success: true
}
DELETE “deleteMeeting” endpoint
Required
The deleteMeeting endpoint will be called when the activity is deleted or the meeting link is deleted using the trashcan icon in the activity modal.
The body of the request made to the deleteMeeting endpoint will be empty.
The :meetingId parameter in the provided deleteMeeting URL in the manifest file will be replaced with a unique meeting ID.
The expected response from the deleteMeeting endpoint:
Status: 204
{
success: true
}
Updated 4 months ago