Интеграция VoiceOS с Instagram

Управляйте своим аккаунтом Instagram голосом прямо из выреза Mac. Спрашивайте, как дела у аккаунта, читайте комментарии и личные сообщения, публикуйте фото или карусель, перетащив её на вырез и проговорив подпись.

Требуется бизнес-аккаунт или аккаунт автора. API Instagram не предоставляет статистику, комментарии, личные сообщения или публикацию для личного аккаунта — это правило Meta, а не наше, и обойти его невозможно.

Чтобы переключить: приложение Instagram → ваш профиль → меню ☰ → Настройки и конфиденциальность → Тип аккаунта и инструменты → Переключиться на профессиональный аккаунт. Выберите Автор или Бизнес, затем следуйте подсказкам. Это бесплатно, обратимо и не делает ваш аккаунт публичным, если он был закрытым. После этого переподключите эту интеграцию.

Настройка

Шесть шагов. Шаги 3 и 4 нужны только если вы хотите публиковать; для чтения они не требуются.

1. Установите зависимости

cd instagram
bun install

2. Подключите Instagram через Composio

Composio — это транспорт для аутентификации и API, на котором работает эта интеграция.

1. Получите API-ключ в панели Composio.

2. Добавьте Instagram как приложение в вашем проекте Composio. Это создаст конфигурацию аутентификации, необходимую для процесса подключения.

Сам OAuth-запрос Instagram вы одобрите на шаге 6 — пока здесь ничего делать не нужно.

3. Создайте ретрансляционный бакет для фото (Cloudflare R2)

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

В панели Cloudflare → R2:

1. Создайте бакет.

2. Откройте его → Настройки → Публичный URL для разработки → Включить. Скопируйте этот URL. Бакет должен быть публичным, иначе Meta не сможет загрузить фото.

3. Управление токенами API → Создать токен API с доступом только к этому бакету и правами на чтение и запись объектов. Секрет показывается один раз — скопируйте его сейчас.

4. Необязательно, но рекомендуется: добавьте правило жизненного цикла для удаления объектов через 1 день. Интеграция сама удаляет каждое фото; это подстраховка на случай редкого сбоя.

Пропустите весь этот шаг, если вам нужно только читать. account_pulse, post_insights, activity и dm_thread работают без бакета. Только create_post и schedule_post требуют его.

4. Передайте серверу ключи

Создайте файл .env в этой папке:

COMPOSIO_API_KEY=

# Cloudflare R2 — publishing only, leave blank if you are read-only
R2_ACCOUNT_ID=
R2_ACCESS_KEY_ID=
R2_SECRET_ACCESS_KEY=
R2_BUCKET=
R2_PUBLIC_URL=

R2_ACCOUNT_ID находится на странице R2 → Обзор в Cloudflare, в правом верхнем углу. R2_PUBLIC_URL — это публичный URL для разработки из шага 3.

Если VoiceOS запросит эти значения как поля настройки, этот ввод имеет приоритет, а файл служит только запасным вариантом для запуска сервера отдельно.

5. Установите в VoiceOS

Сначала закройте VoiceOS. Он держит config.json в памяти и перезаписывает его при выходе, поэтому всё, что записано, пока он работает, молча теряется — без каких-либо ошибок. Установщик откажется работать, если увидит, что VoiceOS запущен.

osascript -e 'quit app "VoiceOS"'
python3 install-into-voiceos.py
open -a VoiceOS

Это скопирует данную папку в ~/Library/Application Support/VoiceOS/custom-mcps/, перенесёт ключи из шага 4 и зарегистрирует интеграцию. Простого cp недостаточно — VoiceOS также нужны две записи в config.json (одна указывает, как запускать сервер, другая содержит манифест), и их запись — основная часть работы скрипта. Он сначала создаёт резервную копию config.json.

