| 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
- macOS Server: Runs Messages.app with client's Apple ID
- Relay Software: BlueBubbles or custom server forwards messages
- OpenClaw Integration: Receives webhooks, sends responses
- 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)
- Install BlueBubbles on macOS: https://bluebubbles.app
- Configure server password and port
- 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 "+1-555-123-4567" --relay-type bluebubbles
Send test message
python3 imessage_setup.py --client-id CLIENT-001 --test-message "+1-555-123-4567"
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: +1-555-123-4567
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
