# HubSpot

Підключіть HubSpot, щоб асистент упізнавав клієнтів за телефоном, створював контакти й угоди та записував кожен дзвінок нотаткою

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

HubSpot підключається за допомогою Service Key, який ви створюєте у своєму акаунті HubSpot. Після підключення асистент звертається до знайомих клієнтів на ім'я і знає їхню останню угоду, створює контакт і угоду, коли клієнт залишає заявку, і записує підсумок кожного дзвінка в картку клієнта.

## Що вміє асистент [#що-вміє-асистент]

* **Упізнає клієнта** — на початку дзвінка шукає номер у HubSpot і отримує ім'я, email, компанію та останню угоду контакту (назва, етап, сума).
* **Створює угоду** — знаходить контакт за телефоном або створює новий і створює угоду у вибраній воронці та на вибраному етапі. Запит, адреса доставки, товари та реклама, з якої прийшов клієнт, додаються до угоди нотаткою.
* **Записує дзвінки** — після кожного дзвінка додає нотатку до контакту та його угоди: напрямок, тривалість, результат, резюме, посилання на запис і, за бажанням, повну розшифровку.

## Перед початком [#перед-початком]

* **Акаунт HubSpot**, у якому ви можете керувати ключами (Super Admin або користувач з правом створювати ключі).
* **Робочий простір HAPP** щонайменше з одним асистентом.
* **HubSpot увімкнено для вашого простору** — інтеграція вмикається для кожної компанії окремо. Зверніться до підтримки HAPP.

## Створіть Service Key [#створіть-service-key]

1. У HubSpot відкрийте **Development > Keys > Service keys** і натисніть **Create service key**.
2. Назвіть його `HAPP` і додайте доступи (scopes):
   * `crm.objects.contacts.read`, `crm.objects.contacts.write`
   * `crm.objects.deals.read`, `crm.objects.deals.write`
   * `crm.objects.owners.read`
3. Створіть ключ і скопіюйте його.

Підійде й токен наявного private app (**Settings > Integrations > Private apps**) з тими самими доступами. З жовтня 2026 HubSpot більше не створює нові private apps, тож для нових підключень використовуйте Service Key.

## Підключення [#підключення]

1. У HAPP відкрийте **Інтеграції** і знайдіть HubSpot у розділі **Додати CRM**.
2. Натисніть **Підключити**, вставте ключ і підтвердьте.
3. HubSpot з'явиться в **Моїх інтеграціях** як «HubSpot \<ID акаунта>».

## Налаштування [#налаштування]

Відкрийте шестерню на картці у вкладці **Інтеграції** асистента.

* **Пошук** — упізнавати клієнта за телефоном.
* **Створення** — угоди. Виберіть **воронку**, **етап** і **відповідального**; без них угода потрапить у першу воронку на перший етап.
* **Нотатки про дзвінки** — нотатка після кожного дзвінка. **Повна розшифровка** додає текст розмови.

## Обмеження [#обмеження]

* HubSpot зберігає телефон так, як його ввели; асистент порівнює останні 9 цифр, тож `050 111 22 33` і `+380501112233` — той самий клієнт.
* Для номера, якого немає в HubSpot, нотатка про дзвінок не створюється — її нема до чого прив'язати.
* Якщо email клієнта вже є в іншого контакту, угода прив'язується до того контакту.

## Вирішення проблем [#вирішення-проблем]

| Проблема                         | Причина                                              | Що робити                                                              |
| -------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------- |
| «HubSpot rejected the token»     | Ключ видалили, перевипустили або вставили з помилкою | Створіть новий ключ і натисніть **Підключити** ще раз.                 |
| «HubSpot token lacks scopes: …»  | У ключа немає одного з доступів вище                 | Додайте вказані доступи (або створіть новий ключ) і підключіть заново. |
| «HubSpot API rate limit reached» | Забагато запитів одночасно                           | Нічого робити не треба — наступний запит пройде.                       |
| Список воронок порожній          | У HubSpot немає воронки угод з етапами               | Створіть воронку угод у HubSpot.                                       |

## Відключення [#відключення]

Відключіть картку в HAPP і видаліть ключ у **Development > Keys > Service keys**. Контакти, угоди й нотатки, що вже є в HubSpot, залишаться.

## Далі [#далі]

* [CRM](/docs/integrations/crm) — усі CRM-інтеграції
* [Інструменти](/docs/agents/tools) — що асистент викликає під час розмови