Last Updated on July 27, 2023 by David
For profit, or just for fun!
At Re:amaze we are invested in helping companies to have quality support conversations with their customers, and support conversations naturally cover a broad spectrum of topics, from returns and billing questions to product questions or service inquiries. The latter type of support conversation is very lucrative for businesses because they represent an opportunity to convert a new visitor into a paying customer or client.
Customers walking in the front door with the right questions will naturally warrant tracking in your sales pipeline. Thus it was a no brainer for Re:amaze to partner up with Pipedrive to handle these cases.
What we found to be the best part is, because of Pipedrive’s mature API and Marketplace, anyone can build a meaningful integration in a matter of hours or days — not weeks or months.
We enjoyed our integration process with our partners at Pipedrive so much, that we thought it would make sense to share our experience and highlight just how easy it can be to build your own app integration with Pipedrive. You can have a working prototype built in a matter of hours and a Marketplace app shipped in just a few days, opening the door to a rich and high quality install base.
We wanted to share some of the pieces we thought were important to get an integration built.
OAuth Integration
Pipedrive has a vibrant and high quality Marketplace with a large install base to tap into. Thus, integration naturally involves registering as an App, which provides the IDs and tokens necessary to build out OAuth.
By now, if you’ve dealt with any web-based integrations, you’ll be familiar with OAuth. If not, have no fear: there are dozens of high quality libraries for OAuth for just about every major web development language and framework. In Pipedrive’s case, the OAuth flow follows industry best-practices so by utilizing the right libraries and common patterns, it’s easy enough to have a working OAuth flow built in minutes.
In our case, our app integrations are built in Ruby so we utilized the popular OAuth2 gem (https://github.com/oauth-xx/oauth2) to build out our flow.
For example, in Ruby, starting the OAuth flow is as easy as the code below:
oauth_client = OAuth2::Client.new(
pipedrive_client_id, # your app ID value here
pipedrive_client_secret, # your secret value here
site: ‘https://oauth.pipedrive.com/',
authorize_url: ‘/oauth/authorize’,
token_url: ‘/oauth/token’,
redirect_uri: redirect_uri # application specific
)
redirect_to oauth_client.auth_code.authorize_url(response_type: “code”)
Storing Tokens
Once the OAuth flow kicks you back, you’ll need to store the token. One particular thing to look out for is that OAuth tokens can expire and will need to be periodically refreshed.
In our case, our code looks something like this:
# code from the return value via OAuth
# basic_auth should be generated based on Pipedrive documentation
response = oauth_client.auth_code.get_token(code, {
headers: { “Authorization” => basic_auth }
})
# response.token now has your OAuth token!
The token grabbed from OAuth should be saved in your database, but you’ll also want to save the refresh_token and expires_in values that live next to it in the OAuth response.
Later on, when you make REST requests, you’ll want to check on the expiration and validity of your token and refresh it as needed and described in the Pipedrive OAuth docs.
SaaS Considerations
If you’re implementing OAuth, one of the most important considerations is whether or not the incoming Pipedrive integration is representative of a new user or an existing user that you might already know.
The four possibilities you may want to consider are as follows:
- The user is installing your app and doesn’t have an account. Thus, a new account needs to be created.
- The user is installing your app and already has an account. However, they’re logged out and need to identify their account under your app.
- The user is installing your app and already has an account and is already logged in.
- The user is re-installing your app and may or may not be logged in, but you’ve already connected their Pipedrive account to an account within your app.
In our case set the redirect_uri value for the OAuth flow to an endpoint where the above cases are detected and handled. If you’re using an MVC style web framework, we recommend this to be done in a controller.
REST API
Once the OAuth flow is in place, you now have API access to Pipedrive’s RESTful API. The API gives almost full access to all of the underlying Pipedrive models so there’s an open canvas for just about any integration.
For Re:amaze, since we focus on customers, it was natural for us to work heavily on the Persons, Organizations, Deals, and Activities endpoints. This allows Re:amaze to map incoming customer conversations identified with an email address to a Pipedrive Person and their associated Deals and Activities.
Every app is different, so there are dozens of other models to work with, from Roles to Notes, MailMessages and more.
Each endpoint follows REST conventions (GET, PUT, POST, DELETE) and can be easily tested directly from the documentation page. Because of this, it’s very easy to start retrieving data with a sandbox developer account to poke at the endpoints and build out your code.
If you’re working with Node JS, you may also find Pipedrive’s own API client to be helpful in getting results ASAP.
Going Live
With the OAuth flow in place and the RESTful API shipping data back and forth between your app and Pipedrive, you should have a meaningful integration built in a very short amount of time.
The next step is simple: Launch it! We found the review and approval process smooth and simple.
Once your new app is launched, you’ll be able to tap into the Pipedrive Marketplace and potentially new customers looking for ways to enhance their workflows in new ways.
Learning More
If you’re interested in trying our Re:amaze for your business, be sure to check us out at here where you can enjoy an extended 30-day free trial! Reach out to our support team if you have any questions about features, pricing, or other product related issues.