### JSON-RPC 2.0 Subscribe Request Example

Source: https://github.com/steipete/imsg/blob/main/docs/rpc.md

An example of a JSON-RPC 2.0 request to subscribe to messages for a specific chat. This shows how to initiate a subscription.

```json
{"jsonrpc":"2.0","id":"2","method":"watch.subscribe","params":{"chat_id":1}}
```

--------------------------------

### JSON-RPC 2.0 Notification Example

Source: https://github.com/steipete/imsg/blob/main/docs/rpc.md

An example of a JSON-RPC 2.0 notification received after subscribing. This demonstrates the format for real-time message updates.

```json
{"jsonrpc":"2.0","method":"message","params":{"subscription":2,"message":{...}}}
```

--------------------------------

### JSON-RPC 2.0 Request Example

Source: https://github.com/steipete/imsg/blob/main/docs/rpc.md

An example of a JSON-RPC 2.0 request to list chats with a limit. This demonstrates the basic structure including version, ID, method, and parameters.

```json
{"jsonrpc":"2.0","id":"1","method":"chats.list","params":{"limit":10}}
```

--------------------------------

### JSON-RPC 2.0 Response Example

Source: https://github.com/steipete/imsg/blob/main/docs/rpc.md

An example of a JSON-RPC 2.0 response for a successful 'chats.list' request. It includes the version, the original ID, and the result payload.

```json
{"jsonrpc":"2.0","id":"1","result":{"chats":[...]}}
```

--------------------------------

### Start RPC Server (Bash)

Source: https://context7.com/steipete/imsg/llms.txt

Starts the JSON-RPC 2.0 server for imsg. The server listens for requests on stdin and writes responses to stdout, facilitating programmatic control without a daemon or TCP port. Each request/response is a single JSON object on one line.

```bash
# Start the RPC server
imsg rpc

# The server reads JSON-RPC requests from stdin and writes responses to stdout
# Each request/response is a single JSON object on one line
```

--------------------------------

### Build and Install imsg CLI

Source: https://github.com/steipete/imsg/blob/main/README.md

This command builds the imsg CLI binary using the provided Makefile. The resulting executable will be located at ./bin/imsg.

```bash
make build
# binary at ./bin/imsg
```

--------------------------------

### Sending iMessage to a Group using Chat GUID

Source: https://github.com/steipete/imsg/blob/main/docs/groups.md

This command sends an iMessage to a group using its globally unique identifier (GUID). This method is also portable and useful when the GUID is known. It requires the 'imsg' tool.

```bash
imsg send --chat-guid <guid>
```

--------------------------------

### Send Message Request/Response (JSON)

Source: https://context7.com/steipete/imsg/llms.txt

Provides examples for sending messages via the RPC server, including sending to a phone number, sending with an attachment, and sending to a group chat using either its ID or identifier. It also shows an example of an error response for invalid parameters.

```json
// Request - Send to phone number
{"jsonrpc":"2.0","id":"7","method":"send","params":{"to":"+14155551212","text":"Hello from RPC!","service":"imessage"}}

// Response
{"jsonrpc":"2.0","id":"7","result":{"ok":true}}

// Request - Send with attachment
{"jsonrpc":"2.0","id":"8","method":"send","params":{"to":"+14155551212","text":"Check this","file":"/Users/me/Desktop/photo.jpg"}}

// Request - Send to group chat by ID
{"jsonrpc":"2.0","id":"9","method":"send","params":{"chat_id":2,"text":"Hello group!"}}

// Request - Send to group chat by identifier
{"jsonrpc":"2.0","id":"10","method":"send","params":{"chat_identifier":"iMessage;+;chat1234567890","text":"Portable group message"}}

// Error response example
{"jsonrpc":"2.0","id":"11","error":{"code":-32602,"message":"Invalid params","data":"text or file is required"}}
```

--------------------------------

### RPC Server

Source: https://context7.com/steipete/imsg/llms.txt

Starts a JSON-RPC 2.0 server that communicates over standard input and output. This server handles both message watching and sending without needing a separate daemon or TCP port.

```APIDOC
## RPC Server

Runs a JSON-RPC 2.0 server over stdin/stdout for programmatic control. One process handles both message watching and sending without requiring a daemon or TCP port.

### Method

```bash
imsg rpc
```

### Description

The server reads JSON-RPC requests from stdin and writes responses to stdout. Each request/response is a single JSON object on one line.
```

--------------------------------

### Stream new messages in real-time

Source: https://github.com/steipete/imsg/blob/main/README.md

Continuously streams new messages for a specified chat, with options for attachments, debounce interval, and filtering. The `--chat-id` specifies the target chat. `--attachments` includes metadata for attachments. `--debounce` sets a delay for event processing. Filtering options like `--participants`, `--start`, and `--end` can be applied. The `--json` flag formats the output as JSON.

```bash
# live stream a chat
imsg watch --chat-id 1 --attachments --debounce 250ms
```