--update каждый раз заново вычисляет confirmTools из манифеста. Это важнее, чем кажется: именно этот список VoiceOS использует для определения, какие инструменты требуют карточки подтверждения, и устаревшая запись, оставшаяся после переименования, позволила бы публиковать пост без карточки вообще.

6. Подключите аккаунт

Скажите «Как там мой Instagram?». Если Instagram ещё не привязан, вы получите карточку Подключить Instagram со ссылкой OAuth. Одобрите её один раз — и всё готово.

Если сказано, что аккаунт личный, вернитесь к рамке вверху этой страницы.

Инструменты

Перетащите фото на вырез и произнесите команду в том же дыхании — «опубликуй эти два с подписью о хакатоне». Оба инструмента записи показывают вам фото, подпись и (для расписания) точное время на карточке до того, как что-либо уйдёт в публикацию.

Как обрабатываются ваши фото

Стоит прочитать один раз, потому что один шаг удивляет людей.

1. Фото преобразуется в JPEG на вашем Mac с помощью sips (встроено в macOS). Instagram не принимает ничего другого.

2. Оно загружается в ваш бакет R2 под случайным неподбираемым именем и остаётся публично доступным несколько секунд. Это неизбежно: краулер Meta анонимен и не может войти в систему, поэтому публичный URL — единственный способ, которым Instagram примет фото.

3. Instagram загружает его и публикует пост.

4. Файл удаляется из бакета — при успехе и при ошибке, в блоке finally. Правило жизненного цикла из шага 3 — подстраховка.

Бакет принадлежит вам. Ничего не хранится на чужих серверах, и эта интеграция не сохраняет копии ваших фото.

Запланированные посты выполняются на вашем Mac, а не на серверах Instagram — у Instagram нет API для планирования. Таймер macOS launchd срабатывает в указанную вами минуту и публикует пост. Поэтому Mac должен быть включён и не спать. Если он был выключен, когда пост должен был выйти, пост помечается как пропущенный, а не публикуется с опозданием на часы, и instagram_activity сообщит вам об этом при следующем запросе.

Не входит в v1

Сознательно исключено, чтобы вы знали заранее:

• Отправка личных сообщений. Meta блокирует отправку сообщений через API через общее приложение Instagram в Composio — возвращает ошибки «вне разрешённого окна», даже если 24-часовое окно заведомо открыто. Интеграция читает личные сообщения, но не может их отправлять. Отвечайте в приложении Instagram.

• Ответы на комментарии. То же ограничение транспорта.

• Видео и Reels. Только фото и фото-карусели. Публикация видео требует возобновляемой загрузки, которой в этой сборке нет.

• Истории. Не поддерживаются инструментарием.

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

• Чтение других аккаунтов. Только ваш подключённый аккаунт.

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

Разработка

bun install
bun test          # 224 unit and failure-injection tests
bunx tsc --noEmit -p tsconfig.json

Три правила, которые защищают тесты, полезно знать перед редактированием:

• stdout — это провод MCP. Один console.log в опубликованном коде — и VoiceOS не сможет разобрать поток JSON-RPC, поэтому интеграция молча исчезнет из маршрутизации до перезапуска приложения. Всё логируется через console.error; stdoutGuard.ts — первый импорт в server.ts и переназначает консоль для зависимостей, которые этого не делают.

• Никогда не собирайте строку оболочки из пути к файлу. Фото приходят от перетаскивания файла на вырез. Только execFile(cmd, [args]) — файл с именем holiday.png; rm -rf ~ — это один непрозрачный аргумент для sips, и тест test/media-paths.test.ts это проверяет.

• Имена инструментов и описания должны точно совпадать с манифестом в обе стороны. server.ts и voiceos.integration.json — две копии одного контракта.

confirmations/post_composer.html — источник истины для карточки перед публикацией; манифест содержит её копию в виде строки. Если вы редактируете HTML, копию нужно перегенерировать, иначе карточка, показанная перед необратимой публикацией, будет устаревшей.