Интеграция с HubSpot CRM

Введение

Интеграция с HubSpot CRM

3CX предлагает интеграцию с HubSpot через 3CX CRM API. Интеграция реализует следующие возможности:

  • Поиск контакта по Caller ID - входящий звонок инициирует поиск контакта в HubSpot.
  • Поиск контактов в HubSpot по имени, номеру или e-mail, когда пользователь 3CX ищет контакт в веб-клиенте.
  • Журнал вызовов и чатов - вызовы и чаты регистрируются в карточке контакта HubSpot как история взаимодействия с клиентом.
  • Создание нового контакта HubSpot из клиента 3CX, когда вызов поступил с Caller ID, которого нет в базе данных.
  • Click to Call - звонки из HubSpot через 3CX с помощью браузерного расширения 3CX Click2Call для Google Chrome и Microsoft Edge.

Настройка HubSpot CRM с помощью HubSpot CLI

HubSpot прекратил создание новых устаревших публичных приложений (legacy Public Apps) через интерфейс Developer Platform. Новые приложения HubSpot теперь должны создаваться с использованием платформы HubSpot Projects и интерфейса командной строки HubSpot CLI.

В этом руководстве объясняется, как создать приложение HubSpot OAuth, необходимое для интеграции 3CX с HubSpot CRM.

Примечание: Существующие устаревшие публичные приложения (legacy Public Apps) продолжают работать.

Шаг 1: Определите URL-адрес перенаправления (Redirect URL) 3CX OAuth

Перед созданием проекта в HubSpot определите публичный URL-адрес, используемый для доступа к системе 3CX.

Например, если доступ к консоли администратора 3CX осуществляется по адресу:

https://mypbx.3cx-example.com

...тогда URL-адрес перенаправления HubSpot OAuth должен быть:

https://mypbx.3cx-example.com/api/oauth2crm

Шаг 2: Установите HubSpot CLI

HubSpot CLI — это приложение Node.js, поэтому сначала необходимо установить Node.js с npm.

Для HubSpot CLI 8 требуется Node.js 20 или новее.

  • Откройте новую командную строку (Command Prompt).
  • В командной строке выполните:

npm install -g @hubspot/cli@latest

  • По завершении установки проверьте версию HubSpot CLI:

hs --version

  • Должна отобразиться версия HubSpot CLI.

Шаг 3: Войдите в HubSpot через CLI

  • В командной строке выполните:

hs account auth

CLI поможет вам пройти аутентификацию в вашей учетной записи HubSpot. Следуйте подсказкам:

  • Дайте учетной записи HubSpot узнаваемое локальное имя, если это будет предложено.
  • Откроется окно браузера, или CLI отобразит инструкции по открытию HubSpot.
  • Войдите в учетную запись HubSpot, в которой будет создаваться проект/приложение.

  • Сгенерируйте запрошенный персональный ключ доступа (Personal Access Key).
  • Ключ должен быть автоматически возвращен в окно терминала.
  • Если CLI попросит вас вставить персональный ключ доступа в терминал, вставьте его и нажмите Enter.
  • Введите имя учетной записи при появлении соответствующего запроса.
  • Если вас спросят, должна ли эта учетная запись использоваться по умолчанию, выберите Yes (Да).

Шаг 4: Создайте проект HubSpot OAuth

  • В командной строке
  • Создайте папку проекта, например:

mkdir C:\HubSpotProjects

cd /d C:\HubSpotProjects

  • В этой папке выполните:

hs project create --project-base app --distribution private --auth oauth

  • CLI запросит дополнительную информацию.

  • Имя проекта, например: "3CX HubSpot Integration"
  • Локальная папка, оставьте по умолчанию или используйте что-то простое, например: "3cx-hubspot"
  • Функции (Features)
  • Сама интеграция с 3CX CRM не требует карточки приложения HubSpot (App Card), вебхука, действия рабочего процесса, страницы настроек или других функций проекта. Если CLI предложит выбрать функции, оставьте все функции не выбранными и продолжите, нажав Enter.

  • После завершения выполнения команды должна появиться новая директория, например:
    "C:\HubSpotProjects\3cx-hubspot"
  • Перейдите в эту директорию:

