Build messaging app integrations with Pipedrive
1. What is it about?
Messaging services such as WhatsApp, Facebook & Telegram are essential channels for businesses and a conduit for building successful relationships with customers. Pipedrive's Messaging app extension makes it easier to build integrations with these services.
It offers a native experience through the Messaging inbox in Pipedrive. All we need to do is build an app that conforms to the specifications and the rest of the heavy lifting is taken care of by Pipedrive and our Developer Platform.
In this tutorial, we will cover some of the key aspects via a Playground App.
What you'll learn
- How Messaging app extension works
- How does a Messaging Service (say WhatsApp) interact with Pipedrive
- What is the role of a Provider and how to implement it
- What is the Channels API and how does it relate to Messaging inbox
- Troubleshooting tips
2. Before we get started
To keep things simple, we will be building integration with WhatsApp in this tutorial. We will make use of the WhatsApp Cloud API and Pipedrive REST APIs to facilitate bi-directional communication.
We will also be building a Node.js app that uses Javascript for both frontend and backend. The app will run in Glitch and requires no local setup (Yay!). We also need to create trial accounts for Pipedrive and Meta Developer which should not take more than a few minutes. Here are the links for reference:
- Create a Pipedrive Sandbox Account to register and test the app
- Create a Meta Developer account to use the WhatsApp Cloud API
- Create a Glitch.com account so that we can do everything via the browser!
Here's also a quick rundown of some of the common terminologies that we might encounter throughout the tutorial.
Terminology | Description |
Messaging Service | Facilitates communication with people. This would be a product like WhatsApp or Facebook. |
Messaging app extension | Collective term for an app that integrates with a messaging service through the Channel API and Provider. |
Channel | Channels facilitate conversations in Pipedrive and are equivalent to an account in Messaging service. |
Provider | A Provider is a middleware/connector that transforms conversations and messages to a format specified by Pipedrive as REST APIs. They also offer webhooks for handling incoming messages. |
Channels API | 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. |
Conversation | A conversation consists of multiple messages with more than one sender. Although there could be scenarios with multiple recipients/senders (like group messages/broadcasts), we will focus only on 1:1 scenarios. |
Message | A message is an individual media (text/image/video) in a conversation. |
Manifest(.json) | The manifest file specifies the endpoints that need to be used by the Pipedrive Messaging Inbox to retrieve and update conversations. |
3. High-level Overview
Messaging app extension uses Pipedrive's Messaging Inbox to communicate with a third-party messaging service. They are like any other Pipedrive Application. They just have an additional OAuth scope and a way to tell Pipedrive how to fetch conversations from an external Messaging Service like WhatsApp.
Not all messaging services build APIs the same way. To interact with different services, Providers are required which offer a standardized interface for communication with Pipedrive. For the sake of simplicity, we will be mocking a provider with the bare minimum data required for setting up a channel. Our Provider will also be able to forward messages from the Messaging Service to Pipedrive & vice-versa.
With our Playground App, we will be able to authenticate with Pipedrive and create a messaging channel (with WhatsApp as our messaging service).
4. Setting up Glitch and integrating with Pipedrive
Make sure you remix the Glitch app to begin. Glitch allows you to build the app from the browser without having to use your local development setup.
Once you have remixed the app, you need to wait for a couple of minutes to let Glitch prepare the environment. You can click on the Logs tab in the bottom footer to see the console logs. If you see a message saying that the 🟢 App has started as indicated by the red arrow in the image below, it means that our Playground app is ready 🙌
Please take note of the Live URL. This will be used in multiple places throughout the tutorial. Open this URL in the browser to access the playground app. The Live URL is in this format:
https://[YOUR_GLITCH_APP_NAME].glitch.me/You should be able to see the playground app's home page like the one below. Please follow these steps to register an OAuth app in Pipedrive. In the Developer Hub, provide the name of the app and paste the callback URL as shown in the first step in the playground.
In the OAuth scopes section, make sure you choose the Messenger Integration scope. We need this scope to access the Channel API and to specify the provider endpoints. You will also notice that an App Manifest section appears like the one below. You can download the manifest.json file from the playground and upload it here.
The manifest.json file specifies the endpoints that need to be used by the Messenger Inbox to retrieve and update conversations. Once everything is provided, hit the Save button in the top corner. This will create a Pipedrive OAuth app with the bare minimum settings for our app.
Now, you need to open the newly created app and copy the Client ID and Secret details. This is important for our Playground app to authorize with Pipedrive. Fill in the .env file in Glitch with these details along with the callback URL and channel ID.
Once the details are filled in, it should look this the image shown above. We will cover the role of the manifest file and provider endpoints in the next step.
5. Manifest file and Provider endpoints
The Messaging inbox interacts with an external Messaging service through the Provider. The Provider is a middleman that makes sure that the conversations, messages, and all the relevant details required by Pipedrive are in the right format. It also facilitates bi-directional communication. Some messaging services like WhatsApp have well-known providers like Twilio. In certain cases, you can write your own provider endpoints if the Messaging Service APIs have a different format.
In the context of the Pipedrive Messaging Inbox, a provider offers a set of endpoints complying with the specification. These endpoints are listed in the manifest file as specified in the documentation. The Playground app generates mock responses for these endpoints.
You can find the logic in the api/provider/mock_response_generator.js file. We are using the Faker library to generate fake usernames and avatars. In a real-world scenario, you need to serve conversations from a table complying with the specification.
The pagination is cursor-based. If there are no further messages in a conversation, next_messages_cursor should return null. You can also monitor the interactions with the provider endpoints by looking at the Logs section. For a detailed overview of the lifecycle, please refer to our documentation.
Until now, we have created a Pipedrive app and configured the .env file in the Glitch app. We have also understood the rationale behind the manifest file and the provider endpoints. In the next section, we will see how to configure WhatsApp Cloud API to interact with our app.
6. Configuring WhatsApp Cloud API
The WhatsApp Business Platform provides a Cloud API that allows us to integrate with WhatsApp seamlessly. It also requires no major infrastructure setup on our side. It supports up to 80 messages / second and is a good choice for getting started. You can find more details about rate limits and pricing in their documentation.
The Cloud API is part of Meta's Graph API and thus you need to perform the following steps:
You also need to follow the additional steps mentioned in their ‘Set up Developer Assets and Platform Access' section.
Once the steps are complete, you should be able to see the following after clicking the WhatsApp > Getting Started section (indicated by the red arrow). You need to copy the temporary access token (blue arrow) and the phone number ID (pink arrow) as they will be required by our app.
Copy and paste these details into the .env file of our Glitch app. Once you have added those, the .env file would look like this
Now that we have configured the WhatsApp Cloud API, it's time for us to test things out from the playground app.
7. Creating our first Messaging Channel
Once you have provided all the relevant details in the .env file, you can authenticate with Pipedrive. With the access token, you will be able to use it to create a new Channel.
You can modify some of the Channel details in the form that is shown in the Playground app. It is prefilled by default for ease. Upon clicking the Create Channel button, we will create a new channel using the Channels REST API.
As you can see from the table above, you will notice that the new channel has been successfully created. You can also access the Messaging Inbox at this time to access the channel.
8. Messaging service-specific logic and webhook subscriptions
WhatsApp Business Platform provides a test number that can be used to try out the Cloud APIs. You should also whitelist the ‘To' numbers for testing purposes.
Note that the whitelisting restriction doesn't apply to production accounts should you choose to make it live in the future.
The ‘From' number is a number allocated by WhatsApp that will act as a business account and the ‘To' number is going to be our test customer. You should also note that there are a few other restrictions to combat spam and these could vary depending on the Messaging Service. In the case of WhatsApp,
- You are required to obtain user opt-in before sending proactive business-initiated messages.
- To send more business-initiated messages, you need to use message templates. These message templates will be approved by WhatsApp.
- Businesses can send free-form messages within this 24-hour window. After which, only templated messages can be sent.
You also need to subscribe to WhatsApp webhook for incoming messages. Copy the provider hook URL in our playground app and paste it into the appropriate section shown in the screenshot below
You also need to subscribe to the ‘messages' event in order to receive notifications when messages are sent by our test customer to the WhatsApp business account number.
Since our playground has logging enabled, you will notice when our hook endpoint is accessed like so:
Now that we have configured everything, let's start testing it out.
9. Receiving messages from WhatsApp
To test this, try to send a WhatsApp message to the business account from one of the approved test customer numbers. To understand the interactions, the WhatsApp business account is referred to as ‘Pipedriver', and the test customer, ‘WhatsApper'.
We will focus on the user-initiated message in this tutorial where a WhatsApper sends a message to Pipedriver. Here's a high-level overview of how a WhatsApp message reaches Pipedrive Messenger Inbox.
Upon receiving a message from WhatsApp, the provider hook URL is triggered by WhatsApp with the message details. This is the same URL that we registered in the WhatsApp App webhooks section. The following logic at webhooks/whatsapp_handler.js is responsible for handling the incoming messages from WhatsApp. A call is made using Channel API to post a message in the corresponding channel.
Upon a successful receive, you will see the message in Pipedrive Messaging inbox. Since we are faking the sender data in our provider endpoints, you'll notice a random name assigned to the conversation.
You will also find important details in the Logs section of your Glitch app. This could be very handy to troubleshoot and debug if something goes wrong.
This is how it should look like when you first receive a message from WhatsApp
We are not forwarding file attachments to Pipedrive with our Playground app. However, a dummy message will be sent if a file/video is being sent from WhatsApp with the content type details.
10. Sending messages from Pipedrive Messaging Inbox
You can reply to WhatsApp conversations directly from the Messaging Inbox. Pipedrive will trigger the postMessage endpoint specified in the provider manifest file with the corresponding payload. You can refer to the complete lifecycle diagram to have an overview of receiving a message from a third-party messaging service (like WhatsApp) from the documentation.
This endpoint is invoked when a user types a message in the chat window and sends it. You can refer to the documentation to understand the payload structure and path parameters.
Note that the content type for incoming messages from Pipedrive will be multipart/form-data. For that reason, we have used the multer package. Although we don't handle file attachments in this demo, you might have to handle that as part of your live app depending on the use case.
Upon parsing the required fields, we forward the message to WhatsApp using the sendMessageToWA() function. This function makes use of WhatsApp API's messages endpoint to deliver the message.
In the images below, a message is being sent by a Pipedriver which is then forwarded to the WhatsApper via our Playground App - in that order.
|
|
Now that we have successfully covered an end-to-end flow including the troubleshooting part, we would encourage you to experiment with the Messaging app extension Playground App and share your thoughts with us on Developer Community.
11. Over to you 🎤
What we have covered so far allows us to do the following:
- Authentication with Pipedrive and fetching
access_tokens - Configuring Pipedrive app with the right scope and provider endpoint details
- Spinning up a mock server for provider and using WhatsApp Cloud API for interaction
- Using it to send bidirectional messages
From here, the possibilities are endless depending on what the business wants to achieve. For instance, in the following steps,
- You can obtain persist the conversations and enable APIs on top of that instead of mock data
- Experiment with other types of message templates offered by WhatsApp. Making use of rich content
- Try multi-channel messaging with different messaging services
Hope you enjoyed the tutorial. We are looking forward to hearing from you!