--------------------------------

### Sending Messages to Groups

Source: https://github.com/steipete/imsg/blob/main/docs/groups.md

This section details how to send messages to iMessage groups using different identifiers. It covers using the chat ID, chat identifier, or chat GUID.

```APIDOC
## Sending Messages to Groups

### Description
Send messages to iMessage groups using their unique identifiers.

### Method
POST

### Endpoint
`/steipete/imsg/send`

### Parameters
#### Query Parameters
- **chat-id** (integer) - Required - The ROWID of the chat.
- **chat-identifier** (string) - Required - The group handle (e.g., `iMessage;+;chat1234567890`).
- **chat-guid** (string) - Required - The group GUID.
- **message** (string) - Required - The content of the message to send.

#### Request Body
This endpoint does not use a request body for sending messages. Parameters are passed via query parameters.

### Request Example
```bash
imsg send --chat-id 12345
imsg send --chat-identifier "iMessage;+;chat1234567890"
imsg send --chat-guid "some-guid-string"
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.
- **message_id** (string) - The ID of the sent message.

#### Response Example
```json
{
  "status": "success",
  "message_id": "msg_abc123"
}
```
```

--------------------------------

### View message history with filters

Source: https://github.com/steipete/imsg/blob/main/README.md

Retrieves message history for a specific chat, with options to filter by attachments, participants, start/end times, and output format. The `--chat-id` is mandatory. The `--attachments` flag includes attachment metadata. Filtering by `--participants`, `--start`, and `--end` allows for precise data retrieval. The `--json` flag outputs results in JSON format.

```bash
# last 10 messages in chat 1 with attachments
imsg history --chat-id 1 --limit 10 --attachments

# filter by date and emit JSON
imsg history --chat-id 1 --start 2025-01-01T00:00:00Z --json
```

--------------------------------

### Run imsg tests

Source: https://github.com/steipete/imsg/blob/main/README.md

Executes the test suite for the imsg project. This command may apply a small patch to SQLite.swift to manage a SwiftPM warning related to PrivacyInfo.xcprivacy.

```bash
make test
```

--------------------------------

### Get Message History

Source: https://github.com/steipete/imsg/blob/main/README.md

Retrieves the message history for a specific chat, with options for filtering and including attachments.

```APIDOC
## GET /history

### Description
Retrieves the message history for a specific chat. Supports filtering by participants, date range, and inclusion of attachment metadata. Output can be formatted as JSON.

### Method
GET

### Endpoint
/history

### Query Parameters
- **chat_id** (integer) - Required - The ID of the chat to retrieve history from.
- **limit** (integer) - Optional - The maximum number of messages to return.
- **attachments** (boolean) - Optional - If true, includes metadata for attachments.
- **participants** (string) - Optional - Comma-separated list of participants to filter messages by.
- **start** (string) - Optional - ISO 8601 timestamp to filter messages starting from.
- **end** (string) - Optional - ISO 8601 timestamp to filter messages ending at.
- **json** (boolean) - Optional - If true, output will be in JSON format.

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier for the message.
- **chat_id** (integer) - The ID of the chat this message belongs to.
- **guid** (string) - The globally unique identifier for the message.
- **reply_to_guid** (string) - The GUID of the message this message is a reply to (if applicable).
- **sender** (string) - The sender's identifier (e.g., phone number).
- **is_from_me** (boolean) - True if the message was sent by the current user.
- **text** (string) - The content of the message.
- **created_at** (string) - ISO 8601 timestamp when the message was created.
- **attachments** (array) - An array of attachment metadata objects (if `attachments` is true). Each object contains fields like `filename`, `mime_type`, `original_path`, `missing`.
- **reactions** (array) - An array of reaction objects (read-only metadata).

#### Response Example
```json
[
  {
    "id": 123,
    "chat_id": 1,
    "guid": "A1B2C3D4-E5F6-7890-1234-567890ABCDEF",
    "reply_to_guid": null,
    "sender": "+11234567890",
    "is_from_me": false,
    "text": "Hello there!",
    "created_at": "2023-10-27T10:05:00Z",
    "attachments": [
      {
        "filename": "image.jpg",
        "transfer_name": "image.jpg",
        "uti": "public.jpeg",
        "mime_type": "image/jpeg",
        "total_bytes": 102400,
        "is_sticker": false,
        "original_path": "/Users/user/Library/Messages/Attachments/...",
        "missing": false
      }
    ],
    "reactions": []
  }
]
```
```

--------------------------------

### Lint and format imsg code

Source: https://github.com/steipete/imsg/blob/main/README.md

Applies linting and formatting rules to the imsg project's codebase. `make lint` checks for code style issues, while `make format` automatically corrects them.

```bash
make lint
make format
```

--------------------------------

### chats.list

Source: https://github.com/steipete/imsg/blob/main/docs/rpc.md

Retrieves a list of chats. Supports pagination with a limit parameter.

```APIDOC
## POST /rpc

