> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argentos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# iMessage

> Connect ArgentOS to iMessage on macOS.

## Overview

ArgentOS can send and receive iMessage messages on macOS by interfacing with the built-in Messages.app. This is a macOS-only channel that leverages AppleScript and the Messages framework.

<Warning>
  iMessage integration is in **alpha**. It requires macOS with an active iMessage account and full disk access permissions for the ArgentOS process.
</Warning>

## Prerequisites

* **macOS** (Apple Silicon or Intel)
* An active **iMessage account** signed in to Messages.app
* **Full Disk Access** granted to your terminal or the ArgentOS process
* ArgentOS gateway running

## Setup

<Steps>
  <Step title="Enable Full Disk Access">
    ArgentOS needs to read the Messages database (`~/Library/Messages/chat.db`):

    1. Open **System Settings > Privacy & Security > Full Disk Access**
    2. Add your terminal app (Terminal.app, iTerm2, etc.)
    3. If running as a LaunchAgent, add the node binary
  </Step>

  <Step title="Add the Channel">
    ```bash theme={null}
    argent channels add imessage
    ```
  </Step>
</Steps>

## Configuration

```json theme={null}
{
  "channels": {
    "imessage": {
      "enabled": true,
      "allowedContacts": [],
      "pollInterval": 5000
    }
  }
}
```

### How It Works

1. ArgentOS polls the Messages SQLite database for new incoming messages
2. New messages are forwarded to the agent runtime
3. Agent responses are sent via AppleScript `tell application "Messages"`

## Supported Features

| Feature            | Supported |
| ------------------ | --------- |
| Text messages      | Yes       |
| Images (inbound)   | Partial   |
| Images (outbound)  | No        |
| Group chats        | No        |
| Tapbacks/reactions | No        |
| Read receipts      | No        |

## Known Limitations

<AccordionGroup>
  <Accordion title="macOS only">
    This channel cannot run on Linux or Docker.
  </Accordion>

  <Accordion title="Polling-based detection">
    New message detection depends on polling interval (default 5 seconds).
  </Accordion>

  <Accordion title="No rich media outbound">
    The agent can only send plain text responses.
  </Accordion>

  <Accordion title="Full Disk Access required">
    Without it, the Messages database cannot be read.
  </Accordion>

  <Accordion title="Single account">
    Only works with the iMessage account signed in on the Mac.
  </Accordion>
</AccordionGroup>

## Security Notes

<Danger>
  The Messages database contains your entire iMessage history. Ensure your ArgentOS installation is properly secured, and use `allowedContacts` to restrict which conversations the agent can access.
</Danger>