BlueBubbles (iMessage)

자체 호스팅 BlueBubbles 서버를 통한 iMessage 브리지. Mac 인프라 운영이 필요하며, 모든 공급자 중 초기 설정 비용이 가장 높습니다.

⚠️ BlueBubbles 서버가 설치된 Mac에서 iMessage 계정에 로그인되어 있어야 합니다. 인증 방식은 단일 공유 비밀번호이며, HMAC은 지원하지 않습니다. Mac을 알림 브리지로 이미 운영 중인 경우(보안팀, 운영팀 등)에 가장 적합합니다.

제공 기능

아웃바운드 텍스트: POST {server}/api/v1/message/text?guid=<password> 엔드포인트에 {chatGuid, message}를 전송합니다. selectedMessageGuid를 통한 인용 답장(Reply-to)도 지원합니다.
인바운드 웹훅: new-message 이벤트를 위한 /webhooks/bluebubbles 엔드포인트. BlueBubbles는 "등록 후 수신" 모델을 사용합니다. Minara는 첫 번째 아웃바운드 시 BlueBubbles 서버에 웹훅 URL을 등록하고, 이후 모든 새 메시지 이벤트를 수신합니다.
텍스트 전용. /api/v1/message/attachment를 통한 이미지 및 첨부파일 업로드는 추후 지원 예정입니다.
텍스트 최대 16,384자.

설정

1. BlueBubbles 서버 설치

공식 BlueBubbles 서버 설치 가이드를 따르십시오.

BlueBubbles macOS 앱을 다운로드합니다.
브리지할 iMessage Apple ID로 Mac에 로그인합니다.
강력한 서버 비밀번호를 설정합니다. 이 값이 BLUEBUBBLES_PASSWORD가 됩니다.
서버를 외부에 공개합니다. BlueBubbles는 다음 방식을 지원합니다.
- Ngrok (내장 연동)
- Cloudflare Tunnel
- 고정 IP를 통한 수동 포트 포워딩
BlueBubbles 앱의 "Status" 탭에서 공개 URL을 복사합니다. 이 값이 BLUEBUBBLES_SERVER_URL이 됩니다.

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 요금이 부과될 수 있습니다.

인바운드 웹훅

BlueBubbles는 레지스트리 내 유일하게 순수 공유 비밀번호 인증 방식을 사용하는 공급자입니다. HMAC 및 JWT를 지원하지 않습니다. 서버는 URL 쿼리 파라미터(?guid=<pw>) 또는 JSON 본문의 password / token 필드를 통해 비밀번호를 전송합니다. Minara는 두 형식을 모두 허용하며, 상수 시간 비교(constant-time comparison)를 수행합니다.

웹훅은 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이 지속적으로 실행되어야 합니다. 서비스 안정성은 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로 폴백됩니다. 이는 통신사에 따라 다릅니다.

"인바운드 웹훅이 동작하지 않음"

BlueBubbles의 웹훅 등록은 클라이언트가 아닌 서버 단위입니다. BlueBubbles 관리자 UI를 열어 웹훅 URL이 Minara 호스트를 가리키고 있는지 확인하십시오.

참조

환경 변수: BLUEBUBBLES_*
아웃바운드: apps/agent/src/messaging/bluebubbles.ts
인바운드 명세: apps/agent/src/messaging/inbound/specs/bluebubbles.ts
BlueBubbles 프로젝트: bluebubbles.app
REST API: docs.bluebubbles.app / REST API & Webhooks