API Hedy

Настройки доступа к API с адресами конечных точек и созданием ключа API

Что такое API Hedy?

API Hedy даёт программный доступ к данным ваших встреч, транскриптам, резюме и ИИ-выводам. Строите ли вы собственные интеграции, автоматизируете рабочие процессы или подключаетесь к таким инструментам, как Zapier, API позволяет расширить возможности Hedy за пределы приложения. Все функции API требуют подписки Pro с включённой облачной синхронизацией. Если вы хотите, чтобы ИИ-ассистент работал с этими данными в диалоге, а не писать код, можно также подключить Hedy к ИИ-ассистентам через MCP.

Начало работы с API

Откройте «Настройки» и перейдите на вкладку «Автоматизация и данные»
Прокрутите до раздела «Доступ к API»
Нажмите «Создать новый ключ API» (нужна подписка Pro)
Скопируйте ключ API и сохраните его в надёжном месте: увидеть его снова будет нельзя
Подробную информацию о конечных точках смотрите в нашей документации API на SwaggerHub или получите исходную спецификацию OpenAPI по адресу https://api.hedy.bot/docs

Примечание по безопасности: ключ API даёт полный доступ к вашим данным Hedy. Храните его в безопасности, никогда не публикуйте и не добавляйте в систему контроля версий.

Адреса конечных точек по регионам

API Hedy работает в двух регионах, чтобы данные пользователей оставались в нужной юрисдикции. Используйте базовый URL, соответствующий региону, в котором создан ваш аккаунт:

Аккаунты в США: https://api.hedy.bot
Аккаунты в ЕС: https://eu-api.hedy.bot

Оба региона работают на одном и том же коде и предоставляют одни и те же конечные точки, так что разницы в функциях нет. Ключ API привязан к региону вашего аккаунта, поэтому вызовы к неверному базовому URL не пройдут аутентификацию. Если вы не уверены, какой регион у вашего аккаунта, откройте Hedy и перейдите в «Настройки» → «Конфиденциальность и система» → «Настройки конфиденциальности»; значок флага показывает, где хранятся ваши данные.

В примерах этой статьи используется https://api.hedy.bot. Если ваш аккаунт в ЕС, везде заменяйте его на https://eu-api.hedy.bot.

Возможности API

API Hedy предоставляет полный доступ к аналитике ваших встреч:

Сессии: список и получение ваших сессий, включая полные транскрипты, ИИ-резюме и ключевые моменты
Основные моменты: получение важных эпизодов ваших встреч с ИИ-выводами
Темы: создание, обновление, удаление и упорядочивание сессий по темам с пользовательскими инструкциями контекста
Задачи: получение и управление задачами по всем сессиям
Контексты сессий: создание и управление многоразовыми инструкциями, которые определяют, как Hedy анализирует ваши встречи
Пользовательский словарь: чтение и замена списка слов аккаунта, который улучшает распознавание имён и технических терминов
Веб-хуки: настройка и управление конечными точками веб-хуков через API для уведомлений о событиях в реальном времени
Сведения о пользователе: получение данных вашего аккаунта через конечную точку /me

API работает с сессиями, когда они уже существуют. Он не может запускать или останавливать сессию в реальном времени, потому что это происходит в приложении Hedy на вашем устройстве. Чтобы запустить или завершить сессию из скрипта или другого приложения на том же устройстве, см. Запуск сессий из других приложений.

Аутентификация

Все запросы к API требуют аутентификации по ключу API. Передавайте его в заголовке Authorization:

Authorization: Bearer YOUR_API_KEY

Веб-хуки

Настройте веб-хуки, чтобы получать уведомления в реальном времени о событиях в вашем аккаунте Hedy:

В разделе «Доступ к API» нажмите «Управление веб-хуками»
Нажмите кнопку +, чтобы добавить новый веб-хук
Введите URL вашей конечной точки HTTPS
Выберите события, которые хотите получать:
- session.created - когда начинается новая сессия
- session.ended - когда сессия завершает обработку
- session.exported - когда пользователь вручную экспортирует сессию
- highlight.created - когда добавляется новый основной момент
- todo.exported - когда задачи экспортируются из сессии
- suggestion.created - когда Hedy показывает автоматическую подсказку во время сессии
Сохраните веб-хук и сохраните секретный ключ подписи для проверки данных

