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.

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.

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.

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 /user-provider-link endpoint 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 /user-provider-link 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 /user-provider-link

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/user-provider-links

A sample request structure made by the video calling app:

{
  user_provider_id: 'string',
  user_id: 001,
  company_id: 007,
  marketplace_client_id: 'string',
}

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

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
}

The expected response from the postMeeting endpoint:

Status: 201

{
  success: true,
  data: {
    meeting_id: 'string',
    join_url: 'string',
    password: 'string',
    invitation: 'string',
  }
}

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
}

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
}