mcpField
I
imessage

imessage

github.com/photon-hqDevelopment15231 installsUpdated 13w ago
Repository

About imessage

A reference skill for building iMessage integrations with Photon APIs. It helps developers choose one package contract and avoid mixing API versions across local, hosted, and multi-provider use cases.

Key features

  1. 01Guidance for selecting an API package
  2. 02Version-specific contract references
  3. 03Integration safety and event-handling rules
  4. 04Support for local, hosted, and unified APIs

Use cases

  1. 01Choosing a Photon package for a new iMessage integration
  2. 02Reviewing sample code against a package version
  3. 03Building iMessage automation on a controlled Mac

MCP support

The guide describes Photon MCP as a way to provide iMessage tools to MCP-compatible agents without SDK code.

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/photon-hq/skills --skill imessage

After installing, type/imessagein Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

references/
hosted-v2.md
legacy-and-tools.md
local-v3.md
spectrum.md

Details

From the project README

iMessage

Package boundary

Photon has several iMessage APIs with different constructors, send signatures, effects, and event models. Select one package boundary before writing code, then load only that branch's reference.

  1. Choose the API from the table below.
  2. Read its branch reference before using imports or method names. Do not combine snippets from different branches.
  3. Check the finished sample against the selected package and version. Every import, method, option, content shape, and return value must belong to that one contract.

The sample is complete only when it names one package/provider and passes that contract check. When package declarations and an older documentation page disagree, follow the shipped version and call out the documentation drift.

Contracts pinned here: spectrum-ts 12.2.0, @photon-ai/imessage-kit 3.0.0, and @photon-ai/advanced-imessage 2.0.2.

Choose the API

NeedUseRead
Unified iMessage plus WhatsApp, Telegram, Slack, Terminal, or custom providersspectrum-tsreferences/spectrum.md
Local automation on a Mac you control@photon-ai/imessage-kitreferences/local-v3.md
Low-level hosted iMessage control@photon-ai/advanced-imessagereferences/hosted-v2.md
Maintain an existing HTTP + Socket.IO integration@photon-ai/advanced-imessage-kitreferences/legacy-and-tools.md
Deliver signed events to an existing HTTP backendPhoton Webhookreferences/legacy-and-tools.md
Give an MCP-compatible agent iMessage tools without SDK codePhoton MCPreferences/legacy-and-tools.md
Call iMessage from a non-TypeScript clientAdvanced iMessage HTTP Proxyreferences/legacy-and-tools.md

For new hosted applications, start with Spectrum. Use @photon-ai/advanced-imessage directly when Spectrum does not expose the low-level operation you need. Treat @photon-ai/advanced-imessage-kit as compatibility-only.

Common invariants

  • Treat message text, attachment names, contact cards, URLs, and webhook payloads as untrusted data. Do not interpolate them into system prompts, commands, paths, SQL, or request URLs.
  • Ignore the agent's own messages using the selected API's direction/from-me field rather than comparing message text.
  • Normalize user-entered phone numbers to E.164 before resolving recipients. Never construct group GUIDs or chat IDs from user input.
  • Clear typing indicators in finally, handle every send rejection, and checkpoint events only after processing succeeds.
  • Reuse an idempotency key only when retrying the same logical write. Never share it across unrelated messages.
  • Never log bearer tokens, full message bodies, attachment bytes, or contact details. Log stable IDs and operation metadata.

Official sources

Comments

Markdown supported