iMessage

Prerequisites

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

How the gateway works

A cloud gateway service bridges iMessage to Gamut. Gamut connects to the gateway over WebSocket; incoming messages from your phone number are forwarded to the agent, and the agent's responses travel back through the gateway to your iMessage conversation.

Unlike Telegram and Slack, iMessage does not support progressive streaming. The full response is sent as a single message once processing is complete, with a typing indicator shown while the agent works.

Setup

1. Open your agent in Gamut.
2. Open the chat integrations setup and select iMessage.
3. From your iPhone, text /setup to +1 (205) 396-7934. The reply contains a 6-digit code that expires after 15 minutes.
4. In the Gamut 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.

Gamut exchanges the code for an authentication token and opens a WebSocket connection to the gateway. If the code has expired, text /setup to the same number again for a new one.

Limitations

• One integration per phone number: Only one agent can be connected to iMessage at a time. For multiple agents, set up a single dedicated iMessage agent and configure it to delegate to the others.
• No streaming: iMessage limits message edits, so responses arrive 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 with tapback reactions: thumbs up to allow, thumbs down to deny.
• Voice notes: Voice notes are transcribed automatically (when a speech-to-text provider is configured) and forwarded as text.

How messages flow

iPhone user sends iMessage
        |
        v
iMessage Gateway (WebSocket)
        |
        v
Gamut 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 with tapbacks (heart, thumbs up, thumbs down, haha, emphasize, question mark) when appropriate.

Sessions

Each iMessage conversation maps to a session in Gamut, visible in the sidebar with full message history. Send /clear in the conversation to reset the session; the next message starts a fresh conversation.

Reconnection

If the WebSocket connection to the gateway drops (e.g., a network interruption), Gamut reconnects automatically with exponential backoff. Messages sent while the connection is down are queued by the gateway and delivered once it is restored.

Managing the integration

Once connected, manage the integration from the Gamut 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 model or effort level.
• Rename / Delete: Rename or permanently remove the integration.