Веб-хуками можно также управлять программно через API с помощью GET, POST и DELETE для конечной точки /webhooks. В каждом аккаунте может быть до 50 веб-хуков.

Проверка подписи веб-хука

Каждая доставка веб-хука содержит подпись в заголовке X-Hedy-Signature, чтобы вы могли убедиться, что она пришла от Hedy. Подпись — это хеш HMAC-SHA256 исходного тела запроса, подписанный секретным ключом вашего веб-хука. Проверяйте подпись на своём сервере, прежде чем обрабатывать данные, чтобы убедиться в подлинности. В каждой доставке также есть заголовок X-Hedy-Event с типом события (например, session.ended).

Контексты сессий

Контексты сессий позволяют создавать многоразовые наборы пользовательских инструкций, которые говорят Hedy, как анализировать ваши встречи. Например, можно создать контекст «Продажи» с упором на задачи и возражения клиентов или «Планёрки» с отслеживанием блокеров и обновлений.

Управлять контекстами сессий можно через API:

GET /contexts - список всех ваших контекстов сессий
GET /contexts/{id} - получить конкретный контекст по ID
POST /contexts - создать новый контекст (название и содержимое)
PATCH /contexts/{id} - обновить существующий контекст
DELETE /contexts/{id} - удалить контекст

Если сделать контекст используемым по умолчанию, он будет автоматически применяться ко всем новым сессиям. Бесплатные аккаунты ограничены одним контекстом сессии.

Управление темами через API

Темы помогают раскладывать сессии по категориям. API поддерживает полное управление темами:

GET /topics - список всех тем с ИИ-выводами и количеством сессий
GET /topics/{id} - получить сведения о конкретной теме
POST /topics - создать новую тему с названием, описанием, цветом, значком и типом сессии по умолчанию
PATCH /topics/{id} - обновить свойства темы, пользовательский контекст или тип сессии по умолчанию
DELETE /topics/{id} - удалить тему (сессии отвязываются, а не удаляются)
GET /topics/{id}/sessions - список всех сессий внутри темы
PATCH /sessions/{id} - перенести сессию в тему с помощью {"topicId": "<topic id>"} или убрать её из темы с помощью {"topicId": null}. topicId — единственное поддерживаемое поле; Hedy обновляет ИИ-обзоры затронутых тем.

Сессию, захваченную при выключенной облачной синхронизации, перенести нельзя (409 session_not_synced); тема назначения должна существовать и не должна находиться в процессе удаления.

В темах может быть поле topicContext с пользовательскими инструкциями (до 20 000 символов), которые определяют, как Hedy анализирует сессии, привязанные к теме. Эти инструкции автоматически прикрепляются к любой сессии, начатой в рамках темы, включая подсказки в реальном времени, поэтому подготовки темы через API достаточно, чтобы подготовить сессию.

Темы также принимают поле dominantSessionType, которое задаёт тип сеанса, используемый для сессии, начатой в рамках этой темы. Это удобно, когда вы создаёте темы программно и не хотите, чтобы каждая из них возвращалась к типу по умолчанию. Это поле одновременно служит производной статистикой: когда в теме появляются сессии, Hedy пересчитывает его по тем типам, которые вы реально использовали, поэтому записанное вами значение служит отправной точкой, а не постоянной настройкой. Если задать его для темы, в которой уже есть сессии, оно работает как разовое переопределение для следующей сессии. Допустимые значения типов сеансов перечислены в справочнике API.

Пользовательский словарь

Пользовательский словарь учит Hedy именам, аббревиатурам и техническим терминам вашей работы, что повышает точность их распознавания. Список хранится в вашем аккаунте и применяется ко всем сессиям.

GET /vocabulary - получить текущий список терминов и включён ли словарь
PUT /vocabulary - заменить весь список терминов

PUT заменяет весь список целиком, а не дополняет его, поэтому любой сохранённый термин, который вы не включили, будет удалён. Отправляйте до 100 терминов длиной от 2 до 50 символов. Термины должны быть уникальными (регистр при сравнении не учитывается) и не могут содержать угловые, фигурные и квадратные скобки, обратные косые черты, вертикальные черты, обратные кавычки и тильды.

