Channels

iMessage

The iMessage channel connects Open Astra agents to iMessage via BlueBubbles, a server that runs on a macOS machine and exposes iMessage through a REST API. This allows agents to send and receive iMessages from any Apple device signed into the Mac's Apple ID.

Prerequisites

  • A macOS machine that stays running (a Mac Mini works well)
  • BlueBubbles Server installed and running on that Mac
  • The machine must be signed into the Apple ID you want to use for the bot
  • Network access from the Astra gateway to the BlueBubbles server

Setup

  1. Download and install BlueBubbles Server on your Mac
  2. Complete the setup wizard in BlueBubbles and note the server URL and password
  3. In BlueBubbles settings, enable the REST API
  4. Add to your Astra environment:
bash
BLUEBUBBLES_URL=http://your-mac-ip:1234
BLUEBUBBLES_PASSWORD=your-bluebubbles-password

Configuration in astra.yml

yaml
channels:
  imessage:
    enabled: true
    defaultAgent: assistant-agent
    allowedHandles: []          # Empty means all contacts allowed
    pollIntervalMs: 5000        # Poll BlueBubbles for new messages

Limitations

  • Requires a macOS machine to remain powered on and online — there is no cloud-based iMessage API
  • Only the Apple ID signed into the Mac can send messages through this integration
  • Group chats are supported but the bot will respond to all messages in the group
  • Apple can revoke access at any time if they detect automation — use this for personal or internal team use only
ℹBlueBubbles also supports a Firebase Cloud Messaging push mode that avoids polling. Refer to the BlueBubbles documentation for setup instructions if you need lower latency than polling provides.