MINARA
Minaraを使用するクライアントとインターフェースメッセージングプラットフォーム

BlueBubbles (iMessage)

自己ホスト型 BlueBubbles サーバーを介した iMessage ブリッジ。Mac インフラの稼働が必要で、全プロバイダー中セットアップコストが最も高い。

⚠️ BlueBubbles サーバーをインストールし、iMessage アカウントにサインインした Mac が必要です。 認証は共有パスワード 1 つのみで、HMAC はありません。すでに Mac を通知ブリッジ（セキュリティチーム・オペレーションチームなど）として運用している場合に最適です。

できること

  • 送信テキスト: POST {server}/api/v1/message/text?guid=<password> に {chatGuid, message} を渡して送信します。selectedMessageGuid による引用返信にも対応しています。
  • 受信 Webhook: /webhooks/bluebubbles で new-message イベントを受け取ります。BlueBubbles は「登録して受信」モデルを採用しており、最初の送信時に Minara が BlueBubbles サーバーへ Webhook URL を登録し、その後すべての新着メッセージをイベントとして受信します。
  • テキストのみ対応: /api/v1/message/attachment による画像・添付ファイルのアップロードは現在未対応です。
  • テキスト上限は 16384 文字です。

セットアップ

1. BlueBubbles サーバーのインストール

BlueBubbles サーバー インストールガイド（公式）に従って進めます。

  1. BlueBubbles macOS アプリをダウンロードする
  2. ブリッジしたい iMessage の Apple ID で Mac にサインインする
  3. 強力なサーバーパスワードを設定する（これが BLUEBUBBLES_PASSWORD になります）
  4. サーバーを外部に公開する。BlueBubbles が対応している方法は次のとおりです。
    • Ngrok（組み込みインテグレーション）
    • Cloudflare Tunnel
    • 静的 IP へのポート手動転送
  5. BlueBubbles アプリの「Status」タブから公開 URL をコピーする。これが BLUEBUBBLES_SERVER_URL になります。

2. デフォルトチャット GUID の確認

BlueBubbles デスクトップ UI で対象の会話を開きます。「Info」パネルにチャット GUID が表示されます。形式は 1 対 1 の場合 iMessage;-;+15551234567、グループの場合 iMessage;+;chat<long hex>@imsgr.icloud.com です。これを BLUEBUBBLES_DEFAULT_CHAT_GUID として保存します。

3. Minara の設定

minara auth messaging add
# リストから `bluebubbles` を選択します。

または環境変数で設定します。

BLUEBUBBLES_SERVER_URL=https://your-tunnel.ngrok.app
BLUEBUBBLES_PASSWORD=<server password>
BLUEBUBBLES_DEFAULT_CHAT_GUID=iMessage;-;+15551234567

4. テスト

minara auth messaging test bluebubbles

対象チャットに「✅ Minara gateway test ping」が届けば成功です。iMessage の SMS フォールバックが有効な場合、SMS 部分の通信料が発生します。

受信 Webhook

BlueBubbles は、レジストリ内で唯一、純粋な共有パスワード認証（HMAC・JWT なし）を使うプロバイダーです。サーバーはパスワードを URL クエリ（?guid=<pw>）または JSON ボディ（password / token フィールド）で送信します。Minara はどちらの形式も受け付け、定数時間での比較を行います。

Webhook は BlueBubbles サーバー側で自動的に設定されます（BlueBubbles 管理 UI: 「Settings」→「Webhooks」→「Add Webhook」）。

URL:    https://<your-host>/webhooks/bluebubbles
Events: new-message

受信ペイロードの形式は次のとおりです。

{
  "type": "new-message",
  "data": {
    "guid": "<message guid>",
    "text": "hello from iMessage",
    "handle": { "address": "+15559876543" },
    "chats": [{ "guid": "iMessage;-;+15559876543" }],
    "dateCreated": 1700000000000,
    "isFromMe": false
  }
}

isFromMe: true のイベントは自己ループとしてフィルタリングされます。updated-message や typing-indicator など、その他のイベントタイプは解析されません。

制限事項と注意点

  • Mac の稼働が必須です。 iMessage にサインインした状態を維持する必要があり、本番環境での信頼性は Mac の稼働時間と Apple の iMessage サービス状態に依存します。
  • パスワード認証のみです。 BLUEBUBBLES_PASSWORD は長い共有シークレットとして扱い、定期的にローテーションしてください。HMAC がないため、パスワードが漏洩すると完全ななりすましが可能になります。
  • Apple iMessage のレート制限が適用されます。 送信速度が速すぎると、キャリアまたは Apple 側でスロットリングが発生します。BlueBubbles はこれを送信失敗として報告します。
  • 添付ファイルは未対応です。 ゲートウェイ経由での画像・ファイル送信は今後の対応予定です。

トラブルシューティング

「BlueBubbles server unreachable」と表示される

  • Mac 側のトンネル（ngrok / cloudflared）が切断されています。トンネルを再起動し、公開 URL が変わった場合は BLUEBUBBLES_SERVER_URL を更新してください。

「送信時に 401 / 403 エラーが発生する」

  • BLUEBUBBLES_PASSWORD がサーバーに保存されたパスワードと一致していません。BlueBubbles デスクトップアプリ → Settings → Server Settings でパスワードをリセットし、環境変数を更新してください。

「テストメッセージが相手の電話に届かない」

  • iMessage は Apple ID 単位で機能します。Mac が正しい Apple ID でサインインしていること、および Messages.app で対象チャットがアクティブな状態であることを確認してください。
  • 受信者が Apple 以外のデバイスを使用している場合、iMessage は SMS にフォールバックします（キャリア依存）。

「受信 Webhook が動作しない」

  • BlueBubbles の Webhook 登録はクライアント単位ではなくサーバー単位です。BlueBubbles 管理 UI を開き、Webhook URL が Minara ホストを指していることを確認してください。

リファレンス

Matrix

Client-Server API を介したフェデレーション Matrix プロトコル。インバウンドはロングポーリングデーモンとして動作し、HTTP webhook のエントリーポイントはありません。

WhatsApp

Meta の Cloud API 経由でアウトバウンドメッセージを送信します。ビジネスアカウントが必要で、セッションウィンドウの制限があり、送信専用です。

目次

できることセットアップ1. BlueBubbles サーバーのインストール2. デフォルトチャット GUID の確認3. Minara の設定4. テスト受信 Webhook制限事項と注意点トラブルシューティングリファレンス