iMessage Inbox
Text an agent on iMessage. It replies in the same chat, and the conversation keeps its context.
Not self-serve yet. iMessage is not generally available to API developers. The flow below is an early preview tied to the m8tes platform and may change. For production API use, trigger agents by email or webhook for now.
Branding. The hosted flow runs on a shared m8tes number. Dedicated numbers exist today, one per app or per end-user, and we provision the line with you: email sales@m8tes.ai.
Hosted Setup (Recommended)
m8tes hosts iMessage for you. There is no server to run:
- Provision a hosted connection. You get the m8tes number to text and a short link code.
- Each person texts the link code once to that number to link their phone.
- They text the number; the message triggers a run; the agent replies in the same chat.
Everyone shares one m8tes number, so inbound is routed to your account by the sender's verified handle (that is what the link code establishes). Rotate the code with client.bridges.regenerate_link_code(bridge.id); unlink a phone with client.bridges.remove_handle(bridge.id, handle_id). provision() raises a 503 if the platform's central server is not configured.
Hosted iMessage links a handle to your account; it does not carry an end-user
user_id. For per-end-user channels in an embedded app, use email instead.
A dedicated number lifts that limit. It routes by number rather than by handle, so it can carry a user_id and give one app or one end-user its own line. Ask us to provision it.
Bind an Agent to a Chat
Give a specific agent one 1:1 chat by its chatGuid. Unbound inbound messages route to your account's Company Agent instead.
Allowed Senders
allowed_imessage_senders takes phone or email handles (formatting and case are normalized). Without a listed sender, inbound messages are silently dropped, so only listed handles can spend a run. Same allowlist model as every inbox channel: see Allowed Senders.
Conversation Continuity
An iMessage chat is an ongoing 1:1 conversation. A follow-up message resumes the same run when the previous one was active in the last 72 hours, so the agent keeps its context. After 72 idle hours a fresh run starts with clean context (the agent can still pull earlier history on demand). A text sent while a run is mid-flight gets a short "still working" acknowledgement instead of a second parallel run.
Only 1:1 chats are supported. Binding a group chat is rejected so an agent never broadcasts replies to a group.
Multi-Tenant iMessage
Self-hosted bridges support user_id scoping per chat, following the shared model in Multi-Tenant Sender Scoping:
Advanced: bring your own BlueBubbles server
Run your own server (your own Apple ID and number) by registering a self-hosted bridge. A bridge is account-scoped and can serve many of your agents, each bound to a 1:1 chat.
Register a bridge
Configure the BlueBubbles webhook to POST new-message events to https://api.m8tes.ai/api/v1/webhooks/inbound/imessage with header X-Webhook-Secret: <webhook_secret>.
owner_handle lets you text your Company Agent the moment the bridge is registered, with no allowlist edit. It is honored only on the default-agent path; an agent bound to a specific chat still uses its own allowlist.
Check the connection
Run this if a bridge stops receiving or replying. It confirms the Mac is reachable and the password is still accepted.
Next: Email Inbox · Webhook Triggers · Memories & Documents