HubSpot Integration Guide

Last updated on 

This guide will cover how to integrate Cue with your HubSpot account. It covers things like getting a HubSpot API key and managing contacts, tickets and WhatsApp engagements in HubSpot.

Overview

In this guide you'll find the following sections:

Requirements for integration

You'll need the following to complete an integration with HubSpot using this guide:

1. Basic knowledge of working with APIs (e.g. JSON and HTTP)
2. A HubSpot app (for a HubSpot API key)

Create a HubSpot app

If you want Cue to be able to perform actions in your HubSpot account, you will need to create a HubSpot API key that Cue can use when making requests to HubSpot. An API key is like a password that applications use when making requests to other applications.

In order to get an API key in your HubSpot account, you will need to create a HubSpot app to represent this external application that will be making request to your HubSpot account.

How to create a HubSpot app →

App permissions

When you create an app in HubSpot, you will need ensure that it has the required permissions to perform various actions in HubSpot. This allows you to control and limit what the application can do so that you can make sure it only has permission to do the things you want to do and nothing more. You can read more about permissions in the official HubSpot guide above.

Making requests to HubSpot

Chatbot flows in Cue allow you to take people through user journeys (a series of steps) when they send a message to a channel in your workspace. Whenever you want to send data to or retrieve data from your HubSpot account, you can use an HTTP request step to call one of HubSpot various APIs. You can use these HTTP request steps to make requests to HubSpot that will create, find and update HubSpot contacts, tickets, and engagements.

Create, find or update HubSpot contacts

If you want to create find or update contacts in HubSpot from your Cue chatbot flow you can use the HTTP request step in your Cue flow to make a request to any of the following points in HubSpot.

See below for the official documentation from HubSpot on how to make these requests:

HubSpot API docs for contacts
Below are links to guides on how to use HubSpots APIs to create, retrieve and update HubSpot contacts:

Create, find or update HubSpot tickets

If you use HubSpot as your main system of record, you might want to create a ticket in HubSpot that is saved against a HubSpot contact. In this case you would do the following in your Cue flow.

  1. Check if the contact exists in HubSpot, if not created it
  2. Create a ticket in HubSpot and associate the ticket to the contact

HubSpot API docs for tickets
Below are links to guides on how to use HubSpots APIs to create, retrieve and update HubSpot tickets:

Create, find or update HubSpot engagements

HubSpot allows you to create objects called engagements that are stored against contacts in HubSpot. Engagements can be different types of communication like WhatsApp, email or SMS that you may have had with a person. This section covers how to work with engagements in HubSpot.

Note that HubSpot engagements are very simple objects that don't have a lot of fields to store data for the different types of engagements. For example if you create a WHATSAPP type engagement. there are no fields to save the to and from phone numbers of a WhatsApp message instead there is just a basic hs_communication_body for the body text of the engagement.

So when creating a WhatsApp engagement in HubSpot we recommend just creating a single WhatsApp engagement for all messages and using the conversation.plainText property available in flows which will output a plain text formatted version of your entire conversation into the hs_communication_body field. This way you also don't end up creating an engagement for each message which could clutter your view of contact activity in HubSpot.

HubSpot API docs
Below are links to guides on how to use HubSpots APIs to create, retrieve and update HubSpot engagements: