# HubSpot

Подключите HubSpot, чтобы агент узнавал звонящих по телефону, создавал контакты и сделки и записывал каждый звонок заметкой

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

HubSpot подключается с помощью Service Key, который вы создаёте в своём аккаунте HubSpot. После подключения агент обращается к знакомым клиентам по имени, зная их последнюю сделку, создаёт контакт и сделку, когда клиент оставляет заявку, и записывает итог каждого звонка в карточку клиента.

## Что умеет агент [#what-the-assistant-can-do]

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

## Перед началом [#before-you-start]

* **Аккаунт HubSpot**, в котором вы можете управлять ключами (Super Admin или пользователь с правом создавать ключи).
* **Воркспейс HAPP** хотя бы с одним агентом.
* **HubSpot включён для вашего воркспейса** — интеграция включается для каждой компании отдельно. Попросите поддержку HAPP её включить.

## Создание Service Key [#create-a-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.

## Подключение [#connect]

1. В HAPP откройте **Интеграции** и найдите HubSpot в разделе **Добавить CRM**.
2. Нажмите **Подключить**, вставьте ключ и подтвердите.
3. HubSpot появится в разделе **Мои интеграции** как «HubSpot \<ID аккаунта>».

## Настройки [#settings]

Нажмите на шестерёнку на карточке во вкладке **Интеграции** агента.

* **Поиск** — узнавать звонящего по телефону.
* **Создание** — сделки. Выберите **воронку**, **этап** и **ответственного**; без них сделка попадёт в первую воронку на первый этап.
* **Заметки о звонках** — заметка после каждого звонка. **Полная расшифровка** добавляет текст разговора.

## Ограничения [#limits]

* HubSpot хранит телефон так, как его ввели; агент сравнивает последние 9 цифр, поэтому `050 111 22 33` и `+380501112233` — один и тот же клиент.
* Для номера, которого нет в HubSpot, заметка о звонке не создаётся — её не к чему привязать.
* Если email клиента уже принадлежит другому контакту, сделка привязывается к этому контакту.

## Решение проблем [#troubleshooting]

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

## Отключение [#disconnect]

Отключите карточку в HAPP и удалите ключ в **Development > Keys > Service keys**. Контакты, сделки и заметки, которые уже есть в HubSpot, останутся.

## Дальше [#next]

* [CRM](/docs/integrations/crm) — все CRM-интеграции
* [Инструменты](/docs/agents/tools) — что агент вызывает во время разговора