cd /d C:\HubSpotProjects\3cx-hubspot

  • Среди важных файлов должны быть:

C:\HubSpotProjects\3cx-hubspot\hsproject.json

C:\HubSpotProjects\3cx-hubspot\src\app\app-hsmeta.json

Шаг 5: Настройте OAuth и необходимые области видимости (scopes) для 3CX

Откройте следующий файл в Блокноте (Notepad): "C:\HubSpotProjects\3cx-hubspot\src\app\app-hsmeta.json".

Сгенерированный файл может содержать дополнительные свойства, которые можно проигнорировать; важным разделом является конфигурация приложения (config) и, в частности, раздел auth.

Настройте приложение с вашим distribution, requiredScopes и redirectUrls как показано ниже, заменив "https://pbx.example.com/api/oauth2crm" на фактический публичный URL-адрес 3CX, определенный на Шаге 1.

{

  "uid": "3CXHubSpotIntegration_app",

  "type": "app",

  "config": {

    "description": "OAuth application for the 3CX HubSpot CRM integration",

    "name": "3CX HubSpot Integration-App",

    "distribution": "private",

    "auth": {

      "type": "oauth",

      "redirectUrls": [

        "https://pbx.example.com/api/oauth2crm"

      ],

      "requiredScopes": [

      "oath",

           "crm.objects.contacts.read",

                "crm.objects.contacts.write",

                "crm.objects.companies.read",

                "crm.objects.owners.read",

                "timeline"

      ],

      "optionalScopes": [],

      "conditionallyRequiredScopes": []

    },

    "permittedUrls": {

      "fetch": [

        "https://api.hubapi.com"

      ],

      "iframe": [],

      "img": []

    },

    "support": {

      "supportEmail": "[email protected]",

      "documentationUrl": "https://example.com/docs",

      "supportUrl": "https://example.com/support",

      "supportPhone": "+18005555555"

    }

  }

}

Шаг 6: Проверьте и загрузите проект в HubSpot

  • Из директории проекта выполните:

hs project validate

  • Если проверка прошла успешно, продолжайте.
  • Если проверка сообщает об ошибке, исправьте указанное свойство JSON и снова выполните команду.
  • Затем выполните:

hs project upload

  • При первой загрузке проекта HubSpot может отобразить сообщение, похожее на:

  • “The project does not exist in this account. Would you like to create it?" (Проект не существует в этой учетной записи. Хотите ли вы его создать?)
  • Ответьте "Y" и продолжите.
  • CLI выполнит следующие действия:
  • загрузит файлы
  • создаст сборку (build) HubSpot
  • развернет приложение

Шаг 7: Получите Client ID и Client Secret в HubSpot

  • В браузере войдите в HubSpot и перейдите в Development > Projects.
  • Откройте 3CX HubSpot Integration (или имя проекта, которое вы создали).
  • В разделе Project Components выберите имя приложения.
  • Откройте вкладку Auth.

  • HubSpot отобразит следующие учетные данные клиента (Client credentials):
  • Client ID
  • Client secret
  • Скопируйте оба значения в надежное место.

Шаг 8: Добавьте дополнительные учетные записи HubSpot CRM в приватное приложение OAuth (Опционально)

Это важный новый шаг по сравнению со старой процедурой использования публичных приложений (Public App).

Поскольку проект был создан с параметром "distribution": "private", HubSpot разрешает авторизацию OAuth только для тех учетных записей, которые были явно одобрены. По умолчанию доступ имеет только учетная запись, создавшая приложение ("private").

В HubSpot:

  • Откройте Development (Разработка).
  • Откройте Projects (Проекты).
  • Откройте проект 3CX.
  • В разделе Project Components выберите приложение 3CX.

  • Откройте вкладку Distribution.
  • Нажмите Add approved account(s).
  • В разделе доступных рабочих учетных записей выберите учетную запись HubSpot CRM, которая содержит контакты и компании, которые будут интегрированы с 3CX.
  • Если ваш логин в HubSpot имеет доступ как к учетной записи разработчика, так и к обычной учетной записи CRM компании, убедитесь, что одобрена именно учетная запись CRM, содержащая реальные данные клиентов.
  • Нажмите Save changes.

