.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
Getting OpenClaw on SMS and iMessage sounds simple until you hit the real constraints: SMS needs a phone number provider and inbound webhooks. iMessage has no official public API so you either run a Mac bridge or you pay a hosted service that runs it for you.
This guide covers the setups that actually hold up over time, with enough detail that you can build something stable on a VPS and not babysit it every day. I’ll keep it practical, but I won’t pretend the trade-offs don’t exist.
If you haven’t deployed OpenClaw yet, start with the OpenClaw onboarding over SSH so you have a working gateway before adding mobile channels.
What “SMS and iMessage integration” means in OpenClaw
OpenClaw uses channels for messaging platforms. Telegram, WhatsApp, Discord, Slack, SMS, iMessage: they’re all just channels with the same two responsibilities.
- Inbound: receive messages from users and turn them into a normalized event
- Outbound: send the agent’s reply back to the same conversation thread
Once a message is normalized, the rest of OpenClaw doesn’t care where it came from. The agent gets text, optional attachments, metadata, a channel ID, and a conversation identifier. Memory and state are keyed by channel and conversation, which keeps SMS threads from contaminating iMessage group chats and keeps both from mixing with your Discord experiments.
If you already run multiple chat surfaces, the OpenClaw multi-channel setup explains the general pattern. SMS and iMessage follow the same logic, just with more annoying infrastructure.
Decide your path before you touch config
There are two decisions that shape everything else.
Decision 1: Do you need two-way chat or only alerts?
Outbound-only is far easier. A skill can send an SMS when a job finishes, a payment fails, or a server goes down. Two-way chat means inbound webhooks, routing, spam control, and a clearer idea of what the assistant is allowed to do over a phone channel.
Decision 2: Who runs the “phone side”?
For SMS, you can run the phone side via a cloud provider like Twilio or by turning a phone into a gateway. For iMessage, you almost always need a Mac bridge unless you use a hosted iMessage API service.
Pick what you want first. If you try to “keep options open” you’ll end up with a half-built pipeline that’s brittle and hard to secure.
SMS channel option A: Using Twilio
Twilio is the default choice because it’s predictable. The docs are solid, the webhook model is well understood, and if something breaks you can usually see it in their console logs.
Twilio’s SMS docs are here: Twilio SMS documentation. Their security docs also cover webhook request validation, which you should implement if you expose an inbound endpoint.
What you get with Twilio
You get a number that can send and receive messages. You also get a webhook from Twilio to your server for inbound messages and a REST API for outbound messages.
The part that surprises people is cost. You pay per message and sometimes per carrier route. It’s fine for low to moderate volume, but if you plan on using SMS like a chat app all day, you’ll notice it.
Outbound-only SMS from OpenClaw
This is the simplest setup and it’s a great starting point. Think “send me a message when something matters” not “replace my whole messaging stack.”
At a minimum, Twilio needs:
- Account SID
- Auth token
- A from number or messaging service SID
A basic outbound request looks like this:
curl -X POST "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Messages.json" \
-u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
--data-urlencode "To=+15551234567" \
--data-urlencode "From=+15557654321" \
--data-urlencode "Body=OpenClaw finished the task."In OpenClaw terms, this is usually implemented as a skill. If you want to write this cleanly as a reusable skill with environment variables and safe input handling, the OpenClaw skills guide is the right reference.
Two-way SMS with Twilio webhooks
Two-way SMS is where you stop “sending notifications” and start running a real channel.
Here’s the normal flow:
- User texts your Twilio number
- Twilio POSTs a webhook to your endpoint with sender, recipient, and message content
- Your handler forwards the message to OpenClaw hooks
- OpenClaw generates a reply
- Your handler sends the reply back to Twilio via their REST API
The webhook payload Twilio sends is form-encoded by default. Your handler needs to normalize it into something OpenClaw can process consistently.
A clean approach is to forward inbound SMS into /hooks/agent so the gateway stays the single control plane for “incoming messages from outside.” If you already expose hooks for other services, keep the same auth style and logging conventions.
Also, don’t expose the OpenClaw gateway directly on the internet without hardening. Use the approach from host OpenClaw securely on VPS before you open inbound webhooks.
Webhook handler responsibilities
Your webhook handler has to do a little more than pass text through.
- Verify the request is really from Twilio
- Rate limit by sender number
- Decide what “to” means in OpenClaw terms (conversation key)
- Convert inbound data into a hooks call
- Send the outbound reply back through Twilio
If you skip signature validation, the first spammer who finds your endpoint can turn it into an expensive toy. If you skip rate limiting, a single angry person can do the same thing faster.
Message length and output control
SMS is short. If your agent returns 1,200 characters, it will either be split or truncated depending on provider and route. Don’t rely on “it’ll be fine.” Put output controls in place.
Common options:
- Cap the maximum response length for SMS conversations
- Summarize long answers and send a short version with “reply MORE” prompts
- Send links to longer content instead of dumping it into SMS
If you already use OpenClaw for document tasks, the PDF summarization and extraction guide pairs well with SMS output constraints because it shows how to compress results into useful summaries.
SMS channel option B: Using an Android gateway
If Twilio feels expensive or you want messages to originate from your actual SIM number, a phone-based SMS gateway is the practical alternative.
One example is textbee.dev, which turns an Android device into an SMS API. The device sends SMS using your plan and exposes an HTTP interface you can call from your server.
Where this approach fits
I like the Android gateway approach for personal assistants and for prototypes. For business-critical lines, it depends on your tolerance for weird phone behavior like battery optimization, app background limits, or the occasional forced update at 2am.
Architecture
- OpenClaw runs on your server
- Android device runs the SMS gateway app
- Outbound messages go from OpenClaw to the Android HTTP API
- Inbound messages are either pushed to your server or polled then forwarded into OpenClaw hooks
The same security rules apply: authenticate inbound events, rate limit, and keep logs minimal. SMS content is sensitive in the boring ways too. It contains addresses, invoices, password reset links, and a surprising amount of personal data.
iMessage option A: Using BlueBubbles
Apple does not provide a public iMessage API that you can call from Linux. So the most common real-world solution is a macOS bridge that can access Messages and expose a REST interface you can integrate with.
BlueBubbles is the most approachable option because it was built for this role. Project site: BlueBubbles.
What BlueBubbles gives you
BlueBubbles runs on a Mac that is signed into iMessage. It can expose an API for sending messages and it can send webhooks for inbound messages, including group chat identifiers and message metadata. It’s not perfect but it’s far less fragile than homegrown AppleScript glue.
Minimal BlueBubbles integration design
Keep the integration boring:
- BlueBubbles receives the message event from macOS Messages
- BlueBubbles POSTs a webhook to your server
- Your server normalizes the event and forwards it to OpenClaw hooks
- OpenClaw replies with text and optional attachment references
- Your server sends the outbound reply to BlueBubbles via its API
The main trick is that you should treat BlueBubbles like a provider, similar to Twilio. Authenticate everything. Avoid exposing it directly to the public internet. Prefer VPN or a tunnel. The Messages database and message history on that Mac is extremely sensitive.
SMS forwarding through the same Mac
If you enable SMS forwarding on macOS, the Mac can relay green bubble SMS as well as iMessage. That can simplify your setup because you can treat “mobile messaging” as one bridge. It’s convenient, but it also concentrates risk onto that one Mac, so keep the machine dedicated to the bridge if you can.
Attachments and media limits
Media is where iMessage setups go sideways fast. A bot that sends images, voice notes, or large files needs careful limits.
- Set a media max size in your integration layer
- Prefer links to files rather than pushing huge attachments
- Strip EXIF metadata from images if you handle photos
Even if BlueBubbles supports it, that does not mean your assistant should spam it. Phone messaging is high-trust by default. Keep it respectful and compact.
iMessage option B: Using imsg CLI
The imsg CLI approach is older and more hands-on. It typically relies on macOS automation and access to the Messages database at:
~/Library/Messages/chat.dbThat database contains a lot more than “the last few messages.” It is basically your messaging life, which is why macOS permissions are strict here.
What you must set up on macOS
- Messages is signed into the Apple ID you want to use
- Full Disk Access is granted to the process that reads chat.db
- Automation permission allows sending messages via Messages.app
- The Mac user session stays logged in
Once it works, it’s usable. The problem is that it can get brittle after system updates, privacy permission resets, or database schema changes.
Remote Mac bridge pattern
A common design is running OpenClaw on a VPS and using SSH to call imsg on a Mac. In practice, you wrap the CLI path in a script that executes the remote command via SSH. That keeps the gateway stable on Linux while leaving Apple-only stuff on Apple hardware.
If you already run the gateway under systemd and want predictable restarts and log control, your existing systemd approach matters here too. The OpenClaw systemd setup guide is relevant because the same “run one instance, restart cleanly” discipline prevents duplicate messages and weird replays.
Hosted iMessage API services
Hosted iMessage API services exist because plenty of teams don’t want to maintain a Mac bridge. The idea is simple: they run the bridge and expose webhooks and REST endpoints.
This is a legit option if you accept the trust model. Messages pass through infrastructure you do not control. For some people that is a deal breaker. For others, it’s the only way to ship a business line without babysitting a Mac mini.
If you take this route, treat it the same as a cloud SMS provider: verify signatures, rotate secrets, keep logs minimal, and don’t store message bodies longer than you need.
Routing and conversation identity
The biggest implementation mistake I see is mixing up “sender identity” with “conversation identity.” SMS is usually one-to-one, so people get sloppy. iMessage can be one-to-one, group chats, and threads with shifting participants.
Use a stable conversation key:
- For SMS, the sender number can be your conversation key
- For iMessage, use the chat GUID or stable chat identifier from the bridge
If your integration layer collapses all iMessage messages into one thread because “it’s the same Apple ID,” your agent memory becomes useless fast.
Abuse control and safety boundaries
Once you put an agent behind a phone number, people will test it. Sometimes that’s a friend. Sometimes it’s a random sender (or a stranger with bad intentions). Put boundaries in place from day one.
Whitelist mode for personal assistants
If this is for you, whitelist your numbers and maybe one or two trusted contacts. You can loosen it later. Starting open is how you get woken up by spam at night and billed for it.
Rate limits and quotas
Rate limits should exist at multiple layers:
- At the public webhook edge (per IP, per sender)
- At the provider layer (Twilio settings where possible)
- At the OpenClaw hook entrypoint (reject bursts and duplicates)
Prompt injection risks on mobile channels
Mobile messaging feels casual which makes it a great delivery channel for prompt injection attempts. If your agent has tools enabled, assume someone will try “paste this command” style tricks.
This is why security hardening is not optional.
If you want a solid baseline, use OpenClaw security best practices as a checklist and actually implement the boring parts like least privilege users, restricted filesystem access, and tight webhook auth.
Webhooks reliability and retries
Mobile channels should feel instant. In reality, webhooks fail. Reverse proxies reload. Certificates expire. Servers reboot. Providers retry and sometimes they retry the same payload more than once.
Your integration layer should be idempotent: if the same inbound event arrives twice, you should detect that and avoid sending two replies. For SMS, duplicates are annoying. For iMessage group chats, duplicates get embarrassing quickly.
If you want retries, request inspection, and a stable inbound URL without exposing your gateway directly, a webhook relay can help. Hookdeck is one example that provides retries and replay tooling.
Running this on a VPS without making it fragile
Mobile channels benefit from an always-on server. A laptop sleeps. A homelab loses power. A VPS is boring and that’s the point.
Keep the gateway stable, keep your webhook handler separate if it needs special logic, and log with restraint. Message bodies do not belong in giant debug logs. They always end up containing something sensitive at the worst moment.
If you are using OpenClaw on Discord or Slack too, it’s worth keeping that config clean. If you need a reference for a working chat channel integration, the connect OpenClaw to Discord tutorial is a decent baseline because it forces you to think about channel identity and delivery.
Common failure modes and how to debug them
Inbound messages arrive but OpenClaw does not respond
Check the chain in order:
- Provider webhook delivery logs
- Your webhook handler logs
- OpenClaw gateway logs
If the handler never calls OpenClaw, fix your handler. If it calls OpenClaw and gets 401, fix hook auth. If OpenClaw processes the message but the provider never gets the outbound call, fix outbound credentials or networking.
Duplicate replies
This usually means retries or multiple running processes. Make sure you have one gateway instance. If you use systemd, avoid running a second manual process out of habit.
iMessage bridge works for a day then stops
On macOS, permissions and background behavior are the usual suspects. Updates can reset privacy permissions. Sleep settings can break long-lived connections. Treat the Mac bridge as a small production service, not a personal desktop you occasionally close.
Long responses look broken on SMS
SMS splitting is ugly. Put a response cap in place and prefer short summaries. If a user wants details, give them a follow-up mechanic like “reply DETAILS” and send a condensed structured output.
One last note...
Mobile messaging feels casual, but it’s a high-trust channel. Keep permissions tight, keep outputs compact and avoid logging message bodies unless you enjoy future regret.
