Messaging app extension overview

The Messaging app extension provides a way to integrate a messaging service directly into Pipedrive. For that, we have created a deep integration point with our Messaging inbox inside the Leads Inbox of Pipedrive.

An app with messaging capability can take advantage of both of our public API endpoints (Channels API) and manifest mapping to create a seamless flow of receiving and sending messages through a third-party tool right inside Pipedrive.

By using our Messaging app extension, your app user can send and receive messages from an external service (such as Facebook Messenger for Business, WhatsApp for Business, etc.) without leaving Pipedrive, as well as quickly link conversations to contacts, leads and/or deals.
The chat window allows you to easily display conversations from all of your channels, as well as to filter conversations from a specific channel when you need.

The Channels API has public endpoints to create and delete channels, and receive incoming messages. The API can also request your app’s endpoints to retrieve previous conversations and messages, senders/participants' info, and send new messages.

It’s possible to enable company-wide visibility for the app, which allows the integration's channels and conversations to be used by everyone in the Pipedrive company.

Development process

First steps to take

In order to access the Channels API and integrate with the Messaging app extension, you need to select the scope Messengers integration in your app listing page in Marketplace Manager.
Next, you'll need to upload the manifest for Messaging app extension. You can find a template of the manifest and all information about the endpoints needed for the integration on the Implementing Messaging app extension page.

Connecting the app

When it comes to establishing the connection, your app will need to first use OAuth2.0. When you have stored the access and refresh tokens (Step 4 and 5 of OAuth authorization) after the app user has accepted the scopes (Step 3 of OAuth authorization), your app can make the first call on-behalf of the user to create a new Channel through the Channels API's POST /channels endpoint in public Pipedrive API.

https://{COMPANYDOMAIN}.pipedrive.com/api/v1/channels

{
   "success":true,
   "data":{
      "id":"e283f878-7ef9-4294-8e5c-04a7d003fd92",
      "name":"My Channel",
      "avatar_url":"http://my-domain.com/images/test.png",
      "provider_channel_id":"4645c2e3-b5df-4acd-8299-76864c22a4ac",
      "marketplace_client_id":"57da5c3c55a82bb4",
      "pd_company_id":123,
      "pd_user_id":321,
      "created_at":"2022-03-01 00:00:00",
      "provider_type":"other",
      "template_support":false
   }
}

After the channel is registered by Pipedrive, manifest endpoints will start to be called.

First, Pipedrive will request from thegetConversations endpoint mapped in the manifest to the service's endpoint, providing information in a paginated format around messages and conversations happening in the channel. This, like all the requests done to manifest endpoints by Pipedrive, will follow basic authentication rules.

If the service provides values in the correct format, next requests will be made to various endpoints(getSenderByID and getTemplates) to finalize the connection depending on the setup and criteria of the integration.

Sharing the app

This app extension supports the option to share an installation with all Pipedrive company users. To enable this option for your app, please get in touch with the Marketplace team.

Once the team enables it, an extra step is shown during the installation for the user right after they have given access to the OAuth scopes.

Once shared, the channels registered by the app will be available to everyone in the company. All users can use most of what the extension has to offer, with a few exceptions:

• Only the installation owner can delete conversations.
• Only the installation owner can change the visibility (share/unshare the app installation).
• Only the installation owner can uninstall the app.
• If the app installed has more than one channel, only the installation owner can remove a channel.