freight-imessage-setup

name	freight-imessage-setup
description	Configure iMessage relay servers for client SMS integration. Supports BlueBubbles or custom relay implementations to enable two-way SMS communication between freight brokers and the AI. Use when setting up iMessage for a new client, testing SMS connectivity, or checking relay status. Triggered by "setup iMessage", "configure SMS", "test iMessage", "iMessage status", or "SMS relay".

Freight iMessage Setup

Configures iMessage relay for client SMS integration. Brokers communicate with AI via text message.

How It Works

1. macOS Server: Runs Messages.app with client's Apple ID
2. Relay Software: BlueBubbles or custom server forwards messages
3. OpenClaw Integration: Receives webhooks, sends responses
4. Broker Experience: Texts commands, receives AI responses

Requirements

• macOS device (Mac Mini, MacBook, or cloud Mac)
• Apple ID logged into Messages.app
• Static IP or domain name
• BlueBubbles server installed

Setup

Option 1: BlueBubbles (Recommended)

1. Install BlueBubbles on macOS: https://bluebubbles.app
2. Configure server password and port
3. Set env vars:

   export IMESSAGE_SERVER_HOST=your-server-ip
   export IMESSAGE_SERVER_PORT=12345
   export IMESSAGE_SERVER_PASSWORD=your-password
   

Option 2: Custom Relay

Build your own relay using:

• python-imessage library
• Webhook forwarding to OpenClaw
• HTTP API for sending messages

Usage

Configure iMessage for client

cd skills/freight-imessage-setup/scripts
python3 imessage_setup.py --setup --client-id CLIENT-001 --phone "[phone]" --relay-type bluebubbles

Send test message

python3 imessage_setup.py --client-id CLIENT-001 --test-message "[phone]"

Check status

python3 imessage_setup.py --client-id CLIENT-001 --status

Broker Text Commands (Once Configured)

Once iMessage is active, brokers can text:

Text	Action
find loads LA to NYC	Scan load board
vet MC#123456	Check carrier
check emails	Email summary
status	Current workload
help	Command list

SMS Output Example

✅ IMESSAGE CONFIGURED
Client: CLIENT-001
Phone: [phone]
Relay: BlueBubbles @ 192.0.2.50:12345
Status: Active

Test message sent successfully.
Ready for broker SMS commands.

Integrations

This skill uses the following external services. See INTEGRATIONS.md for detailed setup instructions, API documentation links, and implementation guidance.

Service	Purpose	Section in INTEGRATIONS.md
Twilio	SMS fallback	Shared Infrastructure: Twilio
BlueBubbles	iMessage relay	Refer to this SKILL.md
LoopMessage	Hosted iMessage bridge	Refer to freight-twilio-webhook SKILL.md

See INTEGRATIONS.md for complete integration architecture

Troubleshooting

• "Could not connect" → Check firewall, verify server is running
• Messages not sending → Verify Apple ID is signed in on Mac
• No webhook received → Check OpenClaw gateway configuration