# HubSpot

Connect HubSpot so the assistant recognises callers by phone, creates contacts and deals, and logs every call as a note

> Full REST + WebSocket API reference: https://api.happ.tools/reference

HubSpot connects with a Service Key that you create in your HubSpot account. Once it's linked, the assistant greets known customers by name with their latest deal in hand, creates a contact and a deal when someone leaves a request, and writes the outcome of every call to the customer's record.

## What the assistant can do [#what-the-assistant-can-do]

* **Recognise the caller** — at the start of a call it looks the phone number up in HubSpot and gets the contact's name, email, company and their latest deal (name, stage, amount).
* **Create a deal** — finds the contact by phone or creates a new one, then creates a deal in the pipeline and stage you choose. The request, delivery address, products and the ad that brought the customer go into the deal as a note.
* **Log calls** — after each call it adds a note to the contact and their deal: direction, duration, outcome, summary, the recording link and, if you want, the full transcript.

## Before you start [#before-you-start]

* **HubSpot account** where you can manage keys (Super Admin, or a user allowed to create keys).
* **HAPP workspace** with at least one assistant.
* **HubSpot enabled for your workspace** — the integration is switched on per company. Ask HAPP support to enable it.

## Create a Service Key [#create-a-service-key]

1. In HubSpot open **Development > Keys > Service keys** and click **Create service key**.
2. Name it `HAPP` and add the scopes:
   * `crm.objects.contacts.read`, `crm.objects.contacts.write`
   * `crm.objects.deals.read`, `crm.objects.deals.write`
   * `crm.objects.owners.read`
3. Create the key and copy it.

An existing private app token (**Settings > Integrations > Private apps**) with the same scopes works too. HubSpot stops creating new private apps in October 2026, so use a Service Key for new connections.

## Connect [#connect]

1. In HAPP open **Integrations** and find HubSpot under **Add a CRM**.
2. Click **Connect**, paste the key and confirm.
3. HubSpot appears under **My integrations** as "HubSpot \<account ID>".

## Settings [#settings]

Open the card's gear icon on the assistant's **Integrations** tab.

* **Search** — recognise the caller by phone.
* **Create** — deals. Pick the **pipeline**, **stage** and **owner**; without them the deal goes to your first pipeline, first stage.
* **Call notes** — a note after every call. **Full transcript** adds the conversation text.

## Limits [#limits]

* HubSpot stores phone numbers as typed; the assistant matches on the last 9 digits, so `050 111 22 33` and `+380501112233` are the same customer.
* A number that isn't in HubSpot gets no call note — there is no record to attach it to.
* If the customer's email already belongs to another contact, the deal is attached to that contact.

## Troubleshooting [#troubleshooting]

| Problem                          | Cause                                    | Fix                                                                   |
| -------------------------------- | ---------------------------------------- | --------------------------------------------------------------------- |
| "HubSpot rejected the token"     | The key was deleted, rotated or mistyped | Create a new key and click **Connect** again.                         |
| "HubSpot token lacks scopes: …"  | The key misses one of the scopes above   | Add the listed scopes to the key (or create a new one) and reconnect. |
| "HubSpot API rate limit reached" | Too many requests at once                | Nothing to do — the next request goes through.                        |
| Pipelines list is empty          | No deal pipeline with stages in HubSpot  | Create a deal pipeline in HubSpot.                                    |

## Disconnect [#disconnect]

Disconnect the card in HAPP and delete the key in **Development > Keys > Service keys**. Contacts, deals and notes already in HubSpot stay.

## Next [#next]

* [CRM](/docs/integrations/crm) — all CRM integrations
* [Tools](/docs/agents/tools) — what the assistant calls during conversations