Agents can chat with humans over iMessage — blue bubbles, tapbacks, read receipts, typing indicators, and media — without owning a dedicated iMessage line. Humans connect to an agent through the shared Inkbox iMessage router, and from then on the conversation behaves like any other thread in their Messages app.

iMessage works differently from SMS in one important way: there is no per-identity iMessage number. Conversations are routed per connection — one human, one agent — over a shared pool of lines that Inkbox manages. Three things follow from that:

• The human always texts first. A recipient connects by texting the router; your agent cannot start an iMessage conversation cold.
• Conversations are the stable key. Agent-facing APIs identify threads by conversation_id and the human's E.164 number. The pool line carrying the conversation is managed by Inkbox and never appears in API responses.
• Shared lines, private conversations. A pool line may carry traffic for many Inkbox customers, but every conversation is private to its connection — your agent identity, in your organization. Inkbox enforces that boundary on every read and write: no one outside your organization can access your conversations, messages, or media, and an identity-scoped API key only ever sees its own identity's threads.

Conversations are 1:1 today — group iMessage threads are not supported.

iMessage reachability is opt-in per identity and defaults to off. Enable it at create time or later:

While an identity is disabled, the router will not connect new recipients to it, sends from it are rejected, and inbound traffic for it is not delivered.

Humans connect by texting a command to the router. Resolve the router number at runtime — it can change, so never hardcode it:

Tell your human: text connect @my-agent to the router number. The router replies, the connection is created, and everything the human sends after that lands in your agent's conversation. A human can be connected to more than one agent at the same time; each connection is its own conversation.

Here's what that looks like from the human's side — they text the connect command to the router, and the router confirms the connection and shares the agent's contact card:

Once a recipient has messaged your agent, list conversations, read messages, and reply. Replies can target the conversation by ID or the recipient by number:

Sending to a number that hasn't connected returns 404 with instructions to relay: have them text the connect command to the router first. If a previously connected recipient disconnects, sends into the old conversation return 409 until they reconnect. Conversation reads carry an assignment_status field ("active" or "released") so you can spot a disconnect before sending, and GET /assignments lists who is currently connected.

Each identity can send up to 100 iMessages per rolling 24-hour window. When the cap is reached, 429 responses carry Retry-After and X-RateLimit-* headers.

Agents can react to any message in the thread — the human's or their own — with the classic tapbacks: love, like, dislike, laugh, emphasize, question.

Tapbacks follow Apple's semantics: one live tapback per sender per message. Sending a second tapback to the same message replaces your first, and when the human swaps or removes theirs, message reads reflect it. Humans can also react with any emoji — those arrive as reaction: "custom" with the emoji in custom_emoji. Custom-emoji tapbacks are receive-only; sends accept the classic six.

Round out the native feel: send a read receipt when your agent has read the thread, show a typing indicator while it works, and attach media.

Expressive send styles are supported too — pass send_style on a send with values like slam, confetti, lasers, or invisible (invisible ink). See the Messages reference for the full list.

iMessage contact rules work like phone and mail rules, with one difference: because there is no per-identity iMessage number, rules are scoped to the agent identity itself.

Each identity has an iMessage filter_mode:

• blacklist (default) — everyone can reach the agent except numbers with an active block rule.
• whitelist — nobody can reach the agent except numbers with an active allow rule.

Blocked inbound messages are stored for review but never reach the agent: identity-scoped API keys never see them, no webhooks fire for them, and outbound sends to a blocked number return 403 before anything leaves Inkbox. Admin API keys and the Inkbox Console can audit blocked rows with is_blocked=true filters. Blocked humans are not told they're blocked — the router gives them the same generic response as for an unknown agent.

Inbound messages and tapbacks are delivered through webhook subscriptions owned by the agent identity (not a mailbox or phone number, since the pool lines aren't yours). The same subscription can also carry the outbound delivery-lifecycle events — imessage.sent, imessage.delivered, and imessage.delivery_failed — so your agent knows when a reply actually landed:

See iMessage webhooks for payload shapes and Signing keys for signature verification.

Inkbox always tries iMessage first. If a recipient isn't reachable over iMessage, delivery can fall back to SMS — the message's service field reports the transport actually used ("imessage", "sms", or "rcs"), and was_downgraded is set when a fallback happened.

• iMessage API reference
• Webhook subscriptions
• Identities