### Description
Retrieves a list of chats, optionally limited by a specified number.

### Method
POST

### Endpoint
/rpc

### Parameters
#### Query Parameters
- **limit** (int) - Optional - The maximum number of chats to return. Defaults to 20.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "chats.list",
  "params": {
    "limit": 10
  }
}
```

### Response
#### Success Response (200)
- **chats** (array) - An array of Chat objects.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "chats": [
      {
        "id": 1,
        "name": "Example Chat",
        "identifier": "example@example.com",
        "service": "imessage",
        "last_message_at": "2023-10-27T10:00:00Z",
        "is_group": false
      }
    ]
  }
}
```
```

--------------------------------

### watch.subscribe and watch.unsubscribe

Source: https://github.com/steipete/imsg/blob/main/docs/rpc.md

Allows subscribing to real-time message notifications for a chat or specific criteria, and unsubscribing from them.

```APIDOC
## POST /rpc

### Description
Manages real-time message subscriptions. `watch.subscribe` allows you to receive notifications for new messages based on various criteria. `watch.unsubscribe` stops these notifications.

### Method
POST

### Endpoint
/rpc

### Parameters
#### `watch.subscribe` Parameters
- **chat_id** (int) - Optional - Subscribe to messages in a specific chat.
- **since_rowid** (int) - Optional - Subscribe to messages with a rowid greater than this value.
- **participants** (array) - Optional - Subscribe to messages involving these participants.
- **start** (ISO8601) - Optional - Subscribe to messages sent after this time.
- **end** (ISO8601) - Optional - Subscribe to messages sent before this time.
- **attachments** (bool) - Optional - If true, only subscribe to messages with attachments. Defaults to false.

#### `watch.unsubscribe` Parameters
- **subscription** (int) - Required - The ID of the subscription to unsubscribe from.

### Request Example (Subscribe)
```json
{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "watch.subscribe",
  "params": {
    "chat_id": 1
  }
}
```

### Request Example (Unsubscribe)
```json
{
  "jsonrpc": "2.0",
  "id": "3",
  "method": "watch.unsubscribe",
  "params": {
    "subscription": 1
  }
}
```

### Response
#### Success Response (200) for `watch.subscribe`
- **subscription** (int) - The ID of the newly created subscription.

#### Success Response (200) for `watch.unsubscribe`
- **ok** (bool) - True if the unsubscribe operation was successful.

#### Response Example (Subscribe)
```json
{
  "jsonrpc": "2.0",
  "id": "2",
  "result": {
    "subscription": 1
  }
}
```

#### Response Example (Unsubscribe)
```json
{
  "jsonrpc": "2.0",
  "id": "3",
  "result": {
    "ok": true
  }
}
```

### Notifications
- **message** - Received when a new message arrives matching a subscription.
  - **subscription** (int) - The ID of the subscription this message belongs to.
  - **message** (Message) - The received Message object.

### Notification Example
```json
{
  "jsonrpc": "2.0",
  "method": "message",
  "params": {
    "subscription": 1,
    "message": {
      "id": 124,
      "chat_id": 1,
      "guid": "another-guid",
      "sender": "Jane Doe",
      "is_from_me": false,
      "text": "Hi there!",
      "created_at": "2023-10-27T11:00:00Z",
      "attachments": [],
      "chat_identifier": "example@example.com",
      "chat_name": "Example Chat",
      "is_group": false
    }
  }
}
```
```

--------------------------------

### Subscribe to Messages Request/Response/Notification (JSON)

Source: https://context7.com/steipete/imsg/llms.txt

Details the process of subscribing to real-time message notifications. This includes the request to subscribe, the response containing a subscription ID, and the format of incoming notifications. It also covers unsubscribing and subscribing from a specific row ID.

```json
// Request - Subscribe to all messages in a chat
{"jsonrpc":"2.0","id":"4","method":"watch.subscribe","params":{"chat_id":1,"attachments":true}}

// Response
{"jsonrpc":"2.0","id":"4","result":{"subscription":1}}

// Notifications (sent automatically when new messages arrive)
{"jsonrpc":"2.0","method":"message","params":{"subscription":1,"message":{"id":12346,"chat_id":1,"guid":"DEF456","sender":"+15551234567","is_from_me":false,"text":"New message!","created_at":"2025-01-15T10:35:00.000Z","attachments":[],"reactions":[]}}}

// Request - Subscribe starting from a specific row ID
{"jsonrpc":"2.0","id":"5","method":"watch.subscribe","params":{"since_rowid":12345}}

// Request - Unsubscribe
{"jsonrpc":"2.0","id":"6","method":"watch.unsubscribe","params":{"subscription":1}}

