iMessage

The iMessage integration connects your phone number to an agent through the iMessage gateway service. You can text the agent from your iPhone and receive responses as regular iMessage conversations.

Prerequisites

• An iPhone with iMessage enabled.
• An agent already created in Superagent.

How the Gateway Works

The iMessage integration uses a cloud gateway service that bridges iMessage messages to Superagent. When you set up the integration, Superagent connects to the gateway over WebSocket. Incoming messages from your phone number are forwarded to the agent, and the agent's responses are sent back through the gateway to your iMessage conversation.

Unlike Telegram and Slack, iMessage does not support progressive streaming. The agent's full response is sent as a single message once processing is complete. While the agent is working, a typing indicator is shown in the conversation.

Setup

1. Open your agent in Superagent.
2. Open the chat integrations setup and select iMessage.
3. From your iPhone, text /setup to +1 (205) 396-7934. You will receive a reply with a 6-digit code (the code expires after 15 minutes).
4. In the Superagent setup form, enter your phone number in E.164 format (e.g., +15551234567) and the 6-digit code.
5. Configure any additional settings (bot name, show tool calls, session timeout).
6. Click Connect.

Superagent will exchange the code for an authentication token and establish a WebSocket connection to the gateway. If the code has expired, text /setup to the same number again to get a new one.

Limitations

• One integration per phone number -- Only one agent can be connected to iMessage at a time. If you need multiple agents accessible via iMessage, set up a single dedicated iMessage agent and configure it to delegate to your other agents.
• No streaming -- iMessage has a limit on message edits, so responses are sent as complete messages rather than streaming progressively.
• Interactive prompts -- Questions with options are rendered as numbered lists. Reply with the number of your choice or type a free-text answer. Approval requests (e.g., permission to use a tool) are handled via tapback reactions: thumbs up to allow, thumbs down to deny.
• Voice notes -- Voice notes sent to the agent are automatically transcribed (when a speech-to-text provider is configured) and forwarded as text.

How Messages Flow

iPhone user sends iMessage
        |
        v
iMessage Gateway (WebSocket)
        |
        v
Superagent routes to agent session
        |
        v
Agent processes message (tools, skills, etc.)
        |
        v
Complete response sent back via gateway
(typing indicator shown while agent works)

• Text messages are forwarded to the agent.
• Images and file attachments are downloaded and passed to the agent.
• Tapback reactions on the agent's messages are interpreted as interactive responses (thumbs up = allow, thumbs down = deny).
• The agent can react to your messages using tapback reactions (heart, thumbs up, thumbs down, haha, emphasize, question mark) when appropriate.

Sessions

Each iMessage conversation maps to a session in Superagent. The session is visible in the Superagent sidebar, where you can view the full message history.

Send /clear in the iMessage conversation to reset the session. The next message will start a fresh conversation with the agent.

Reconnection

If the WebSocket connection to the gateway is lost (e.g., due to a network interruption), Superagent automatically attempts to reconnect with exponential backoff. Messages sent while the connection is down will be queued by the gateway and delivered once the connection is restored.

Managing the Integration

Once connected, you can manage the integration from the Superagent sidebar:

• Pause / Resume -- Temporarily stop receiving messages without deleting the integration.
• Show Tool Calls -- Toggle visibility of tool invocation messages.
• Session Timeout -- Set an inactivity timeout for automatic session rotation.
• Model and Effort -- Override the AI model or effort level.
• Rename / Delete -- Rename or permanently remove the integration.