Флаг enabled можно и читать, и записывать. Если опустить его при замене терминов, сохранённое значение остаётся прежним. Это важно, если вы автоматизируете обновление словаря: прочитав флаг заранее, вы узнаете, будут ли записанные вами термины реально использоваться, а не лежать в аккаунте, где словарь выключен.

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

Типичные сценарии использования

Интеграция с управлением проектами: автоматически создавайте задачи в вашем инструменте управления проектами из задач встреч
Управление знаниями: индексируйте содержание встреч в базе знаний вашей компании
Интеграция с CRM: обновляйте карточки клиентов выводами со встреч
Аналитические панели: стройте собственные отчёты о том, как проходят встречи и какова продуктивность
Автоматизация рабочих процессов: запускайте действия по содержанию или завершению встречи
Интеграция с Zapier: подключайте Hedy к тысячам приложений через Zapier (добавьте ?format=zapier к конечным точкам, чтобы получать плоские массивы, совместимые с Zapier)

Ограничения API и рекомендации

Ограничения частоты запросов: 200 запросов в минуту на один ключ API
Постраничная выдача: используйте параметр limit (по умолчанию 50, максимум 100) и параметр курсора after для перехода по результатам
Кэшируйте ответы, где возможно, чтобы сократить число вызовов API
Корректно обрабатывайте ошибки с экспоненциальной задержкой между повторами
Используйте веб-хуки для обновлений в реальном времени вместо опроса

Автоматический экспорт задач

Включите автоматический экспорт задач, чтобы отправлять задачи в подключённые системы:

В разделе «Доступ к API» включите «Автоматический экспорт задач»
Задачи будут автоматически отправляться на настроенные конечные точки веб-хуков
Каждая задача содержит контекст, предлагаемых исполнителей и ссылку на встречу

Примеры кода

Вот простой пример получения ваших последних сессий:

curl -X GET "https://api.hedy.bot/sessions?limit=10" \  -H "Authorization: Bearer YOUR_API_KEY"

Другие примеры и полный справочник конечных точек смотрите в нашей документации API.

Решение проблем

Ошибка 401 Unauthorized

Проверьте, что ключ API верен и правильно оформлен
Убедитесь, что у вас активна подписка Pro
Проверьте, что облачная синхронизация включена в вашем аккаунте
Убедитесь, что ключ API не был создан заново (старые ключи перестают действовать)

Пустой ответ или отсутствующие данные

Убедитесь, что облачная синхронизация включена: API работает только с данными, синхронизированными с облаком
Подождите несколько минут после сессии, чтобы данные синхронизировались
Проверьте фильтры по датам и параметры постраничной выдачи
Убедитесь, что вы используете правильную конечную точку для нужного типа данных

Веб-хук не получает события

Убедитесь, что URL вашей конечной точки использует HTTPS (это обязательно)
Проверьте, что ваш сервер отвечает статусом 200 OK
Проверяйте заголовок X-Hedy-Signature, если реализуете проверку подписи
Протестируйте веб-хук кнопкой «Протестировать веб-хук»
Проверьте, что правила брандмауэра не блокируют серверы Hedy

Превышен лимит запросов

Внедрите кэширование, чтобы сократить лишние вызовы API
Используйте веб-хуки для обновлений в реальном времени вместо опроса
По возможности объединяйте операции в пакеты
Если нужны более высокие лимиты, свяжитесь с поддержкой

Совет: используйте веб-хуки вместо опроса для обновлений в реальном времени. Это эффективнее и даёт мгновенные уведомления при изменении ваших данных.

Конфиденциальность и безопасность

Безопасность ваших данных — наш приоритет:

Весь обмен данными с API идёт по шифрованному соединению HTTPS
Ключи API можно создать заново в любой момент (старый ключ при этом перестаёт действовать)
Данные веб-хуков подписываются с помощью HMAC-SHA256 для проверки
Доступ к данным возможен только при действительной аутентификации
Все конечные точки применяют строгие заголовки безопасности

Помощь

Если у вас есть вопросы по API:

Изучите документацию API, где описаны конечные точки и схемы
Прочитайте нашу статью с анонсом API с примерами и сценариями использования