// Response
{"jsonrpc":"2.0","id":"6","result":{"ok":true}}
```

--------------------------------

### MessageStore: Read Messages Database

Source: https://context7.com/steipete/imsg/llms.txt

The MessageStore class provides methods to access and query the Messages SQLite database. It supports reading chats, messages, attachments, and reactions. Initialize with a default or custom database path.

```swift
import IMsgCore

// Initialize with default Messages database path
let store = try MessageStore()
// Or specify a custom path
let store = try MessageStore(path: "/path/to/chat.db")

// List recent chats
let chats = try store.listChats(limit: 20)
for chat in chats {
    print("[\(chat.id)] \(chat.name) - \(chat.identifier)")
    print("  Service: \(chat.service), Last: \(chat.lastMessageAt)")
}

// Get chat details
if let info = try store.chatInfo(chatID: 1) {
    print("Chat: \(info.name)")
    print("Identifier: \(info.identifier)")
    print("GUID: \(info.guid)")
}

// Get chat participants
let participants = try store.participants(chatID: 1)
print("Participants: \(participants.joined(separator: ", "))")

// Get message attachments
let attachments = try store.attachments(for: messageRowID)
for attachment in attachments {
    print("File: \(attachment.transferName)")
    print("MIME: \(attachment.mimeType), Size: \(attachment.totalBytes)")
    print("Path: \(attachment.originalPath), Missing: \(attachment.missing)")
}

// Get reactions on a message
let reactions = try store.reactions(for: messageRowID)
for reaction in reactions {
    print("\(reaction.sender) reacted with \(reaction.reactionType.emoji)")
}
```

--------------------------------

### Send iMessage or SMS with attachments

Source: https://github.com/steipete/imsg/blob/main/README.md

Sends a message via iMessage or SMS to a specified recipient. The `--to` flag indicates the recipient's handle. `--text` provides the message content. `--file` attaches a file to the message. `--service` specifies the messaging service (imessage, sms, or auto). `--region` helps with phone number normalization.

```bash
# send a picture
imsg send --to "+14155551212" --text "hi" --file ~/Desktop/pic.jpg --service imessage
```

--------------------------------

### chats.list Method

Source: https://context7.com/steipete/imsg/llms.txt

Lists recent conversations with participant information. This method is useful for retrieving an overview of recent chats and their associated details.

```APIDOC
## chats.list Method

Lists recent conversations with participant information.

### Method

```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "chats.list",
  "params": {
    "limit": 10
  }
}
```

### Parameters

#### Query Parameters

- **limit** (integer) - Optional - The maximum number of recent chats to return.

### Response

#### Success Response (200)

- **chats** (array) - An array of chat objects, each containing details like id, identifier, guid, name, service, last_message_at, participants, and is_group.

#### Response Example

```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "chats": [
      {
        "id": 1,
        "identifier": "+15551234567",
        "guid": "iMessage;-;+15551234567",
        "name": "John Doe",
        "service": "iMessage",
        "last_message_at": "2025-01-15T10:30:00.000Z",
        "participants": [
          "+15551234567"
        ],
        "is_group": false
      },
      {
        "id": 2,
        "identifier": "iMessage;+;chat12345",
        "guid": "iMessage;+;chat12345",
        "name": "Family Group",
        "service": "iMessage",
        "last_message_at": "2025-01-15T09:15:00.000Z",
        "participants": [
          "+15551234567",
          "+15559876543"
        ],
        "is_group": true
      }
    ]
  }
}
```
```

--------------------------------

### List Chats Request/Response (JSON)

Source: https://context7.com/steipete/imsg/llms.txt

Demonstrates the JSON structure for requesting a list of recent conversations and the expected response format. The request includes an optional limit for the number of chats returned. The response provides details for each chat, including its ID, participants, and last message timestamp.

```json
// Request
{"jsonrpc":"2.0","id":"1","method":"chats.list","params":{"limit":10}}

// Response
{"jsonrpc":"2.0","id":"1","result":{"chats":[
  {"id":1,"identifier":"+15551234567","guid":"iMessage;-;+15551234567","name":"John Doe","service":"iMessage","last_message_at":"2025-01-15T10:30:00.000Z","participants":["+15551234567"],"is_group":false},
  {"id":2,"identifier":"iMessage;+;chat123456","guid":"iMessage;+;chat123456","name":"Family Group","service":"iMessage","last_message_at":"2025-01-15T09:15:00.000Z","participants":["+15551234567","+15559876543"],"is_group":true}
]}}
```

--------------------------------

### Send Message

Source: https://github.com/steipete/imsg/blob/main/README.md

Sends an iMessage or SMS with optional text and file attachments.

```APIDOC
## POST /send

### Description
Sends an iMessage or SMS to a specified recipient. Supports sending text content and file attachments. The service can be explicitly chosen or auto-detected.

### Method
POST

### Endpoint
/send

