본문으로 건너뛰기

BlueBubbles (iMessage)

BlueBubbles를 통해 Hermes를 Apple iMessage에 연결하세요 — iMessage를 어떤 장치와도 연결할 수 있는 무료 오픈 소스 macOS 서버입니다.

사전 요구 사항​

  • BlueBubbles Server를 실행 중인 Mac (항상 켜져 있어야 함)
  • 해당 Mac의 Messages.app에 로그인된 Apple ID
  • BlueBubbles Server v1.0.0+ (웹훅 사용을 위해 해당 버전 필요)
  • Hermes와 BlueBubbles 서버 간의 네트워크 연결

설정​

1. BlueBubbles Server 설치​

bluebubbles.app에서 다운로드하고 설치하세요. 설정 마법사를 완료한 후 Apple ID로 로그인하고 연결 방법(로컬 네트워크, Ngrok, Cloudflare 또는 동적 DNS)을 구성하세요.

2. 서버 URL과 비밀번호를 받으세요​

BlueBubbles 서버 → 설정 → API에서, 주의하세요:

  • 서버 URL (예: http://192.168.1.10:1234)
  • 서버 비밀번호

3. 헤르메스 구성​

설치 마법사를 실행하세요:

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`에서):
```bash
BLUEBUBBLES_ALLOWED_USERS=user@icloud.com,+15551234567

오픈 액세스 (~/.hermes/.env에서):

BLUEBUBBLES_ALLOW_ALL_USERS=true

5. 게이트웨이 시작​

hermes gateway run

Hermes는 귀하의 BlueBubbles 서버에 연결하고, 웹훅을 등록하며, iMessage 메시지를 수신 대기하기 시작합니다.

작동 원리​

iMessage → Messages.app → BlueBubbles Server → Webhook → Hermes
Hermes → BlueBubbles REST API → Messages.app → iMessage
  • 인바운드: BlueBubbles는 새 메시지가 도착하면 로컬 리스너로 웹훅 이벤트를 전송합니다. 폴링 없음 — 즉시 전송.
  • 발신: Hermes는 BlueBubbles REST API를 통해 메시지를 보냅니다.
  • 미디어: 이미지, 음성 메시지, 비디오 및 문서는 양방향으로 지원됩니다. 수신 첨부 파일은 에이전트가 처리할 수 있도록 다운로드되어 로컬에 캐시됩니다.

환경 변수​

변수필수기본값설명
BLUEBUBBLES_SERVER_URL예—BlueBubbles 서버 URL
BLUEBUBBLES_PASSWORD예—서버 비밀번호
BLUEBUBBLES_WEBHOOK_HOSTNo127.0.0.1웹훅 리스너 바인드 주소
BLUEBUBBLES_WEBHOOK_PORTNo8645웹훅 수신 포트
BLUEBUBBLES_WEBHOOK_PATHNo/bluebubbles-webhook웹훅 URL 경로
BLUEBUBBLES_HOME_CHANNELNo—크론 전송용 전화/이메일
BLUEBUBBLES_ALLOWED_USERSNo—쉼표로 구분된 권한 있는 사용자
BLUEBUBBLES_ALLOW_ALL_USERSNofalse모든 사용자 허용

메시지를 자동으로 읽음 상태로 표시하는 기능은 ~/.hermes/config.yaml에서 platforms.bluebubbles.extra 아래의 send_read_receipts 키로 제어됩니다 (기본값: true). 이에 해당하는 환경 변수는 없습니다.

특징​

문자 메시지​

iMessage를 보내고 받을 수 있습니다. 깔끔한 일반 텍스트 전달을 위해 마크다운은 자동으로 제거됩니다.

리치 미디어​

  • 이미지: 사진이 iMessage 대화에 기본적으로 나타납니다
  • 음성 메시지: iMessage 음성 메시지로 전송된 오디오 파일
  • 동영상: 동영상 첨부
  • 문서: iMessage 첨부 파일로 전송된 파일

탭백 반응​

좋아요, 마음에 들어요, 싫어요, 웃음, 강조, 질문 반응. BlueBubbles Private API helper가 필요합니다.

입력 표시기​

에이전트가 처리하는 동안 iMessage 대화에서 '입력 중...'을 표시합니다. 비공개 API가 필요합니다.

읽음 확인​

처리 후 메시지를 자동으로 읽음으로 표시합니다. 개인 API가 필요합니다.

채팅 주소 지정​

채팅은 이메일이나 전화번호로 지정할 수 있습니다 — Hermes가 이를 자동으로 BlueBubbles 채팅 GUID로 변환합니다. 원시 GUID 형식을 사용할 필요가 없습니다.

개인 API​

일부 기능은 BlueBubbles Private API helper를 필요로 합니다:

  • 탭백 반응
  • 입력 표시
  • 읽음 확인
  • 주소로 새 채팅 만들기

개인 API가 없어도 기본 문자 메시지와 미디어는 여전히 작동합니다.

문제 해결​

서버에 연결할 수 없습니다​

  • 서버 URL이 올바른지 확인하고 Mac이 켜져 있는지 확인하세요
  • BlueBubbles 서버가 실행 중인지 확인하세요
  • 네트워크 연결 상태 확인(방화벽, 포트 포워딩)

메시지가 도착하지 않음​

  • BlueBubbles 서버 → 설정 → API → 웹훅에서 웹훅이 등록되어 있는지 확인하세요
  • 웹훅 URL이 Mac에서 접근 가능한지 확인하세요
  • 웹훅 오류는 hermes logs gateway에서 확인하세요 (또는 실시간으로 확인하려면 hermes logs -f).

"개인 API 헬퍼가 연결되지 않음"​

  • 개인 API 도우미를 설치하세요: docs.bluebubbles.app
  • 기본 메시징은 그것 없이도 작동합니다 — 반응, 입력 표시, 읽음 확인만 필요합니다