freight-twilio-webhook

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=[phone]

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 "[phone]" --message "Hello" --smart

Force iMessage (falls back to SMS)

python3 loopmessage.py --send --to "[phone]" --message "Hello"

Send SMS only

python3 send_sms.py --to "[phone]" --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	[phone]	/webhook/sms?client=abc
XYZ Logistics	[phone]	/webhook/sms?client=xyz

Or use separate VPS per client for isolation.

Production Deployment

# /etc/systemd/system/freight-webhook.service
[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