### Query Parameters
- **to** (string) - Required - The recipient's phone number or identifier.
- **text** (string) - Optional - The text content of the message.
- **file** (string) - Optional - The path to the file attachment.
- **service** (string) - Optional - The messaging service to use ('imessage', 'sms', or 'auto'). Defaults to 'auto'.
- **region** (string) - Optional - The region code (e.g., 'US') for phone number normalization. Defaults to 'US'.

### Request Example
```bash
imsg send --to "+14155551212" --text "Hello from the CLI!" --file "/path/to/your/image.png" --service imessage
```

### Response
#### Success Response (200)
Indicates the message was successfully sent. The response body might be empty or contain a confirmation message.

#### Response Example
```json
{
  "status": "sent",
  "message_id": "some_unique_id"
}
```
```

--------------------------------

### Sending iMessage to a Group using Chat Identifier

Source: https://github.com/steipete/imsg/blob/main/docs/groups.md

This command sends an iMessage to a group using its chat identifier (handle). This method is portable across different iMessage databases. It relies on the 'imsg' tool and the group's handle.

```bash
imsg send --chat-identifier <handle>
```

--------------------------------

### List recent conversations

Source: https://github.com/steipete/imsg/blob/main/README.md

Lists recent conversations with an optional limit and JSON output. The `--limit` flag controls the number of conversations shown, and `--json` formats the output as JSON.

```bash
# list 5 chats
imsg chats --limit 5

# list chats as JSON
imsg chats --limit 5 --json
```

--------------------------------

### List Chats

Source: https://github.com/steipete/imsg/blob/main/README.md

Lists recent conversations with optional limit and JSON output.

```APIDOC
## GET /chats

### Description
Lists recent conversations, with options to limit the number of results and format the output as JSON.

### Method
GET

### Endpoint
/chats

### Query Parameters
- **limit** (integer) - Optional - The maximum number of chats to return.
- **json** (boolean) - Optional - If true, output will be in JSON format.

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier for the chat.
- **name** (string) - The name of the chat (if available).
- **identifier** (string) - The primary identifier for the chat (e.g., phone number or email).
- **service** (string) - The messaging service used (e.g., 'imessage', 'sms').
- **last_message_at** (string) - Timestamp of the last message in the chat.

#### Response Example
```json
[
  {
    "id": 1,
    "name": "Alice",
    "identifier": "+11234567890",
    "service": "imessage",
    "last_message_at": "2023-10-27T10:00:00Z"
  }
]
```
```

--------------------------------

### MessageSender: Send Messages via AppleScript

Source: https://context7.com/steipete/imsg/llms.txt

MessageSender facilitates sending messages through the Messages.app using AppleScript. It handles recipient normalization, attachment staging, and supports sending text, attachments, and messages to group chats via iMessage or SMS.

```swift
import IMsgCore

let sender = MessageSender()

// Send text to phone number
let options = MessageSendOptions(
    recipient: "+14155551212",
    text: "Hello from Swift!",
    service: .imessage,
    region: "US"
)
try sender.send(options)

// Send with attachment
let attachmentOptions = MessageSendOptions(
    recipient: "+14155551212",
    text: "Check out this photo",
    attachmentPath: "~/Desktop/photo.jpg",
    service: .imessage
)
try sender.send(attachmentOptions)

// Send to group chat
let groupOptions = MessageSendOptions(
    recipient: "",
    text: "Hello everyone!",
    chatIdentifier: "iMessage;+;chat1234567890"
)
try sender.send(groupOptions)

// Send via SMS
let smsOptions = MessageSendOptions(
    recipient: "+14155551212",
    text: "SMS message",
    service: .sms
)
try sender.send(smsOptions)
```

--------------------------------

### Swift Structures for iMessage Data

Source: https://context7.com/steipete/imsg/llms.txt

Defines Swift structures for representing iMessage data like chats, messages, attachments, and reactions. These structures support Codable for easy JSON serialization and deserialization, making them suitable for data exchange and storage.

```swift
import IMsgCore

// Chat represents a conversation
struct Chat {
    let id: Int64              // Database row ID
    let identifier: String     // Phone/email or group handle
    let name: String           // Display name
    let service: String        // "iMessage" or "SMS"
    let lastMessageAt: Date    // Timestamp of last message
}

// Message represents a single message
struct Message {
    let rowID: Int64           // Database row ID
    let chatID: Int64          // Parent chat ID
    let guid: String           // Unique message identifier
    let replyToGUID: String?   // For thread replies
    let sender: String         // Sender phone/email
    let text: String           // Message body
    let date: Date             // Timestamp
    let isFromMe: Bool         // Sent vs received
    let service: String        // iMessage or SMS
    let attachmentsCount: Int  // Number of attachments
}

// AttachmentMeta provides attachment details
struct AttachmentMeta {
    let filename: String       // Database filename
    let transferName: String   // Original filename
    let uti: String            // Uniform Type Identifier
    let mimeType: String       // MIME type
    let totalBytes: Int64      // File size
    let isSticker: Bool        // Sticker flag
    let originalPath: String   // Resolved file path
    let missing: Bool          // File exists check
}