Настройка и авторизация HubSpot в 3CX

  • В консоли администратора 3CX перейдите в раздел "Integrations"  > "CRM"
  • Выберите "HubSpot" из выпадающего списка
  • Выберите желаемый порядок поиска контактов (Contact Lookup Order)
  • Введите ранее скопированные значения OAuth из вашего приложения для полей "Client ID" и "Client Secret"
  • Нажмите Save
  • Нажмите Authorize

  • Должна открыться страница авторизации HubSpot.
  • Войдите в HubSpot, если потребуется.
  • Выберите учетную запись HubSpot CRM, содержащую контакты и компании, которые должны использоваться системой 3CX.
  • Просмотрите запрошенные разрешения.
  • HubSpot может предупредить, что приложение не проверено (unverified). Это нормально для приложения, созданного для вашей собственной учетной записи и не отправленного в HubSpot Marketplace.
  • Подтвердите установку/авторизацию.
  • Теперь 3CX получает код авторизации OAuth и обменивает его на токены HubSpot OAuth.
  • Убедитесь, что поле "Refresh Token" автоматически заполнено для HubSpot CRM в консоли администратора 3CX.
  • Если вы хотите включить создание контактов из клиента 3CX, установите этот флажок. Если номер звонящего не совпадает ни с одним контактом, клиент 3CX позволит пользователю создать контакт, заполнив данные в диалоговом окне.

Настройка контактов в формате E164 и Caller ID

  1. Для успешного поиска совпадений в HubSpot, входящий Caller ID должен быть идентичен записи в CRM, включая любой префикс, так как HubSpot выполняет поиск по всему номеру. Поиск в HubSpot по части номера не вернет никаких данных.
  2. Чтобы интеграция с HubSpot работала, вы должны сохранять номера в HubSpot в формате E164, и ваш SIP-транк также должен предоставлять номер звонящего в формате E164, чтобы оба значения совпадали. В противном случае вы можете использовать переформатирование Caller ID для настройки номера звонящего перед его передачей в CRM.
  3. Теперь перейдите в раздел System > Phonebook > Options, установите стратегию поиска совпадений на "Match exactly" и нажмите "OK".

Настройка журналирования вызовов и чатов, включая транскрипцию

  • Чтобы передавать отчеты о внешних вызовах и чатах в HubSpot, адрес электронной почты, настроенный для добавочного номера 3CX, должен совпадать с адресом электронной почты пользователя HubSpot. Таким образом 3CX может сопоставить добавочный номер 3CX, получающий вызов или чат, с пользователем HubSpot.
  • Установите флажок "Enable Call Journaling", чтобы передавать информацию о внешних вызовах в CRM, и настройте следующие параметры "Call Journaling":
  • Call Subject - тема вызова.
  • Answered Inbound Call - описание для отвеченных входящих вызовов.
  • Missed Call - описание для пропущенных вызовов.
  • Answered Outbound Call - описание для отвеченных исходящих вызовов.
  • Unanswered Outbound Call - описание для неотвеченных исходящих вызовов.
  • Обратите внимание, что вы можете использовать переменные в параметрах "Call Journaling", обозначаемые как
    [variable_name]
    , например, внешний номер указывается как
    [Number]
    . Доступные для использования переменные перечислены     здесь.

  • Если вы хотите передавать информацию о чатах в CRM, установите флажок Enable Chat Journaling и настройте параметры ниже:
  • Chat Subject - тема сессии чата.
  • Обратите внимание, что в параметрах "Chat Journaling" можно использовать переменные, обозначаемые как
    [variable_name]
    . Например, внешний номер указывается как
    [Number]
    . Доступные переменные приведены     здесь.

Дополнительная информация

Версия документа

Последнее обновление документа 21 августа 2026

https://www.3cx.ru/docs/hubspot-pbx-crm-integration/