BlueBubbles (iMessage)

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

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

• Mac (постоянно включённый) с запущенным BlueBubbles Server
• Apple ID, выполнивший вход в Messages.app на этом Mac
• BlueBubbles Server версии 1.0.0+ (вебхуки требуют этой версии)
• Сетевая связность между VibeOS и сервером BlueBubbles

Настройка

1. Установите BlueBubbles Server

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

2. Получите URL сервера и пароль

В BlueBubbles Server → Настройки → API запишите:

• URL сервера (например, http://192.168.1.10:1234)
• Пароль сервера

3. Настройте VibeOS

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

vibeos gateway setup

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

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

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

Опционально: требовать упоминания в групповых чатах

По умолчанию VibeOS отвечает на каждое авторизованное личное или групповое сообщение BlueBubbles/iMessage. Чтобы сделать групповые чаты опциональными, включите фильтрацию по упоминаниям:

platforms:
  bluebubbles:
    enabled: true
    extra:
      require_mention: true

С require_mention: true личные сообщения работают как обычно, но сообщения в групповых чатах игнорируются, если они не соответствуют шаблону упоминания. Если вы не настроите собственные шаблоны, VibeOS использует консервативные значения по умолчанию для вариантов VibeOS и @VibeOS agent.

Для собственного имени агента задайте regex-шаблоны:

platforms:
  bluebubbles:
    extra:
      require_mention: true
      mention_patterns:
        - '(?<![\w@])@?amos\b[,:\-]?'

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

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

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

vibeos pairing approve bluebubbles <CODE>

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

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

BLUEBUBBLES_ALLOWED_USERS=user@icloud.com,+15551234567

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

BLUEBUBBLES_ALLOW_ALL_USERS=true

5. Запустите шлюз

vibeos gateway run

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

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

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

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

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

Переменная	Обязательная	По умолчанию	Описание
BLUEBUBBLES_SERVER_URL	Да	—	URL сервера BlueBubbles
BLUEBUBBLES_PASSWORD	Да	—	Пароль сервера
BLUEBUBBLES_WEBHOOK_HOST	Нет	127.0.0.1	Адрес привязки слушателя вебхука
BLUEBUBBLES_WEBHOOK_PORT	Нет	8645	Порт слушателя вебхука
BLUEBUBBLES_WEBHOOK_PATH	Нет	/bluebubbles-webhook	Путь URL вебхука
BLUEBUBBLES_HOME_CHANNEL	Нет	—	Телефон/email для доставки по расписанию
BLUEBUBBLES_ALLOWED_USERS	Нет	—	Авторизованные пользователи через запятую
BLUEBUBBLES_ALLOW_ALL_USERS	Нет	false	Разрешить всех пользователей
BLUEBUBBLES_REQUIRE_MENTION	Нет	false	Требовать шаблон упоминания перед ответом в групповых чатах
BLUEBUBBLES_MENTION_PATTERNS	Нет	Слова пробуждения VibeOS	JSON-массив, разделённые новой строкой или запятой regex-шаблоны для сопоставления упоминаний в группах

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

Возможности

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

Отправка и получение iMessages. Markdown автоматически удаляется для чистого текстового формата.

Богатый медиаконтент

• Изображения: Фотографии отображаются нативно в диалоге iMessage
• Голосовые сообщения: Аудиофайлы отправляются как голосовые сообщения iMessage
• Видео: Видеовложения
• Документы: Файлы отправляются как вложения iMessage

Реакции Tapback

Реакции «Нравится», «Люблю», «Не нравится», «Смешно», «Подчеркнуть» и «Вопрос». Требуется помощник Private API BlueBubbles.

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

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

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

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

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

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

Private API

Некоторые функции требуют помощника Private API BlueBubbles:

• Реакции Tapback
• Индикаторы набора текста
• Уведомления о прочтении
• Создание новых чатов по адресу

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

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

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

• Проверьте правильность URL сервера и что Mac включён
• Убедитесь, что BlueBubbles Server запущен
• Проверьте сетевую связность (брандмауэр, проброс портов)

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

• Проверьте, что вебхук зарегистрирован в BlueBubbles Server → Настройки → API → Webhooks
• Убедитесь, что URL вебхука доступен с Mac
• Проверьте vibeos logs gateway на наличие ошибок вебхука (или vibeos logs -f для отслеживания в реальном времени)

«Помощник Private API не подключён»

• Установите помощника Private API: docs.bluebubbles.app
• Базовая отправка сообщений работает без него — только реакции, индикаторы набора и уведомления о прочтении требуют его наличия