// Reaction represents a tapback or emoji reaction
struct Reaction {
    let rowID: Int64
    let reactionType: ReactionType  // .love, .like, .dislike, .laugh, .emphasis, .question, .custom(String)
    let sender: String
    let isFromMe: Bool
    let date: Date
    let associatedMessageID: Int64
}

// ReactionType enum
enum ReactionType {
    case love      // 2000 - Heart
    case like      // 2001 - Thumbs up
    case dislike   // 2002 - Thumbs down
    case laugh     // 2003 - Ha ha
    case emphasis  // 2004 - Exclamation
    case question  // 2005 - Question mark
    case custom(String)  // 2006 - Custom emoji

    var emoji: String  // Returns the emoji character
    var name: String   // Returns human-readable name
}
```

--------------------------------

### Watch for New Messages

Source: https://github.com/steipete/imsg/blob/main/README.md

Streams new messages in real-time, with options for filtering and including attachments.

```APIDOC
## GET /watch

### Description
Streams new incoming messages in real-time. Supports filtering by chat ID, since a specific message row ID, debounce interval, participants, and date range. Attachment metadata can be included, and output can be formatted as JSON.

### Method
GET

### Endpoint
/watch

### Query Parameters
- **chat_id** (integer) - Optional - The ID of the chat to watch. If omitted, watches all chats.
- **since_rowid** (integer) - Optional - Watch for messages with a row ID greater than this value.
- **debounce** (string) - Optional - Time duration (e.g., '250ms') to debounce events.
- **attachments** (boolean) - Optional - If true, includes metadata for attachments.
- **participants** (string) - Optional - Comma-separated list of participants to filter messages by.
- **start** (string) - Optional - ISO 8601 timestamp to filter messages starting from.
- **end** (string) - Optional - ISO 8601 timestamp to filter messages ending at.
- **json** (boolean) - Optional - If true, output will be in JSON format.

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier for the message.
- **chat_id** (integer) - The ID of the chat this message belongs to.
- **guid** (string) - The globally unique identifier for the message.
- **reply_to_guid** (string) - The GUID of the message this message is a reply to (if applicable).
- **sender** (string) - The sender's identifier (e.g., phone number).
- **is_from_me** (boolean) - True if the message was sent by the current user.
- **text** (string) - The content of the message.
- **created_at** (string) - ISO 8601 timestamp when the message was created.
- **attachments** (array) - An array of attachment metadata objects (if `attachments` is true). Each object contains fields like `filename`, `mime_type`, `original_path`, `missing`.
- **reactions** (array) - An array of reaction objects (read-only metadata).

#### Response Example
```json
[
  {
    "id": 124,
    "chat_id": 1,
    "guid": "F1E2D3C4-B5A6-7890-1234-567890ABCDEF",
    "reply_to_guid": "A1B2C3D4-E5F6-7890-1234-567890ABCDEF",
    "sender": "+10987654321",
    "is_from_me": false,
    "text": "Got it!",
    "created_at": "2023-10-27T10:10:00Z",
    "attachments": [],
    "reactions": []
  }
]
```
```

--------------------------------

### watch.subscribe Method

Source: https://context7.com/steipete/imsg/llms.txt

Subscribes to real-time message notifications. It returns a subscription ID and automatically sends notifications as new messages arrive. Supports unsubscribing.

```APIDOC
## watch.subscribe Method

Subscribes to real-time message notifications. Returns a subscription ID and sends notifications as messages arrive.

### Method

```json
{
  "jsonrpc": "2.0",
  "id": "4",
  "method": "watch.subscribe",
  "params": {
    "chat_id": 1,
    "attachments": true
  }
}
```

### Parameters

#### Query Parameters

- **chat_id** (integer) - Optional - Subscribe to messages in a specific chat.
- **attachments** (boolean) - Optional - Include attachment information in notifications.
- **since_rowid** (integer) - Optional - Subscribe to messages starting from a specific row ID.

### Request Example

// Request - Subscribe to all messages in a chat
```json
{
  "jsonrpc": "2.0",
  "id": "4",
  "method": "watch.subscribe",
  "params": {
    "chat_id": 1,
    "attachments": true
  }
}
```

// Request - Subscribe starting from a specific row ID
```json
{
  "jsonrpc": "2.0",
  "id": "5",
  "method": "watch.subscribe",
  "params": {
    "since_rowid": 12345
  }
}
```

// Request - Unsubscribe
```json
{
  "jsonrpc": "2.0",
  "id": "6",
  "method": "watch.unsubscribe",
  "params": {
    "subscription": 1
  }
}
```

### Response

#### Success Response (200)

- **subscription** (integer) - The ID of the created subscription.
- **ok** (boolean) - Indicates if the unsubscribe operation was successful.

#### Response Example

