| name | freight-twilio-webhook |
| description | Universal SMS and iMessage webhook handler for freight broker AI. Supports Twilio SMS and LoopMessage iMessage with automatic fallback. No macOS server required - use LoopMessage hosted iMessage API for blue bubbles. Use when setting up SMS/iMessage integration, handling inbound broker texts, or sending AI responses. Triggered by Twilio or LoopMessage webhooks automatically. |
Freight Messaging Webhook
Universal messaging handler supporting Twilio SMS and LoopMessage iMessage with automatic channel selection.
Two Options
Option A: Twilio Only (SMS - Green Bubbles)
- Works with any phone (iPhone/Android)
- Pay per message ($0.0075/msg)
- Simple setup, no Mac needed
Option B: LoopMessage + Twilio (iMessage - Blue Bubbles + SMS Fallback)
- iMessage for iPhone users (free, blue bubbles)
- SMS fallback for Android via Twilio
- LoopMessage hosts the Mac infrastructure (~$20-50/mo)
- You don't manage any Mac servers!
Setup
Twilio (Required for SMS)
export TWILIO_ACCOUNT_SID=ACxxxxxxxx
export TWILIO_AUTH_TOKEN=your_token
export TWILIO_PHONE_NUMBER=+15551234567
LoopMessage (Optional - for iMessage)
export LOOPMESSAGE_API_KEY=your_key
export LOOPMESSAGE_SENDER_NAME=YourBusiness
Get LoopMessage API key: https://loopmessage.com
Webhook Configuration
Twilio Setup
- Phone Numbers → Manage → Active Numbers
- Messaging webhook:
http://your-vps:8080/webhook/sms
- Method: HTTP POST
LoopMessage Setup
- Dashboard → Webhooks
- Inbound webhook:
http://your-vps:8080/webhook/imessage
- Enable SMS fallback with Twilio credentials
Usage
Start webhook server
cd skills/freight-twilio-webhook/scripts
python3 webhook_server.py --port 8080
Send via best channel (auto-detect)
python3 message_router.py --to "+15551234567" --message "Hello" --smart
Force iMessage (falls back to SMS)
python3 loopmessage.py --send --to "+15551234567" --message "Hello"
Send SMS only
python3 send_sms.py --to "+15551234567" --message "Hello"
How LoopMessage Works
Broker (iPhone) → iMessage → LoopMessage → Webhook → Your VPS → AI Response
↓
Broker (Android) → SMS (Twilio) ← Fallback if no iMessage ←┘
Key benefits:
- iPhone users see blue bubbles (free iMessage)
- Android users get SMS (Twilio rates)
- LoopMessage detects device type automatically
- You pay Twilio only for Android/non-iMessage recipients
Cost Comparison
| Setup | Monthly Cost | Best For |
|---|
| Twilio only | ~$8-15 (1k msgs) | Mixed iPhone/Android, simple |
| LoopMessage + Twilio | ~$25-60 (LoopMsg + SMS) | iPhone-heavy, professional image |
| BlueBubbles (self-hosted) | ~$100 (Mac server) | Full control, high volume |
Supported Commands
Brokers text these to your number:
| Command | Response |
|---|
find loads [origin] to [dest] | Load search results |
vet MC#[number] | FMCSA carrier check |
check emails | Email summary |
status | System status |
help | Command list |
Example SMS/iMessage Exchange
Broker sends:
find loads Dallas to Chicago dry van
AI replies (blue bubble if iPhone):
🚛 LOAD SEARCH
To search live loads, configure:
- DAT_CLIENT_ID
- DAT_CLIENT_SECRET
Example: find loads LA to NYC reefer
Health Check
curl http://your-vps:8080/health
Returns:
{
"status": "ok",
"twilio": true,
"loopmessage": true
}
Multi-Client Setup
Each client gets their own Twilio number, all pointing to same VPS:
| Client | Twilio Number | Webhook URL |
|---|
| ABC Trucking | +1-555-111-0000 | /webhook/sms?client=abc |
| XYZ Logistics | +1-555-222-0000 | /webhook/sms?client=xyz |
Or use separate VPS per client for isolation.
Production Deployment
[Unit]
Description=Freight Messaging Webhook
After=network.target
[Service]
Type=simple
User=freightbroker
WorkingDirectory=/opt/freight-broker/skills/freight-twilio-webhook/scripts
ExecStart=/usr/bin/python3 webhook_server.py --port 8080
Restart=always
Environment=TWILIO_ACCOUNT_SID=ACxxx
Environment=TWILIO_AUTH_TOKEN=xxx
Environment=LOOPMESSAGE_API_KEY=xxx
[Install]
WantedBy=multi-user.target
Enable:
sudo systemctl enable freight-webhook
sudo systemctl start freight-webhook
Troubleshooting
| Issue | Solution |
|---|
| "Webhook unreachable" | Open port 8080 on VPS firewall |
| No iMessage delivery | Check LoopMessage API key, verify recipient has iPhone |
| SMS not sending | Verify Twilio credentials and phone number |
| "Unknown sender" | Set LOOPMESSAGE_SENDER_NAME in env vars |
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 sending and receiving | Shared Infrastructure: Twilio |
| Telnyx | SMS/voice alternative | Shared Infrastructure: Telnyx |
| LoopMessage | Hosted iMessage bridge | Refer to this SKILL.md |
| Slack | Internal notifications | Shared Infrastructure: Slack Webhook |
See INTEGRATIONS.md for complete integration architecture
LoopMessage vs Alternatives
| Service | Cost | Mac Required | Notes |
|---|
| LoopMessage | $20-50/mo | No | Hosted, reliable, easy |
| BlueBubbles self-hosted | $0 (but need Mac) | Yes | Full control, more work |
| MacStadium | $100+/mo | Yes (cloud) | Expensive, managed |
| Twilio only | Per-message | No | SMS only, green bubbles |
