BlueBubbles (iMessage)

Подключите Hermes к Apple iMessage через BlueBubbles — бесплатный сервер с открытым исходным кодом для macOS, который соединяет iMessage с любым устройством.

Предварительные требования

• Mac (постоянно включённый) с запущенным BlueBubbles Server

• Apple ID, выполнивший вход в Messages.app на этом Mac

• BlueBubbles Server v1.0.0+ (вебхуки требуют этой версии)

• Сетевая доступность между Hermes и сервером BlueBubbles

Настройка

1. Установка BlueBubbles Server

Скачайте и установите с bluebubbles.app. Пройдите мастер настройки — войдите с вашим Apple ID и настройте способ подключения (локальная сеть, Ngrok, Cloudflare или Dynamic DNS).

2. Получение URL и пароля сервера

В BlueBubbles Server → Settings → API, запишите:

• Server URL (например, http://192.168.1.10:1234)

• Server Password

3. Настройка Hermes

Запустите мастер настройки:

hermes gateway setup

Выберите BlueBubbles (iMessage) и введите URL сервера и пароль.

Или укажите переменные окружения напрямую в ~/.hermes/.env:

BLUEBUBBLES_SERVER_URL=http://192.168.1.10:1234
BLUEBUBBLES_PASSWORD=your-server-password

4. Авторизация пользователей

Выберите один из способов:

Сопряжение через DM (рекомендуется): Когда кто-то пишет вам в iMessage, Hermes автоматически отправляет им код сопряжения. Подтвердите его командой:

hermes pairing approve bluebubbles <CODE>

Используйте hermes pairing list для просмотра ожидающих кодов и подтверждённых пользователей.

Предварительная авторизация конкретных пользователей (в ~/.hermes/.env):

BLUEBUBBLES_ALLOWED_USERS=user@icloud.com,+155****4567

Открытый доступ (в ~/.hermes/.env):

BLUEBUBBLES_ALLOW_ALL_USERS=true

5. Запуск Gateway

hermes gateway run

Hermes подключится к вашему серверу BlueBubbles, зарегистрирует вебхук и начнёт прослушивание сообщений iMessage.

Как это работает

iMessage → Messages.app → BlueBubbles Server → Webhook → Hermes
Hermes → BlueBubbles REST API → Messages.app → iMessage

• Входящие: BlueBubbles отправляет события вебхука локальному слушателю при поступлении новых сообщений. Без опроса — мгновенная доставка.

• Исходящие: Hermes отправляет сообщения через REST API BlueBubbles.

• Медиа: Изображения, голосовые сообщения, видео и документы поддерживаются в обоих направлениях. Входящие вложения скачиваются и кэшируются локально для обработки агентом.

Переменные окружения

Автоматическая отметка сообщений как прочитанных управляется ключом send_read_receipts в разделе platforms.bluebubbles.extra файла ~/.hermes/config.yaml (по умолчанию: true). Соответствующей переменной окружения нет.

Возможности

Текстовые сообщения

Отправляйте и получайте iMessage. Markdown автоматически удаляется для чистой доставки в виде обычного текста.

Медиа

• Изображения: Фотографии отображаются нативно в диалоге iMessage

• Голосовые сообщения: Аудиофайлы отправляются как голосовые сообщения iMessage

• Видео: Видео-вложения

• Документы: Файлы отправляются как вложения iMessage

Реакции Tapback

Реакции «Love», «Like», «Dislike», «Laugh», «Emphasize» и «Question». Требуют Private API helper от BlueBubbles.

Индикаторы набора текста

Показывает «typing...» в диалоге iMessage, пока агент обрабатывает запрос. Требует Private API.

Уведомления о прочтении

Автоматически отмечает сообщения как прочитанные после обработки. Требует Private API.

Адресация чатов

Вы можете адресовать чаты по email или номеру телефона — Hermes автоматически преобразует их в BlueBubbles chat GUID. Нет необходимости использовать сырой формат GUID.

Private API

Некоторые возможности требуют Private API helper от BlueBubbles:

• Реакции Tapback

• Индикаторы набора текста

• Уведомления о прочтении

• Создание новых чатов по адресу

Без Private API базовая отправка текстовых сообщений и медиа по-прежнему работают.

Устранение неполадок

«Не удаётся подключиться к серверу»

• Проверьте правильность URL сервера и что Mac включён

• Убедитесь, что BlueBubbles Server запущен

• Обеспечьте сетевую доступность (фаервол, проброс портов)

Сообщения не приходят

• Проверьте, что вебхук зарегистрирован в BlueBubbles Server → Settings → API → Webhooks

• Убедитесь, что URL вебхука доступен с Mac

• Проверьте hermes logs gateway на наличие ошибок вебхука (или hermes logs -f для отслеживания в реальном времени)

«Private API helper не подключён»

• Установите Private API helper: docs.bluebubbles.app

• Базовая отправка сообщений работает без него — только реакции, индикаторы набора и уведомления о прочтении требуют его