// Subscribe Response
```json
{
  "jsonrpc": "2.0",
  "id": "4",
  "result": {
    "subscription": 1
  }
}
```

// Unsubscribe Response
```json
{
  "jsonrpc": "2.0",
  "id": "6",
  "result": {
    "ok": true
  }
}
```

#### Notifications

// Notifications (sent automatically when new messages arrive)
```json
{
  "jsonrpc": "2.0",
  "method": "message",
  "params": {
    "subscription": 1,
    "message": {
      "id": 12346,
      "chat_id": 1,
      "guid": "DEF456",
      "sender": "+15551234567",
      "is_from_me": false,
      "text": "New message!",
      "created_at": "2025-01-15T10:35:00.000Z",
      "attachments": [],
      "reactions": []
    }
  }
}
```
```

--------------------------------

### send Method

Source: https://context7.com/steipete/imsg/llms.txt

Sends messages to individuals or groups. Supports sending text messages, messages with attachments, and targeting recipients by phone number, chat ID, or chat identifier.

```APIDOC
## send Method

Sends messages to individuals or groups.

### Method

```json
{
  "jsonrpc": "2.0",
  "id": "7",
  "method": "send",
  "params": {
    "to": "+14155551212",
    "text": "Hello from RPC!",
    "service": "imessage"
  }
}
```

### Parameters

#### Query Parameters

- **to** (string) - Required - The recipient's phone number or identifier.
- **chat_id** (integer) - Optional - The ID of the group chat to send the message to.
- **chat_identifier** (string) - Optional - The identifier of the group chat to send the message to.
- **text** (string) - Required - The content of the message.
- **file** (string) - Optional - The path to the file to be sent as an attachment.
- **service** (string) - Optional - The messaging service to use (e.g., "imessage"). Defaults to iMessage.

### Request Example

// Request - Send to phone number
```json
{
  "jsonrpc": "2.0",
  "id": "7",
  "method": "send",
  "params": {
    "to": "+14155551212",
    "text": "Hello from RPC!",
    "service": "imessage"
  }
}
```

// Request - Send with attachment
```json
{
  "jsonrpc": "2.0",
  "id": "8",
  "method": "send",
  "params": {
    "to": "+14155551212",
    "text": "Check this",
    "file": "/Users/me/Desktop/photo.jpg"
  }
}
```

// Request - Send to group chat by ID
```json
{
  "jsonrpc": "2.0",
  "id": "9",
  "method": "send",
  "params": {
    "chat_id": 2,
    "text": "Hello group!"
  }
}
```

// Request - Send to group chat by identifier
```json
{
  "jsonrpc": "2.0",
  "id": "10",
  "method": "send",
  "params": {
    "chat_identifier": "iMessage;+;chat1234567890",
    "text": "Portable group message"
  }
}
```

### Response

#### Success Response (200)

- **ok** (boolean) - Indicates if the message was sent successfully.

#### Response Example

```json
{
  "jsonrpc": "2.0",
  "id": "7",
  "result": {
    "ok": true
  }
}
```

#### Error Response Example

```json
{
  "jsonrpc": "2.0",
  "id": "11",
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": "text or file is required"
  }
}
```
```

--------------------------------

### Stream Messages in Real-Time

Source: https://context7.com/steipete/imsg/llms.txt

Watches for new incoming messages using filesystem events on the Messages database. Supports the same filtering options as history with configurable debounce interval.

```APIDOC
## GET /watch

### Description
Watches for new incoming messages using filesystem events on the Messages database. Supports the same filtering options as history with configurable debounce interval.

### Method
GET

### Endpoint
/watch

### Parameters
#### Query Parameters
- **chat-id** (integer) - Optional - The ID of the chat to watch messages from.
- **since-rowid** (integer) - Optional - Resume watching from a specific message row ID.
- **start** (string) - Optional - The start date/time for filtering messages (ISO 8601 format).
- **end** (string) - Optional - The end date/time for filtering messages (ISO 8601 format).
- **participants** (string) - Optional - A comma-separated list of participants to filter messages by.
- **attachments** (boolean) - Optional - If true, includes attachment metadata in the response.
- **debounce** (string) - Optional - The debounce interval for filesystem events (e.g., '250ms').
- **json** (boolean) - Optional - If true, output will be in JSON format.

### Request Example
```bash
imsg watch --chat-id 1 --attachments --debounce 250ms
imsg watch --chat-id 1 --json
imsg watch --since-rowid 12345 --json
imsg watch --chat-id 2 --participants +15551234567 --start 2025-01-15T00:00:00Z
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier for the message.
- **chat_id** (integer) - The ID of the chat the message belongs to.
- **guid** (string) - The global unique identifier for the message.
- **sender** (string) - The sender's identifier (phone number or email).
- **is_from_me** (boolean) - True if the message was sent by the current user.
- **text** (string) - The content of the message.
- **created_at** (string) - The timestamp when the message was created (ISO 8601 format).
- **attachments** (array) - An array of attachment objects, if any.
- **reactions** (array) - An array of reaction objects, if any.

#### Response Example
```json
{
  "id": 12346,
  "chat_id": 1,
  "guid": "DEF456",
  "sender": "+15551234567",
  "is_from_me": false,
  "text": "New message",
  "created_at": "2025-01-15T10:35:00.000Z",
  "attachments": [],
  "reactions": []
}
```
```

