iMessage API: send and receive messages from any AI agent

The short answer: Apple does not provide a general-purpose public iMessage API for arbitrary agent conversations. Developers use one of three routes: an approved Apple business product, a managed iMessage API, or a self-hosted Mac bridge. The best route depends on whether you need a consumer-style blue bubble, published compliance controls, or full ownership of the infrastructure.

This guide focuses on the engineering decision. It shows the complete message path, the boundaries that matter in production, and a copyable quickstart that ends when a reply reaches your agent. If you are comparing vendors, use the separate iMessage API comparison. If cost is the main question, see the iMessage API pricing guide.

The three ways to access iMessage

Apple's official developer pages cover products such as Messages for Business and Messages for Communication. Those are the right place to start when your use case fits Apple's approved categories. See Apple's Messages developer overview. Do not assume that access gives an AI agent a normal personal iMessage identity.

Where each alternative is better

There is no honest universal winner. The important differences are operational control, compliance evidence, and the amount of infrastructure your team wants to own.

• Use BlueBubbles when you already own a Mac and want direct control over the bridge, Apple account, database, and network. It is a strong fit for technical teams that accept the maintenance burden.
• Use Sendblue when published compliance and SDK breadth are hard requirements. Its public API materials emphasize REST, SDKs, webhooks, a sandbox, SOC 2 Type II, and HIPAA support. Verify the current contract and price with Sendblue before buying.
• Use Claw Messenger when the priority is a low-cost managed path for an AI agent without a Mac. It starts with one controlled thread, supports REST sending plus WebSocket replies by default, and keeps accepted or delivered status separate from actual reply proof. Webhooks are limited to approved managed setups where delivery has been configured.

The dedicated comparison covers Apple, BlueBubbles, Sendblue, LoopMessage, Blooio, and Claw Messenger side by side. This page stays focused on building the integration.

The architecture of a two-way iMessage API

1. Route ownership: map a registered phone or conversation to the correct tenant before accepting work.
2. Outbound request: your agent sends a recipient and plain text through REST.
3. Provider transport: the API submits the message to Apple's messaging network and reports what it can prove.
4. Inbound listener: a WebSocket process remains available for replies and status events. Approved managed webhook setups can use their configured endpoint instead.
5. Correlation: your backend matches the reply to the correct tenant, chat, and agent run.

The common mistake is to build only step two. A successful POST means the API accepted an outbound request. It does not prove that the recipient replied or that the reply reached the agent. Keep the inbound process connected before the controlled send and leave it running until the matching reply appears.

Quickstart: REST out, WebSocket reply in

Use a phone you control for the first test. Do not contact a customer or import a recipient list while you are validating the integration.

1. Start a trial and register the controlled phone

Create an API key in the Claw Messenger dashboard. Keep it in an environment variable and register the E.164 phone that will receive the controlled message.

curl -X POST https://claw-messenger.onrender.com/api/routes \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"phone_number":"+15551234567"}'

2. Connect the inbound listener first

Open the WebSocket before sending. Respond to ping events so the connection stays healthy. The example logs the inbound event for a local test; production code should validate, correlate, and store only what your application needs.

const socket = new WebSocket(
  'wss://claw-messenger.onrender.com/ws?key=' +
    encodeURIComponent(process.env.CLAW_API_KEY)
);

socket.onmessage = ({ data }) => {
  const event = JSON.parse(data);
  if (event.type === 'ping') {
    socket.send(JSON.stringify({ type: 'pong' }));
    return;
  }
  if (event.type === 'message') {
    console.log('Reply received:', event);
  }
};

The API key appears in the WebSocket URL, so never print the URL or leave it in request logs. Redact it in errors, traces, and provider diagnostics.

3. Confirm readiness

Check the authenticated readiness endpoint. Stop if the receiver is not ready. Sending while the listener is disconnected creates a false sense of completion.

curl https://claw-messenger.onrender.com/api/agent/readiness \
  -H 'Authorization: Bearer YOUR_API_KEY'

# Continue only when the response includes:
# {"ready":true,"action":"send_controlled_test"}

4. Send one plain message

Keep the listener running and send a message with a unique, human-readable reply instruction.

curl -X POST https://claw-messenger.onrender.com/api/agent/send-message \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "phone_number":"+15551234567",
    "text":"Reply with: API test received",
    "claim_route":false
  }'

5. Reply from the controlled phone

Reply in the same conversation. The finish state is not accepted, delivered, or read. The finish state is:

Reply received by your agent.

If a reply arrived while the listener was disconnected, reconnect and use the documented recovery or sync path. Do not emit your activation event until the reply has actually reached the connected agent or backend. In an approved managed webhook setup, wait until it reaches the configured webhook.

Use the same contract from your agent framework

The transport contract does not change when a framework wraps it. A tool call can send a message, but persistent inbound work still needs a long-running WebSocket listener. Approved managed setups can use a configured webhook service instead.

• LangChain and LangGraph iMessage integration for a Python tool plus matching reply flow.
• CrewAI iMessage integration for a CrewAI tool and separate listener.
• n8n iMessage integration for the public outbound node and separate reply consumer.
• Windows iMessage API setup for Node.js 22 and PowerShell.

Production checklist

• Store API keys in a secret manager. Never place them in browser code, source control, screenshots, or WebSocket request logs.
• Add reconnect behavior with bounded backoff and duplicate suppression.
• Treat accepted, failed, not-confirmed, delivered, read, and replied as different states.
• Persist provider message IDs and your own tenant-safe correlation IDs.
• Isolate routes by tenant and stop when ownership is ambiguous.
• Send only to opted-in recipients and honor suppression, complaint, and acceptable-use rules.
• Minimize message retention and keep customer content out of analytics events.
• Test disconnect, reconnect, duplicate, delayed reply, and provider failure paths before production traffic.

iMessage API FAQ