--------------------------------

### send

Source: https://github.com/steipete/imsg/blob/main/docs/rpc.md

Sends a message, either directly to a recipient or within a group chat. Supports text and file attachments.

```APIDOC
## POST /rpc

### Description
Sends a message. Can be used for direct messages or messages within existing group chats. Supports text and file attachments, and allows specifying the service and region.

### Method
POST

### Endpoint
/rpc

### Parameters
#### Direct Message Parameters
- **to** (string) - Required - The recipient's identifier (e.g., phone number or email).
- **text** (string) - Optional - The text content of the message.
- **file** (string) - Optional - A path to the file to be attached.
- **service** ("imessage"|"sms"|"auto") - Optional - The messaging service to use. Defaults to "auto".
- **region** (string) - Optional - The region code for the recipient.

#### Group Message Parameters
- **chat_id** (int) - Required (one of these is required) - The ID of the group chat.
- **chat_identifier** (string) - Required (one of these is required) - The identifier of the group chat.
- **chat_guid** (string) - Required (one of these is required) - The GUID of the group chat.
- **text** (string) - Optional - The text content of the message.
- **file** (string) - Optional - A path to the file to be attached.

### Request Example (Direct Message)
```json
{
  "jsonrpc": "2.0",
  "id": "4",
  "method": "send",
  "params": {
    "to": "+1234567890",
    "text": "Hello from imsg!"
  }
}
```

### Request Example (Group Message with File)
```json
{
  "jsonrpc": "2.0",
  "id": "5",
  "method": "send",
  "params": {
    "chat_id": 1,
    "file": "/path/to/image.jpg"
  }
}
```

### Response
#### Success Response (200)
- **ok** (bool) - True if the message was sent successfully.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": "4",
  "result": {
    "ok": true
  }
}
```
```

--------------------------------

### List Chats Command (imsg CLI)

Source: https://context7.com/steipete/imsg/llms.txt

Lists recent conversations from the Messages database, ordered by last message time. Supports limiting the number of results and outputting in human-readable or JSON format. The chat ID, display name, identifier, service type, and timestamp are returned.

```bash
# List 5 most recent chats in human-readable format
imsg chats --limit 5

# Output:
# [1] John Doe (+15551234567) last=2025-01-15T10:30:00.000Z
# [2] Family Group (iMessage;+;chat123456) last=2025-01-15T09:15:00.000Z
# [3] jane@example.com (jane@example.com) last=2025-01-14T18:45:00.000Z

# List chats as JSON for programmatic processing
imsg chats --limit 5 --json

# Output (one JSON object per line):
# {"id":1,"name":"John Doe","identifier":"+15551234567","service":"iMessage","last_message_at":"2025-01-15T10:30:00.000Z"}
# {"id":2,"name":"Family Group","identifier":"iMessage;+;chat123456","service":"iMessage","last_message_at":"2025-01-15T09:15:00.000Z"}
```

--------------------------------

### Message History Request/Response (JSON)

Source: https://context7.com/steipete/imsg/llms.txt

Illustrates how to retrieve message history for a specific chat, with options for filtering by attachment presence and date range. The response includes a list of messages, each with details like sender, text, timestamp, and attachments.

```json
// Request - Get last 50 messages from chat with attachments
{"jsonrpc":"2.0","id":"2","method":"messages.history","params":{"chat_id":1,"limit":50,"attachments":true}}

// Response
{"jsonrpc":"2.0","id":"2","result":{"messages":[
  {"id":12345,"chat_id":1,"guid":"ABC123","reply_to_guid":null,"sender":"+15551234567","is_from_me":false,"text":"Hello","created_at":"2025-01-15T10:30:00.000Z","chat_identifier":"+15551234567","chat_guid":"iMessage;-;+15551234567","chat_name":"John Doe","participants":["+15551234567"],"is_group":false,"attachments":[{"filename":"~/Library/Messages/Attachments/.../photo.jpg","transfer_name":"photo.jpg","uti":"public.jpeg","mime_type":"image/jpeg","total_bytes":102400,"is_sticker":false,"original_path":"/Users/me/Library/Messages/Attachments/.../photo.jpg","missing":false}],"reactions":[]}
]}}

// Request - Filter by date range
{"jsonrpc":"2.0","id":"3","method":"messages.history","params":{"chat_id":1,"start":"2025-01-01T00:00:00Z","end":"2025-02-01T00:00:00Z"}}
```